ArgsParser A simple yet powerful command line argument parser¶
author: | Bruno Carlin <bruno.carlin@maarch.org> |
---|
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.
- 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, $params)¶
Register an argument in the parser.
Parameters: - $name (string) – The name of the argument
- $params –
The parameters of the argument. Can contain following items:
- short: the short form of the argument (ex: “q” for “-q”) (default: null)
- long: the long form of the argument (ex: “quiet” for “–quiet”) (default: null)
- default: The default value for the argument if not given by the user (default: null)
- mandatory: Wether the argument have a value either given by the user or a default one) (default: false)
- help: A short help phrase used to generate usage (default: “”)
Return type: null
Changed in version 0.2.0: Only add arguments. Other types have their own methods. Parameters are given as array
This is the only way to register an argument in the parser. Example:
To add a optional argument that sets the working directory for the script:
<?php $argsparser = new ArgsParser(); $argsparser->add_arg("working directory", Array( "short" => "w", "long" => "working-directory", "default" => getcwd(), "help" => "Sets working directory" ) );
- public method ArgsParser::add_switch($name, $params)¶
Register a switch in the parser. Switches can only be optional
Parameters: - $name (string) – The name of the switch
- $params –
The parameters of the switch. Can contain following items:
- short: the short form of the argument (ex: “q” for “-q”) (default: null)
- long: the long form of the argument (ex: “quiet” for “–quiet”) (default: null)
- default: The default value for the argument if not given by the user (default: false)
- help: A short help phrase used to generate usage (default: “”)
Return type: null
New in version 0.2.0.
Example:
To add a optional argument that make output more verbose:
<?php $argsparser = new ArgsParser(); $argsparser->add_switch("verbose", Array( "short" => "v", "long" => "verbose", "help" => "Makes output more verbose" ) );
- public method ArgsParser::add_positional($name, $params)¶
Register a positional argument in the parser.
Parameters: - $name (string) – The name of the argument
- $params –
The parameters of the argument. Can contain following items:
- default: The default value for the argument if not given by the user (default: null)
- mandatory: Wether the argument have a value either given by the user or a default one) (default: false)
- help: A short help phrase used to generate usage (default: “”)
Return type: null
New in version 0.2.0.
Example:
To add a mandatory positional argument that sets the working directory for the script:
<?php $argsparser = new ArgsParser(); $argsparser->add_positional("working directory", Array( "default" => getcwd(), "help" => "Sets working directory" ) );
- 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:
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.
Parameters: - $args (Array) – An array of arguments
Raises MissingArgumentError: When a mandatory argument is missing
Changed in version 0.1.1: Verifies that mandatory arguments have a value
Changed in version 0.1.3: Throws MissingArgumentError instead of exception
It takes as input a list of token taken directly from command line. In most cases, $GLOBALS["argv"] is what you want.
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();