@@ 8,13 8,39 @@
#
"""parse command lines with subcommands
+This module provides various utilities for hooking multiple
+subcommands under a single script. The programmer creates
+a table of commands and then either parses the command
+line and manually dispatches the command, or uses the main(...)
+or launch(...) functions that perform automatic dispatch.
-XXX
-ret = commander.launch(globalopts, cmdtable, args)
+Example:
+ >>> # cmd1 and cmd2 are functions
+ >>> cmdtable = [
+ ... ('name', cmd1, '', [OPTS], 'something helpful'),
+ ... ('other', cmd2, 'alias|alais2', [], 'something helpless'),
+ ... ]
+ >>> ret = commander.launch(OPTS, cmdtable, argv)
+ >>> cmd, opts, args = commander.parse(OPTS, cmdtable, argv)
-cmd, opts, args = commander.parse(globalopts, cmdtable, args)
+The entries in the command table may be tuples, dictionaries,
+or commander.Command objects. As an alternate form of the table
+a dictionary mapping command names to dictionaries may be used.
+
+>>> table = {
+... 'mycommand': {'target':cmd1, 'opts':[], 'help': 'foo bar'},
+... }
+
-XXX
+The parse function parses a command line and returns a
+command object, opts, args triple. The launch command parses
+and then dispatches the command function, it may raise
+a parsing exception or a HelpWanted exception. The programmer
+should catch the exception and print usage if this exception is
+raised. Finally the main function both dispatches and provides
+simple help usage and error handling for cli parsing errors.
+By default, error messages will be written to the standard
+output.
"""
from vanity import cli