/** * 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; }