/**
* Factory creates a new {@link Console_Getargs_Options} object
*
* This method will return a new {@link 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:
* <pre>
* array(
* longname => array('short' => Short option name,
* 'max' => Maximum arguments for option,
* 'min' => Minimum arguments for option,
* 'default' => Default option argument,
* 'desc' => Option description)
* )
* </pre>
*
* 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.
* <code>
* 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");
*
* </code>
*
* 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.
*
* @param array $config associative array with keys being the
* options long name
* @param array $arguments numeric array of command line arguments
* @access public
* @return object|PEAR_Error a newly created Console_Getargs_Options
* object or a PEAR_Error object on error
*/
static function &factory($config = array(), $arguments = NULL)
{
// Create the options object.
$obj = new Console_Getargs_Options();
// Try to set up the arguments.
$err = $obj->init($config, $arguments);
if ($err !== true) {
return $err;
}
// Try to set up the options.
$err = $obj->buildMaps();
if ($err !== true) {
return $err;
}
// Get the options and arguments from the command line.
$err = $obj->parseArgs();
if ($err !== true) {
return $err;
}
// Set arguments for options that have defaults.
$err = $obj->setDefaults();
if ($err !== true) {
return $err;
}
// All is good.
return $obj;
}
/**
* Factory creates a new {@link Console_Getargs_Options} object
*
* This method will return a new {@link 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:
* <pre>
* array(
* longname => array('short' => Short option name,
* 'max' => Maximum arguments for option,
* 'min' => Minimum arguments for option,
* 'default' => Default option argument,
* 'desc' => Option description)
* )
* </pre>
*
* 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.
* <code>
* 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");
*
* </code>
*
* 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.
*
* @param array $config associative array with keys being the
* @param array $arguments numeric array of command line arguments
*
* @access public
* @return object|PEAR_Error a newly created Console_Getargs_Options
* object or a PEAR_Error object on error
*/
static function factory($config = array(), $arguments = null)
{
// Create the options object.
$obj = new Console_Getargs_Options();
// Try to set up the arguments.
$err = $obj->init($config, $arguments);
if ($err !== true) {
return $err;
}
// Try to set up the options.
$err = $obj->buildMaps();
if ($err !== true) {
return $err;
}
// Get the options and arguments from the command line.
$err = $obj->parseArgs();
if ($err !== true) {
return $err;
}
// Set arguments for options that have defaults.
$err = $obj->setDefaults();
if ($err !== true) {
return $err;
}
// Double check that all required options have been passed.
$err = $obj->checkRequired();
if ($err !== true) {
return $err;
}
// All is good.
return $obj;
}
