Link Search Menu Expand Document

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

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.
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.
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

Back to top

Copyright © 2021 Ore Richard Muyiwa. Distributed under the MIT license.