Maarch CLITools v0.3.1 documentation

ArgsParser A simple yet powerful command line argument parser

«  Welcome to Maarch CLITools documentation!   ::   Contents   ::   Changelog  »

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:

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();

«  Welcome to Maarch CLITools documentation!   ::   Contents   ::   Changelog  »