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
)