Python command line parser API

Overview

There is 3 major kinds of objects in the Python API.

Info objects

In a basic usage of the Python API. You shouldn't have to take care of the *Info classes since the build-python.sh will automatically generate a derivated ProgramInfo class populated with all options, subcommands and positional arguments descriptions. The only thing to do is to instanciate this class and give it to a Parser instance.

info = miniappProgramInfo()
parser = Parser(info)

Program usage

The UsageFormat class can be used to tweak usage output

Member Type / Return type Description
lineLength integer Maximum line length (default: 80)
indentString string Indentation character(s)
wrap() string Wrap text according UsageFormat settings
SHORT_TEXT flag Display short usage
ABSTRACT_TEXT flag Display short usage and option abstract description
DETAILED_TEXT flag Display full usage
usage = UsageFormat()
print info.usage(usage)
# display program usage

print info.usage(usage, "sc")
# display sc program sub command usage

Result objects

OptionResult

All options result share a common ancestor OptionResult with the following properties

Member / Method Type / Return type Description
isSet boolean True if the option is present in the command line arguments and if its presence and value is valid
value(...) mixed Value of the option. The returned type depends on the option type
##__call__ mixed A shortcut to call the value(...) method

SwithOptionResult

Result of a switch option. The value() method returns the value of the isSet member

ArgumentOptionResult

Result of a single-argument option. The value() method returns the value of the option argument if the option is present. Otherwise None

MultiArgumentOptionResult

Result of a multi-argument option. The value(...) method returns an array containing the option arguments.

Thus, value(...) (and ##__call__ accept arguments

optionRes.value(2, 3)
// or
optionRes.value( (2, 3) )

will return arguments at index 2 and 3 only

SubcommandResult

Contains an array of OptionResult where the array keys are the option's bound variable name defined by the <prg:variable> node of the XML definition file.

Option values can be accessed by the operator []

subcommand["optionVarName"].value()

As a pseudo member (thanks to the magic method ##__getattr__

subcommand.optionVarName.value()

Or as a pseudo method (thanks to the magic method ##__call__

subcommand.optionVarName()

ProgramResult

The main object returned by the Parser

Parser

Member / Method Type / Return type Description
subcommandName string Main name of the selected subcommand if set. Otherwise None
subcommand SubcommandResult Reference to the selected subcommand result if set. Otherwise None
##__call__ boolean True if the command line argument parsing completes successfully (no error raised)
valueCount() integer Number of positional arguments
operator [key] mixed If key is a number. value of the keyth positional argument.
Otherwise, value of the global option bound to variable key
getMessages(min, max) array Get a list of messages generated during command line argument parsing.
The min and max arguments allow to filter messages by importance (debug, warnings, errors and fatal error)

Options can also be accsssed as in SubcommandResult (by pseudo variable/method)

See also


The program interface definition framework