Class: Console_Getargs

object|PEAR_Error &factory( [array $config = array()], [array $arguments = null])

Factory creates a new Console_Getargs_Options object

This method will return a new Console_Getargs_Options built using the given configuration options. If the configuration or the command line options contain errors, the returned object will in fact be a PEAR_Error explaining the cause of the error.

Factory expects an array as parameter. The format for this array is:

 array(
  longname => array('short'   => Short option name,
                    'max'     => Maximum arguments for option,
                    'min'     => Minimum arguments for option,
                    'default' => Default option argument,
                    'desc'    => Option description)
 )

If an option can be invoked by more than one name, they have to be defined by using | as a separator. For example: name1|name2 This works both in long and short names.

max/min are the most/least number of arguments an option accepts.

The 'defaults' field is optional and is used to specify default arguments to an option. These will be assigned to the option if it is *not* used in the command line. Default arguments can be:

• a single value for options that require a single argument,
• an array of values for options with more than one possible arguments.

Default argument(s) are mandatory for 'default-if-set' options.

If max is 0 (option is just a switch), min is ignored. If max is -1, then the option can have an unlimited number of arguments greater or equal to min.

If max == min == 1, the option is treated as a single argument option.

If max >= 1 and min == 0, the option is treated as a 'default-if-set' option. This implies that it will get the default argument only if the option is used in the command line without any value. (Note: defaults *must* be specified for 'default-if-set' options)

If the option is not in the command line, the defaults are *not* applied. If an argument for the option is specified on the command line, then the given argument is assigned to the option. Thus:

• a --debug in the command line would cause debug = 'default argument'
• a --debug 2 in the command line would result in debug = 2

if not used in the command line, debug will not be defined.

Example 1.

 require_once 'Console/Getargs.php';

 
 $args =& Console_Getargs::factory($config);
 
 if (PEAR::isError($args)) {
  if ($args->getCode() === CONSOLE_GETARGS_ERROR_USER) {
    echo Console_Getargs::getHelp($config, null, $args->getMessage())."\n";
  } else if ($args->getCode() === CONSOLE_GETARGS_HELP) {
    echo Console_Getargs::getHelp($config)."\n";
  }
  exit;
 }
 
 echo 'Verbose: '.$args->getValue('verbose')."\n";
 if ($args->isDefined('bs')) {
  echo 'Block-size: '.(is_array($args->getValue('bs')) ? implode(', ', $args->getValue('bs'))."\n" : $args->getValue('bs')."\n");
 } else {
  echo "Block-size: undefined\n";
 }
 echo 'Files: '.($args->isDefined('file') ? implode(', ', $args->getValue('file'))."\n" : "undefined\n");
 if ($args->isDefined('n')) {
  echo 'Nodes: '.(is_array($args->getValue('n')) ? implode(', ', $args->getValue('n'))."\n" : $args->getValue('n')."\n");
 } else {
  echo "Nodes: undefined\n";
 }
 echo 'Log: '.$args->getValue('log')."\n";
 echo 'Debug: '.($args->isDefined('d') ? "YES\n" : "NO\n");

If you don't want to require any option name for a set of arguments, or if you would like any "leftover" arguments assigned by default, you can create an option named CONSOLE_GETARGS_PARAMS that will grab any arguments that cannot be assigned to another option. The rules for CONSOLE_GETARGS_PARAMS are still the same. If you specify that two values must be passed then two values must be passed. See the example script for a complete example.

Parameters:

string getHelp( array $config, [string $helpHeader = null], [string $helpFooter = ''], [int $maxlength = 78], [int $indent = 0])

Returns an ascii art version of the help

This method uses the given configuration and parameters to create and format an help text for the options you defined in your config parameter. You can supply a header and a footer as well as the maximum length of a line. If you supplied descriptions for your options, they will be used as well.

By default, it returns something like this:

 Usage: myscript.php [-dv --formats] <-fw --filters>

 -f --files values(2)          Set the source and destination image files.
 -w --width=<value>      Set the new width of the image.
 -d --debug                    Switch to debug mode.
 --formats values(1-3)         Set the image destination format. (jpegbig,
                               jpegsmall)
 -fi --filters values(1-...)   Set the filters to be applied to the image upon
                               conversion. The filters will be used in the order
                               they are set.
 -v --verbose (optional)value  Set the verbose level. (3)

Parameters:

array getOptionalRequired( array &$config)

Parse the config array to determine which flags are optional and which are required.

To make the help header more descriptive, the options are shown seperated into optional and required flags. When possible the short flag is used for readability. Optional items (including "parameters") are surrounded in square braces ([-vd]). Required flags are surrounded in angle brackets (<-wf>).

This method may be called statically.

Parameters: