Introduction
Prev		Next

Introduction

Introduction – introduction to the Console_CommandLine package

Introduction

Console_CommandLine is a convenient, flexible, and powerful library for parsing command-line options and arguments.

It uses adeclarative style of command-line parsing: you create an instance of Console_CommandLine, populate it with options, arguments and even sub-commands and parse the command line. Console_CommandLine allows users to specify options in the conventional GNU/POSIX syntax, and additionally generates usage and help messages for you.

DISCLAIMER: since Console_CommandLine was highly inspired from the python optparse module and thus is very similar to it, some parts of this document were shamelessly copied from optparse manual.

A simple example:


<?php
require_once 'Console/CommandLine.php';

$parser = new Console_CommandLine();
$parser->description = 'A fantastic command line program that does nothing.';
$parser->version = '1.5.0';
$parser->addOption('filename', array(
    'short_name'  => '-f',
    'long_name'   => '--file',
    'description' => 'write report to FILE',
    'help_name'   => 'FILE',
    'action'      => 'StoreString'
));
$parser->addOption('quiet', array(
    'short_name'  => '-q',
    'long_name'   => '--quiet',
    'description' => "don't print status messages to stdout",
    'action'      => 'StoreTrue'
));
try {
    $result = $parser->parse();
    // do something with the result object
    print_r($result->options);
    print_r($result->args);
} catch (Exception $exc) {
    $parser->displayError($exc->getMessage());
}
?>

With the above lines of code, users of the script can now use the program like this:

$ <yourscript> --file=outfile -q

As it parses the command line, Console_CommandLine sets attributes of the result object returned by Console_CommandLine::parse() method based on user-supplied command-line values. When Console_CommandLine::parse() returns from parsing this command line, $result->options['filename'] will be "outfile" and $result->options['quiet'] will be TRUE.

Console_CommandLine supports both long and short options, allows short options to be merged together, and allows options to be associated with their arguments in a variety of ways.

The following lines are all equivalent for the above example:

$ <yourscript> -f outfile --quiet
$ <yourscript> --quiet --file outfile
$ <yourscript> -q -foutfile
$ <yourscript> -qfoutfile

Additionally, to get help, users can do this:

$ <yourscript> -h
$ <yourscript> --help

These commands will print:

A fantastic command line program that does nothing.

Usage:
  tmp.php [options]

Options:
  -f FILE, --file=FILE  write report to FILE
  -q, --quiet           don't print status messages to stdout
  -h, --help            show this help message and exit
  --version             show the program version and exit

Console_CommandLine also manage the program version automatically:

$ <yourscript> --version

The above command will print:

$ <yourscript> version 1.5.0.

where the value of yourscript is determined at runtime (normally from $argv[0], except if you specified explicitely a name for your parser).

Prev	Console_CommandLine	Next
Console_CommandLine	PEAR Manual	Creating the parser