1 # Copyright (C) 2010-2012 W. Trevor King <wking@drexel.edu>
3 # This file is part of Hooke.
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.
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.
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/>.
19 """The `command` module provides :class:`Command`\s and
20 :class:`Argument`\s for defining commands.
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.
34 class CommandExit (Exception):
37 class Success (CommandExit):
41 """The command requests an end to the interpreter session.
45 class Failure (CommandExit):
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()
54 self.exception = exception
55 self.traceback = traceback_string
56 self.__setstate__(self.__getstate__())
58 def __getstate__(self):
59 """Return a picklable representation of the objects state.
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
66 See `pickling class instances`_ and `pickling examples`_.
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
73 return {'exception':self.exception, 'traceback':self.traceback}
75 def __setstate__(self, state):
76 """Apply the picklable state from :meth:`__getstate__` to
77 reconstruct the instance.
79 for key,value in state.items():
80 setattr(self, key, value)
81 self.args = (self.traceback + str(self.exception),)
84 class Command (object):
85 """One-line command description here.
87 >>> c = Command(name='test', help='An example Command.')
89 >>> status = c.run(hooke, NullQueue(), PrintQueue(),
90 ... help=True) # doctest: +REPORT_UDIFF
96 help BOOL (bool) Print a help message.
97 stack BOOL (bool) Add this command to appropriate command stacks.
103 def __init__(self, name, aliases=None, arguments=[], help='',
105 # TODO: see_also=[other,command,instances,...]
109 self.aliases = aliases
111 Argument(name='help', type='bool', default=False, count=1,
112 help='Print a help message.'),
113 Argument(name='stack', type='bool', default=True, count=1,
114 help='Add this command to appropriate command stacks.'),
119 def run(self, hooke, inqueue=None, outqueue=None, **kwargs):
120 """`Normalize inputs and handle <Argument help> before punting
124 inqueue = NullQueue()
126 outqueue = NullQueue()
128 params = self.handle_arguments(hooke, inqueue, outqueue, kwargs)
129 if params['help'] == True:
130 outqueue.put(self.help())
132 self._run(hooke, inqueue, outqueue, params)
133 except CommandExit, e:
134 if isinstance(e, Failure):
137 # other CommandExit subclasses fall through to the end
139 x = UncaughtException(e)
147 def _run(self, hooke, inqueue, outqueue, params):
148 """This is where the command-specific magic will happen.
152 def handle_arguments(self, hooke, inqueue, outqueue, params):
153 """Normalize and validate input parameters (:class:`Argument` values).
155 for argument in self.arguments:
156 names = [argument.name] + argument.aliases
157 settings = [(name,v) for name,v in params.items() if name in names]
158 num_provided = len(settings)
159 if num_provided == 0:
160 if argument.optional == True or argument.count == 0:
161 settings = [(argument.name, argument.default)]
163 raise Failure('Required argument %s not set.'
166 raise Failure('Multiple settings for %s:\n %s'
168 '\n '.join(['%s: %s' % (name,value)
169 for name,value in sorted(settings)])))
170 name,value = settings[0]
171 if num_provided == 0:
172 params[argument.name] = value
174 if name != argument.name:
176 params[argument.name] = value
177 if argument.callback != None:
178 value = argument.callback(hooke, self, argument, value)
179 params[argument.name] = value
180 argument.validate(value)
183 def help(self, name_fn=lambda name:name):
184 """Return a help message describing the `Command`.
186 `name_fn(internal_name) -> external_name` gives calling
187 :class:`hooke.ui.UserInterface`\s a means of changing the
188 display names if it wants (e.g. to remove spaces from command
191 name_part = 'Command: %s' % name_fn(self.name)
192 if len(self.aliases) > 0:
193 name_part += ' (%s)' % ', '.join(
194 [name_fn(n) for n in self.aliases])
196 if len(self.arguments) > 0:
197 argument_part = ['Arguments:', '']
198 for a in self.arguments:
199 argument_part.append(textwrap.fill(
202 subsequent_indent=" "))
203 argument_part = '\n'.join(argument_part)
204 parts.append(argument_part)
205 parts.append(self._help) # help part
206 return '\n\n'.join(parts)
208 class Argument (object):
209 """Structured user input for :class:`Command`\s.
211 TODO: ranges for `count`?
213 def __init__(self, name, aliases=None, type='string', metavar=None,
214 default=None, optional=True, count=1,
215 completion_callback=None, callback=None, help=''):
219 self.aliases = aliases
222 metavar = type.upper()
223 self.metavar = metavar
224 self.default = default
225 self.optional = optional
227 self.completion_callback = completion_callback
228 self.callback = callback
232 return '<%s %s>' % (self.__class__.__name__, self.name)
235 return self.__str__()
237 def help(self, name_fn=lambda name:name):
238 """Return a help message describing the `Argument`.
240 `name_fn(internal_name) -> external_name` gives calling
241 :class:`hooke.ui.UserInterface`\s a means of changing the
242 display names if it wants (e.g. to remove spaces from command
245 parts = ['%s ' % name_fn(self.name)]
246 if self.metavar != None:
247 parts.append('%s ' % self.metavar)
248 parts.extend(['(%s) ' % self.type, self._help])
249 return ''.join(parts)
251 def validate(self, value):
252 """If `value` is not appropriate, raise `ValueError`.
254 pass # TODO: validation
259 class StoreValue (object):
260 def __init__(self, value):
262 def __call__(self, hooke, command, argument, fragment=None):
265 class NullQueue (queue.Queue):
266 """The :class:`queue.Queue` equivalent of `/dev/null`.
268 This is a bottomless pit. Items go in, but never come out.
270 def get(self, block=True, timeout=None):
271 """Raise queue.Empty.
273 There's really no need to override the base Queue.get, but I
274 want to know if someone tries to read from a NullQueue. With
275 the default implementation they would just block silently
280 def put(self, item, block=True, timeout=None):
281 """Dump an item into the void.
283 Block and timeout are meaningless, because there is always a
284 free slot available in a bottomless pit.
288 class PrintQueue (NullQueue):
289 """Debugging :class:`NullQueue` that prints items before dropping
292 def put(self, item, block=True, timeout=None):
293 """Print `item` and then dump it into the void.
295 print 'ITEM:\n%s' % item