Managing command line arguments
Prev		Next

Managing command line arguments

Managing command line arguments – how to add arguments to the parser and use them

Some background

Arguments are for those pieces of information that your program absolutely, positively requires to run.

A good user interface should have as few absolute requirements as possible. If your program requires 17 distinct pieces of information in order to run successfully, it doesn't much matter how you get that information from the user, most people will give up and walk away before they successfully run the program. This applies whether the user interface is a command-line, a configuration file, or a GUI: if you make that many demands on your users, most of them will simply give up.

In short, try to minimize the amount of information that users are absolutely required to supply and use sensible defaults whenever possible. Of course, you also want to make your programs reasonably flexible. That's what options are for.

Adding arguments with Console_CommandLine

To add arguments to your parser, just create the parser as explained in the previous section and use the Console_CommandLine::addArgument() method.

The Console_CommandLine::addArgument() method takes two arguments:

the argument name: a string that will be used to access the argument in the result object. For example if you name your argument foo, you will access to the result object like this: $result->args['foo'];
the arguments parameters: an array of various informations as explained below.

Available arguments parameters
name	type	required	description	example
description	string	no, but recommended for the help message	a description for the argument	entry list of input files separated by spaces
multiple	boolean	no, default to FALSE	tells the parser that the argument expects multiples values	TRUE
optional	boolean	no, default to FALSE	tells the parser that the argument is optional	TRUE
help_name	string	no, if not given it will default to the argument name	the name to display in the argument help line	files

Adding commandline arguments


<?php
require_once 'Console/CommandLine.php';
$parser = new Console_CommandLine();

// add an array argument
$parser->addArgument('input_files', array('multiple'=>true));

// add a simple argument
$parser->addArgument('output_file');

try {
   $result = $parser->parse();
   print_r($result->args);
} catch (Exception $exc) {
   $parser->displayError($exc->getMessage());
}
?>

If the user type:

$ <yourprogram> file1 file2 file3

The output of the above script will be:

Array
(
   [input_files] => Array
       (
           [0] => file1
           [1] => file2
       )

   [output_file] => file3
)

Prev	Console_CommandLine	Next
Managing command line options	PEAR Manual	Managing command line sub-commands