X-Git-Url: http://git.tremily.us/?p=hooke.git;a=blobdiff_plain;f=hooke%2Fcommand.py;h=974e3b5e7f121b65d153c517de027f164c74ac11;hp=b6d6b3522bdfcb87c038a3821e3d93a575370255;hb=565f9d7b69d2e4a9ea447d7a50f8f835c3e08642;hpb=b9108c2602cbc3229d651e44886cce3e86bebd19

diff --git a/hooke/command.py b/hooke/command.py
index b6d6b35..974e3b5 100644
--- a/hooke/command.py
+++ b/hooke/command.py
@@ -1,5 +1,28 @@
+# Copyright (C) 2010 W. Trevor King <wking@drexel.edu>
+#
+# This file is part of Hooke.
+#
+# Hooke is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Lesser General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# Hooke is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General
+# Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with Hooke.  If not, see
+# <http://www.gnu.org/licenses/>.
+
 """The `command` module provides :class:`Command`\s and
 :class:`Argument`\s for defining commands.
+
+It also provides :class:`CommandExit` and subclasses for communicating
+command completion information between
+:class:`hooke.engine.CommandEngine`\s and
+:class:`hooke.ui.UserInterface`\s.
 """
 
 import Queue as queue
@@ -14,21 +37,57 @@ class CommandExit (Exception):
 class Success (CommandExit):
     pass
 
+class Exit (Success):
+    """The command requests an end to the interpreter session.
+    """
+    pass
+
 class Failure (CommandExit):
     pass
 
 class UncaughtException (Failure):
-    def __init__(self, exception):
+    def __init__(self, exception, traceback_string=None):
+        super(UncaughtException, self).__init__()
+        if traceback_string == None:
+            traceback_string = traceback.format_exc()
+            sys.exc_clear()
         self.exception = exception
-        self.exc_string = traceback.format_exc()
-        sys.exc_clear()
-        super(UncaughtException, self).__init__(self.exc_string)
+        self.traceback = traceback_string
+        self.__setstate__(self.__getstate__())
+
+    def __getstate__(self):
+        """Return a picklable representation of the objects state.
+
+        :mod:`pickle`'s doesn't call a :meth:`__init__` when
+        rebuilding a class instance.  To preserve :attr:`args` through
+        a pickle cycle, we use :meth:`__getstate__` and
+        :meth:`__setstate__`.
+
+        See `pickling class instances`_ and `pickling examples`_.
+
+        .. _pickling class instances:
+          http://docs.python.org/library/pickle.html#pickling-and-unpickling-normal-class-instances
+        .. _pickling examples:
+          http://docs.python.org/library/pickle.html#example
+        """
+        return {'exception':self.exception, 'traceback':self.traceback}
+
+    def __setstate__(self, state):
+        """Apply the picklable state from :meth:`__getstate__` to
+        reconstruct the instance.
+        """
+        for key,value in state.items():
+            setattr(self, key, value)
+        self.args = (self.traceback + str(self.exception),)
+
 
 class Command (object):
     """One-line command description here.
 
     >>> c = Command(name='test', help='An example Command.')
-    >>> status = c.run(NullQueue(), PrintQueue(), help=True) # doctest: +REPORT_UDIFF
+    >>> hooke = None
+    >>> status = c.run(hooke, NullQueue(), PrintQueue(),
+    ...                help=True) # doctest: +REPORT_UDIFF
     ITEM:
     Command: test
     <BLANKLINE>
@@ -38,18 +97,21 @@ class Command (object):
     <BLANKLINE>
     An example Command.
     ITEM:
-    Success
+    <BLANKLINE>
     """
-    def __init__(self, name, aliases=None, arguments=[], help=''):
+    def __init__(self, name, aliases=None, arguments=[], help='',
+                 plugin=None):
+        # TODO: see_also=[other,command,instances,...]
         self.name = name
         if aliases == None:
             aliases = []
         self.aliases = aliases
         self.arguments = [
             Argument(name='help', type='bool', default=False, count=1,
-                     callback=StoreValue(True), help='Print a help message.'),
+                     help='Print a help message.'),
             ] + arguments
         self._help = help
+        self.plugin = plugin
 
     def run(self, hooke, inqueue=None, outqueue=None, **kwargs):
         """`Normalize inputs and handle <Argument help> before punting
@@ -79,7 +141,7 @@ class Command (object):
         outqueue.put(e)
         return 0
 
-    def _run(self, inqueue, outqueue, params):
+    def _run(self, hooke, inqueue, outqueue, params):
         """This is where the command-specific magic will happen.
         """
         pass
@@ -103,12 +165,14 @@ class Command (object):
                        '\n  '.join(['%s: %s' % (name,value)
                                     for name,value in sorted(settings)])))
             name,value = settings[0]
-            if name != argument.name:
-                params.remove(name)
+            if num_provided == 0:
                 params[argument.name] = value
+            else:
+                if name != argument.name:
+                    params.remove(name)
+                    params[argument.name] = value
             if argument.callback != None:
-                if num_provided > 0:
-                    value = argument.callback(hooke, self, argument, value)
+                value = argument.callback(hooke, self, argument, value)
                 params[argument.name] = value
             argument.validate(value)
         return params
@@ -123,7 +187,8 @@ class Command (object):
         """
         name_part = 'Command: %s' % name_fn(self.name)
         if len(self.aliases) > 0:
-            name_part += ' (%s)' % ', '.join([name_fn(n) for n in aliases])
+            name_part += ' (%s)' % ', '.join(
+                [name_fn(n) for n in self.aliases])
         parts = [name_part]
         if len(self.arguments) > 0:
             argument_part = ['Arguments:', '']