ArgsParser A simple yet powerful command line argument parser¶
ArgsParser makes it easy to define the command line syntax of your program.
You can define arguments with short (ex: -v) and long (ex: --verbose) identifiers.
It supports three types of arguments:
- Pure arguments, with short or long arguments. Supported syntaxes are:
- --key value or -k value
- --key=value or -k=value
- Switches, which translate to boolean values. ex: --verbose or -v.
- Positional arguments. Those can be named. All positional arguments given that are not named will be stored in a special array.
Additionally, subcommands are supported. Subcommands must be defined as a new instance of ArgsParser that will be attached to the main one. In consequence, subcommands can have their own sets of arguments.
- abstract class ArgsParser¶
This class contains a dictionnary of every argument and generates a hash containing all the options the users sets on the command line merged in default values.
It has the following methods:
- public method ArgsParser::add_arg($name, $type[, $short=null[, $long=null[, $default=null[, $mandatory=false[, $help=""]]]]])¶
Register an argument in the parser.
Parameters: - $name (string) – The name of the argument
- $type (string) – The argument’s type. Supported values: argument, switch and positional
- $short (string) – The short identifier for the argument
- $long (string) – The long identifier for the argument
- $default (mixed) – The default value of the argument
- $mandatory (bool) – Wether the argument must be given or not
- $help (string) – Description of the argument. Will be used to generate help
Return type: null
This is the only way to register an argument in the parser. Examples of use :
To add a optional switch to make output more verbose:
<?php $argsparser = new ArgsParser(); $argsparser->add_arg("verbose", "switch", "v", "verbose", False, False, "Makes output more verbose");
To add a mandatory positional argument that contains an output path:
<?php $argsparser = new ArgsParser(); $argsparser->add_arg("output", "positional", null, null, null, True, "Output path");
- public method ArgsParser::add_command($name, $aliases, &$parser[, $help=""])¶
Registers a subcommand to the parser
Parameters: - $name (string) – Main name of the command
- $aliases (array) – Aliases for the command
- $parser (ArgsParser) – An instance of ArgsParser that declares the specific arguments of the subcommand
- $help (string) – Description of the argument. Will be used to generate help
Return type: null
This allows to define and use subcommands on the command line. For example:
<?php $ program.php command -o /path/to/output/file
Those commands can be invoked with both the command name and its aliases. Let’s imagine a wrapper for the svn program. You can define the following:
<?php $main_parser = new ArgsParser(); $main_parser-> add_arg( ... ); $checkout_parser = new ArgsParser(); $checkout_parser->add_arg( ... ); $main_parser->add_command("checkout", Array("co", "get"), $checkout_parser, "Checkouts the given SVN repository");
You can then use this command the following ways:
svn.php checkout svn://url/to/repository svn.php co svn://url/to/repository svn.php get svn://url/to/repository
- public method ArgsParser::parse_args($args)¶
Gets the actual command line argument and parses them.
This is the core of the class.
It takes as input a list of token taken directly from command line.
program.php --arg1 "value of arg1" -k=v path/to/file --switch
must be translated as
<?php Array("program.php", "--arg1", "value of arg1", "-k=v", "path/to/file", "--switch");
This list will be processed and an array containing the options will be return. The returned array has the following structure:
<?php Array( "executable" => "program.php", "positional" => Array("list of", "non-declared", "positional arguments"), "name of arg1" => "value of arg1", "name of k" => "v", "non-given arg" => "default value", "path as positional arg" => "path/to/file", "switch" => True )
If a subcommand is given on the command line, a “subcommand” item will be added in the output array. It will contain an array defined as following:
<?php Array( "opts" => Array( ... ), // array returned by the sub-parser parse_args method. // It contains the subcommand specific arguments "name" => "name of the command" )
- public method ArgsParser::usage()¶
Automatically generates usage for the program and exits
This method is automatically called in the following case :
- no value is given for an argument
- the -h or --help switches are given on the command line
- the “help” command is given.
It can also be invoked directly :
<?php $argsparser = new ArgsParser(); $argsparser->usage();