Console_Getargs
[ class tree: Console_Getargs ] [ index: Console_Getargs ] [ all elements ]

Class: Console_Getargs

Source Location: /Console_Getargs-1.3.5/Console/Getargs.php

Class Overview


Command-line arguments parsing class


Author(s):

Version:

  • 1.3.5

Copyright:

  • 2004 Bertrand Mansion

Methods


Inherited Variables

Inherited Methods


Class Details

[line 122]
Command-line arguments parsing class

This implementation was freely inspired by a python module called getargs by Vinod Vijayarajan and a perl CPAN module called Getopt::Simple by Ron Savage

This class implements a Command Line Parser that your cli applications can use to parse command line arguments found in $_SERVER['argv'] or a user defined array.

It gives more flexibility and error checking than Console_Getopt. It also performs some arguments validation and is capable to return a formatted help text to the user, based on the configuration it is given.

The class provides the following capabilities:

  • Each command line option can take an arbitrary number of arguments.
  • Makes the distinction between switches (options without arguments) and options that require arguments.
  • Recognizes 'single-argument-options' and 'default-if-set' options.
  • Switches and options with arguments can be interleaved in the command line.
  • You can specify the maximum and minimum number of arguments an option can take. Use -1 if you don't want to specify an upper bound.
  • Specify the default arguments to an option
  • Short options can be more than one letter in length.
  • A given option may be invoked by multiple names (aliases).
  • Understands by default the --help, -h options
  • Can return a formatted help text
  • Arguments may be specified using the '=' syntax also.
  • Short option names may be concatenated (-dvw 100 == -d -v -w 100)
  • Can define a default option that will take any arguments added without an option name
  • Can pass in a user defined array of arguments instead of using $_SERVER['argv']



[ Top ]


Method Detail

factory   [line 224]

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.

  1.  require_once 'Console/Getargs.php';
  2.  
  3.  $args =Console_Getargs::factory($config);
  4.  
  5.  if (PEAR::isError($args)) {
  6.   if ($args->getCode(=== CONSOLE_GETARGS_ERROR_USER{
  7.     echo Console_Getargs::getHelp($confignull$args->getMessage())."\n";
  8.   else if ($args->getCode(=== CONSOLE_GETARGS_HELP{
  9.     echo Console_Getargs::getHelp($config)."\n";
  10.   }
  11.   exit;
  12.  }
  13.  
  14.  echo 'Verbose: '.$args->getValue('verbose')."\n";
  15.  if ($args->isDefined('bs')) {
  16.   echo 'Block-size: '.(is_array($args->getValue('bs')) implode(', '$args->getValue('bs'))."\n" $args->getValue('bs')."\n");
  17.  else {
  18.   echo "Block-size: undefined\n";
  19.  }
  20.  echo 'Files: '.($args->isDefined('file'implode(', '$args->getValue('file'))."\n" "undefined\n");
  21.  if ($args->isDefined('n')) {
  22.   echo 'Nodes: '.(is_array($args->getValue('n')) implode(', '$args->getValue('n'))."\n" $args->getValue('n')."\n");
  23.  else {
  24.   echo "Nodes: undefined\n";
  25.  }
  26.  echo 'Log: '.$args->getValue('log')."\n";
  27.  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.

  • Return: a newly created Console_Getargs_Options object or a PEAR_Error object on error
  • Access: public

Parameters:

array   $config     associative array with keys being the
array   $arguments     numeric array of command line arguments

[ Top ]

getHelp   [line 298]

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)

  • Return: the formatted help text
  • Access: public

Parameters:

array   $config     your args configuration
string   $helpHeader     the header for the help. If it is left null, a default header will be used, starting by Usage:
string   $helpFooter     the footer for the help. This could be used to supply a description of the error the user made
int   $maxlength     help lines max length
int   $indent     the indent for the options

[ Top ]

getOptionalRequired   [line 453]

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.

  • Author: Scott Mattocks
  • Access: public

Parameters:

array   &$config     The config array.

[ Top ]


Documentation generated on Mon, 11 Oct 2010 16:00:04 +0000 by phpDocumentor 1.4.3. PEAR Logo Copyright © PHP Group 2004.