Maarch CLITools v0.1.0 documentation

ArgsParser A simple yet powerful command line argument parser

«  Welcome to Maarch CLITools’s documentation!   ::   Contents

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:

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

«  Welcome to Maarch CLITools’s documentation!   ::   Contents