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 and 0 as well as true and false 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_name v 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 type CHOICE.

add_command(name: string [, help: string [, opts: dict]])

adds a support for a new command to the parser.

The opts dictionary can contain property type and action.

• 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 type CHOICE.

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