Replace .config rather than reconstructing plugins, drivers, and UIs.
[hooke.git] / hooke / command.py
1 # Copyright (C) 2010 W. Trevor King <wking@drexel.edu>
2 #
3 # This file is part of Hooke.
4 #
5 # Hooke is free software: you can redistribute it and/or modify it
6 # under the terms of the GNU Lesser General Public License as
7 # published by the Free Software Foundation, either version 3 of the
8 # License, or (at your option) any later version.
9 #
10 # Hooke is distributed in the hope that it will be useful, but WITHOUT
11 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
12 # or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General
13 # Public License for more details.
14 #
15 # You should have received a copy of the GNU Lesser General Public
16 # License along with Hooke.  If not, see
17 # <http://www.gnu.org/licenses/>.
18
19 """The `command` module provides :class:`Command`\s and
20 :class:`Argument`\s for defining commands.
21
22 It also provides :class:`CommandExit` and subclasses for communicating
23 command completion information between
24 :class:`hooke.engine.CommandEngine`\s and
25 :class:`hooke.ui.UserInterface`\s.
26 """
27
28 import Queue as queue
29 import sys
30 import textwrap
31 import traceback
32
33
34 class CommandExit (Exception):
35     pass
36
37 class Success (CommandExit):
38     pass
39
40 class Exit (Success):
41     """The command requests an end to the interpreter session.
42     """
43     pass
44
45 class Failure (CommandExit):
46     pass
47
48 class UncaughtException (Failure):
49     def __init__(self, exception, traceback_string=None):
50         super(UncaughtException, self).__init__()
51         if traceback_string == None:
52             traceback_string = traceback.format_exc()
53             sys.exc_clear()
54         self.exception = exception
55         self.traceback = traceback_string
56         self.__setstate__(self.__getstate__())
57
58     def __getstate__(self):
59         """Return a picklable representation of the objects state.
60
61         :mod:`pickle`'s doesn't call a :meth:`__init__` when
62         rebuilding a class instance.  To preserve :attr:`args` through
63         a pickle cycle, we use :meth:`__getstate__` and
64         :meth:`__setstate__`.
65
66         See `pickling class instances`_ and `pickling examples`_.
67
68         .. _pickling class instances:
69           http://docs.python.org/library/pickle.html#pickling-and-unpickling-normal-class-instances
70         .. _pickling examples:
71           http://docs.python.org/library/pickle.html#example
72         """
73         return {'exception':self.exception, 'traceback':self.traceback}
74
75     def __setstate__(self, state):
76         """Apply the picklable state from :meth:`__getstate__` to
77         reconstruct the instance.
78         """
79         for key,value in state.items():
80             setattr(self, key, value)
81         self.args = (self.traceback + str(self.exception),)
82
83
84 class Command (object):
85     """One-line command description here.
86
87     >>> c = Command(name='test', help='An example Command.')
88     >>> hooke = None
89     >>> status = c.run(hooke, NullQueue(), PrintQueue(),
90     ...                help=True) # doctest: +REPORT_UDIFF
91     ITEM:
92     Command: test
93     <BLANKLINE>
94     Arguments:
95     <BLANKLINE>
96     help BOOL (bool) Print a help message.
97     <BLANKLINE>
98     An example Command.
99     ITEM:
100     <BLANKLINE>
101     """
102     def __init__(self, name, aliases=None, arguments=[], help='',
103                  plugin=None):
104         # TODO: see_also=[other,command,instances,...]
105         self.name = name
106         if aliases == None:
107             aliases = []
108         self.aliases = aliases
109         self.arguments = [
110             Argument(name='help', type='bool', default=False, count=1,
111                      help='Print a help message.'),
112             ] + arguments
113         self._help = help
114         self.plugin = plugin
115
116     def run(self, hooke, inqueue=None, outqueue=None, **kwargs):
117         """`Normalize inputs and handle <Argument help> before punting
118         to :meth:`_run`.
119         """
120         if inqueue == None:
121             inqueue = NullQueue()
122         if outqueue == None:
123             outqueue = NullQueue()
124         try:
125             params = self.handle_arguments(hooke, inqueue, outqueue, kwargs)
126             if params['help'] == True:
127                 outqueue.put(self.help())
128                 raise(Success())
129             self._run(hooke, inqueue, outqueue, params)
130         except CommandExit, e:
131             if isinstance(e, Failure):
132                 outqueue.put(e)
133                 return 1
134             # other CommandExit subclasses fall through to the end
135         except Exception, e:
136             x = UncaughtException(e)
137             outqueue.put(x)
138             return 1
139         else:
140             e = Success()
141         outqueue.put(e)
142         return 0
143
144     def _run(self, hooke, inqueue, outqueue, params):
145         """This is where the command-specific magic will happen.
146         """
147         pass
148
149     def handle_arguments(self, hooke, inqueue, outqueue, params):
150         """Normalize and validate input parameters (:class:`Argument` values).
151         """
152         for argument in self.arguments:
153             names = [argument.name] + argument.aliases
154             settings = [(name,v) for name,v in params.items() if name in names]
155             num_provided = len(settings)
156             if num_provided == 0:
157                 if argument.optional == True or argument.count == 0:
158                     settings = [(argument.name, argument.default)]
159                 else:
160                     raise Failure('Required argument %s not set.'
161                                   % argument.name)
162             if num_provided > 1:
163                 raise Failure('Multiple settings for %s:\n  %s'
164                     % (argument.name,
165                        '\n  '.join(['%s: %s' % (name,value)
166                                     for name,value in sorted(settings)])))
167             name,value = settings[0]
168             if num_provided == 0:
169                 params[argument.name] = value
170             else:
171                 if name != argument.name:
172                     params.remove(name)
173                     params[argument.name] = value
174             if argument.callback != None:
175                 value = argument.callback(hooke, self, argument, value)
176                 params[argument.name] = value
177             argument.validate(value)
178         return params
179
180     def help(self, name_fn=lambda name:name):
181         """Return a help message describing the `Command`.
182
183         `name_fn(internal_name) -> external_name` gives calling
184         :class:`hooke.ui.UserInterface`\s a means of changing the
185         display names if it wants (e.g. to remove spaces from command
186         line tokens).
187         """
188         name_part = 'Command: %s' % name_fn(self.name)
189         if len(self.aliases) > 0:
190             name_part += ' (%s)' % ', '.join(
191                 [name_fn(n) for n in self.aliases])
192         parts = [name_part]
193         if len(self.arguments) > 0:
194             argument_part = ['Arguments:', '']
195             for a in self.arguments:
196                 argument_part.append(textwrap.fill(
197                         a.help(name_fn),
198                         initial_indent="",
199                         subsequent_indent="    "))
200             argument_part = '\n'.join(argument_part)
201             parts.append(argument_part)
202         parts.append(self._help) # help part
203         return '\n\n'.join(parts)
204
205 class Argument (object):
206     """Structured user input for :class:`Command`\s.
207     
208     TODO: ranges for `count`?
209     """
210     def __init__(self, name, aliases=None, type='string', metavar=None,
211                  default=None, optional=True, count=1,
212                  completion_callback=None, callback=None, help=''):
213         self.name = name
214         if aliases == None:
215             aliases = []
216         self.aliases = aliases
217         self.type = type
218         if metavar == None:
219             metavar = type.upper()
220         self.metavar = metavar
221         self.default = default
222         self.optional = optional
223         self.count = count
224         self.completion_callback = completion_callback
225         self.callback = callback
226         self._help = help
227
228     def __str__(self):
229         return '<%s %s>' % (self.__class__.__name__, self.name)
230
231     def __repr__(self):
232         return self.__str__()
233
234     def help(self, name_fn=lambda name:name):
235         """Return a help message describing the `Argument`.
236
237         `name_fn(internal_name) -> external_name` gives calling
238         :class:`hooke.ui.UserInterface`\s a means of changing the
239         display names if it wants (e.g. to remove spaces from command
240         line tokens).
241         """        
242         parts = ['%s ' % name_fn(self.name)]
243         if self.metavar != None:
244             parts.append('%s ' % self.metavar)
245         parts.extend(['(%s) ' % self.type, self._help])
246         return ''.join(parts)
247
248     def validate(self, value):
249         """If `value` is not appropriate, raise `ValueError`.
250         """
251         pass # TODO: validation
252
253
254 # Useful callbacks
255
256 class StoreValue (object):
257     def __init__(self, value):
258         self.value = value
259     def __call__(self, hooke, command, argument, fragment=None):
260         return self.value
261
262 class NullQueue (queue.Queue):
263     """The :class:`queue.Queue` equivalent of `/dev/null`.
264
265     This is a bottomless pit.  Items go in, but never come out.
266     """
267     def get(self, block=True, timeout=None):
268         """Raise queue.Empty.
269         
270         There's really no need to override the base Queue.get, but I
271         want to know if someone tries to read from a NullQueue.  With
272         the default implementation they would just block silently
273         forever :(.
274         """
275         raise queue.Empty
276
277     def put(self, item, block=True, timeout=None):
278         """Dump an item into the void.
279
280         Block and timeout are meaningless, because there is always a
281         free slot available in a bottomless pit.
282         """
283         pass
284
285 class PrintQueue (NullQueue):
286     """Debugging :class:`NullQueue` that prints items before dropping
287     them.
288     """
289     def put(self, item, block=True, timeout=None):
290         """Print `item` and then dump it into the void.
291         """
292         print 'ITEM:\n%s' % item