Python command line parser API

Python command line parser API

Overview

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

The *Info classes represent the Python counterparts of the elements defined in a program interface definition XML file.
The *Result classes store the state of the program elements after a command line argument processing
The Parser class parses command line arguments according to *Info rules and output corresponding *Results

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)