Introduction
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).