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.

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"
)

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