pology.subcmd

Package pology :: Module subcmd |

# Module subcmd

Handle subcommands and their parameters.

Subcommands are putting main command into different modes of operation. Main commands with subcommands are typical of package managers, version control systems, etc. This module provides a handler to conveniently load subcommands on demand, and parser to extract and route parameters to them from the command line.

The command line interface consists of having subcommand a free parameter, and a special collector-option to collect parameters for the subcommand:

       $ cmd -a -b -c \  # command and any usual options
             subcmd \    # subcommand
             -s foo \    # subcommand parameter 'foo', without value (flag)
             -s bar:xyz  # subcommand parameter 'bar', with the value 'xyz'

where `-s` is the collector-option, repeated for as many subcommand parameters as needed. The collector-option can be freely positioned in the command line, before or after the subcommand name, and mixed with other options.

The format of subcommand parameter is either `param` for flag parameters, `param:value` for parameters taking a value, or `param:value1,value2,...` for parameters taking a list of values. Instead of, or in addition to using comma-separated string to represent the list, some parameters can be repeated on the command line, and all the values collected to make the list.

Several subcommands may be given too, in which case a each subcommand parameter is routed to every subcommand which expects it. This means that all those subcommands should place the same semantics into the same-named parameter they are using.

Note: For any of the methods in this module, the order of keyword parameters is not guaranteed. Always name them in calls.

Author: Chusslove Illich (Часлав Илић) <caslav.ilic@gmx.net>

License: GPLv3

Classes
| ParamParser Parser for subcommand parameters.
| SubcmdView The view of a particular subcommand in a parameter parser.
| SubcmdError Exception for errors on defining subcommands and parsing their parameters.

Variables
| __package__ = ``'``pology``'``