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:
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.
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:
Register an argument in the parser.
Parameters: |
|
---|---|
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"
)
);
Register a switch in the parser. Switches can only be optional
Parameters: |
|
---|---|
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"
)
);
Register a positional argument in the parser.
Parameters: |
|
---|---|
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"
)
);
Registers a subcommand to the parser
Parameters: |
|
---|---|
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
Gets the actual command line argument and parses them.
This is the core of the class.
Parameters: |
|
---|---|
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.
program.php --arg1 "value of arg1" -k=v path/to/file --switch
must be translated as
.. code-block:: php
<?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" )
Automatically generates usage for the program and exits
This method is automatically called in the following case :
It can also be invoked directly :
<?php
$argsparser = new ArgsParser();
$argsparser->usage();