add the "MORE" mode so commands can co-opt user interaction

src/zc/monitor/CHANGES.txt

@@ -2,6 +2,11 @@
 Change History
 ==============
 
+0.2.0 (2009-10-28)
+------------------
+
+- Add the "MORE" mode so commands can co-opt user interaction
+
 0.1.2 (2008-09-15)
 ------------------
 

src/zc/monitor/README.txt

@@ -20,10 +20,10 @@ To see this, we'll create a hello plugin:
 
     >>> def hello(connection, name='world'):
     ...     """Say hello
-    ...     
+    ...
     ...     Provide a name if you're not the world.
     ...     """
-    ...     connection.write("Hi %s, nice to meet ya!\n" % name) 
+    ...     connection.write("Hi %s, nice to meet ya!\n" % name)
 
 and register it:
 
@@ -160,3 +160,51 @@ traceback on the connection.
    Closing the connection:
 
    >>> connection.test_close('test')
+
+
+Command loops
+-------------
+
+Using the "MORE" mode, commands can signal that they want to claim all future
+user input.  We'll implement a silly example to demonstrate how it works.
+
+Here's a command that implements a calculator.
+
+    >>> PROMPT = '.'
+    >>> def calc(connection, *args):
+    ...     if args and args[0] == 'quit':
+    ...         return zc.monitor.QUIT_MARKER
+    ...
+    ...     if args:
+    ...         connection.write(str(eval(''.join(args))))
+    ...         connection.write('\n')
+    ...
+    ...     connection.write(PROMPT)
+    ...     return zc.monitor.MORE_MARKER
+
+If we register this command...
+
+    >>> zope.component.provideUtility(calc,
+    ...     zc.monitor.interfaces.IMonitorPlugin, 'calc')
+
+...we can invoke it and we get a prompt.
+
+    >>> connection = zc.ngi.testing.TextConnection()
+    >>> server = zc.monitor.Server(connection)
+    >>> connection.test_input('calc\n')
+    .
+
+If we then give it more input we get the result plus another prompt.
+
+    >>> connection.test_input('2+2\n')
+    4
+    .
+
+    >>> connection.test_input('4*2\n')
+    8
+    .
+
+Once we're done we can tell the calculator to let us go.
+
+    >>> connection.test_input('quit\n')
+    -> CLOSE

src/zc/monitor/__init__.py

@@ -23,6 +23,7 @@
 
 INTERACTIVE_MARKER = object()
 QUIT_MARKER = object()
+MORE_MARKER = object()
 
 class Server:
 
@@ -36,7 +37,9 @@ def __init__(self, connection):
 
     def handle_input(self, connection, data):
         args = data.strip().split()
-        if not args:
+        if self.mode is MORE_MARKER:
+            command_name = self.last_command[0]
+        elif not args:
             if self.last_command is not None:
                 command_name, args = self.last_command
             else:
@@ -57,9 +60,7 @@ def handle_input(self, connection, data):
                 traceback.print_exc(100, connection)
                 print >> connection, "%s: %s\n" % (v.__class__.__name__, v)
             else:
-                if res is INTERACTIVE_MARKER:
-                    self.mode = res
-                elif res is QUIT_MARKER:
+                if res in (INTERACTIVE_MARKER, QUIT_MARKER, MORE_MARKER):
                     self.mode = res
 
         if self.mode is QUIT_MARKER:
@@ -83,7 +84,7 @@ def start(port):
             # Don't kill the process just because somebody else has our port.
             # This might be a zopectl debug or some other innocuous problem.
             logging.warning(
-                'unable to start z3monitor server because port %d is in use.',
+                'unable to start zc.monitor server because port %d is in use.',
                 port)
             return False
         else:

src/zc/monitor/tests.py

@@ -11,14 +11,11 @@
 # FOR A PARTICULAR PURPOSE.
 #
 ##############################################################################
-import unittest
 
 from zope.testing import doctest
 
 def test_suite():
-    return unittest.TestSuite((
-        doctest.DocFileSuite(
-            'README.txt',
-            ),
-
-        ))
+    return doctest.DocFileSuite(
+        'README.txt',
+        optionflags=doctest.NORMALIZE_WHITESPACE,
+        )