args
This module provides functionalities that makes writing command-line interfaces easy. A user can define the options and commands available in a program and this module can automatically figure out how to parse those options and commands out of the CLI arguments. It also provides automatic help and usage messages as well as error/warnings generation for valid/invalid arguments.
Example
The below is a simple program that shows a typical use of the module.
import args
var parser = args.Parser('myprogram')
parser.add_option('name', 'The name of person to call', {type: args.STRING})
parser.add_command('call', 'Make a phone call')
parser.parse()
We can simply print help information for the above program if it were saved in a file myprogram.b
as follows.
$ blade myprogram.b -h
Usage: myprogram [ [-h] | [--name NAME] ] [COMMAND]
OPTIONS:
-h, --help Show this help message and exit
--name <value> The name of person to call
COMMANDS:
call Make a phone call
if we change the last line of the program to echo parser.parse()
so that we can see the result of the parsing, the following CLI call will yield the given result.
$ blade myprogram.b --name 25
{options: {name: 25}, command: nil}
$ blade myprogram.b call
{options: {}, command: {name: call, value: nil}}
$ blade myprogram.b call --name 25
{options: {name: 25}, command: {name: call, value: nil}}
Calling name without an option will yield the following result/error.
$ blade myprogram.b --name
error: Option "name" expects a value
You may even get help on a command directly like below:
$ blade myprogram.b --help call
Usage: myprogram call
Make a phone call
Properties
- args.NONE
- value type none
- args.INT
- value type integer (allows numbers, but floors them to integers)
- args.NUMBER
- value type number
- args.BOOL
- value type boolean (accepts
1
and0
as well astrue
andfalse
as valid values).
- args.STRING
- value type string
- args.LIST
- value type for list
- args.CHOICE
- value type enumeration choices.
Classes
class ArgsException < Exception
Commandline argument exception.
class ArgsException methods
- ArgsException(message: string)
- constructor
class Parser < _Optionable
A configurable commandline parser.
class Parser properties
- Parser.commands
- A list of commands supported by the parser.
class Parser methods
- Parser(name: string [, default_help: bool = true])
- param `name` refers to the name of the cli program.param `default_help` whether to show help when no command or option is matched or not.constructor
- add_option(name: string [, help: string [, opts: dict]])
- adds a support for a new command to the parser.
The
opts
dictionary can contain one or more of:short_name
: A shorter version of the option name parsed via single hyphens (-
) without the hyphen. For example, short_namev
will match-v
in the commandline.type
: type must be one of the args types and will indicate how the parsed data should be interpreted in the final result.required
: tells the parser if a value is compulsory for this option.choices
: a list of allowed options or a dictionary of allowed options with their respective descriptions.
- the
choices
option only works for typeCHOICE
.
- add_command(name: string [, help: string [, opts: dict]])
- adds a support for a new command to the parser.
The
opts
dictionary can contain propertytype
andaction
.- The
type
property a must be one of the args types and will indicate how the parsed data should be interpreted in the final result. - The
action
property must be a function.
The
opts
dictionary can contain one or more of:type
: type must be one of the args types and will indicate how the parsed data should be interpreted in the final result.required
: tells the parser if a value is compulsory for this option.choices
: a list of allowed options or a dictionary of allowed options with their respective descriptions.
- the
choices
option only works for typeCHOICE
.
- The
- parse()
- Parses the commandline arguments and returns a dictionary of command and options.
For example, parsing the commandline
blade test.b install 5 --verbose
may yeild such a result as{options: {verbose: true}, command: {name: install, value: 5}}
.return dict