John Mulligan committed 7226e8b

cli: fix up some doc strings

Comments (0)

Files changed (1)

 This module uses tables and functions to compile a 
 command line into a useful structure. There is very
-little *magic* to the cli handling, only basic python
+little *magic* to the cli handling, only limited python
 types are returned from the functions.
 Standard Command Lines
-To get started, create a options table (a list of tuples)
-in the following form: name, short-option, default-value, and
+To get started create a options table. A table contains entries
+which have a name, short option, default value, and help string.
 >>> options = [
 ...     ('signed', 's', None, 'input data is signed'),
 ...     ('tweak', '', [], 'set tweak keyword'),
 ...     ]
-The name of the option will also be used for the long style 
-option. If the short option is an empty string, no short
-version will be available for the option. Using None as a
-default value turns that option into a switch, which does
-not take an argument. If the default is a list, then the
-option takes a value and may be specified more than once,
-each time the option appears in the command it's value 
-will be added to the a list in the processed data.
-If the default is any other value, then the takes a single
-value, if the value is not specified on the command line, 
-the default from the table will be used.
+An entry may be a tuple, dictionary or Option object.
+>>> options = [
+...     {'name': 'signed', 'short':'s', 'default': None, 'help': 'foo bar'},
+...     {'name': 'output', 'short':'o', 'default': '', 'help': 'foo bar'},
+...     ]
+The name of the option is also used for the long option's string. If
+the short option is None or an empty string no short option will be
+available for that option.
+The default value controls both the default value of the option, and
+the type of option on the cli. A string value will be an option that
+requires an argument. A value of None will create an option that
+takes no arguments (true/false flag). A list value will create an
+option that takes arguments an may be specified multiple times.
 Converting a cli into something useful is done by calling
 the parse function.
 the processed options and the remaining arguments respectively.
 The values in the opts dict may be True, False, None or a string.
-Command lines with sub-commands
-Some command lines take an initial keyword which determines the
-real action that the appliaction will take. Additional options
-and arguments can be specified after the keyword.
->>> commands = [
-...     (func1, 'start', start_opts, 'Start the action'),
-...     (func2, 'stop', [], 'Stop the action'),
-...     (func3, 'refresh', [], 'refresh the database'),
-...     ]
->>> func, opts, args = parsecommand(options, commands, sys.argv[1:])
 import getopt as _getopt
 def parse(table, arguments, strict=None):
     """Parse a command line, returns an options dict and an args list.
+    By default parsing is GNU style and options may be specified after
+    arguments.
+    * ``table`` - a list of cli options
+    * ``arguments`` - the argument list to be parsed
+    * ``strict`` - if true, use strict posix style parsing
     if strict:
         getopt = _getopt.getopt