Zend_Console_Getopt is a class to parse options for command-line applications.
Terminology: Argument: an element of the argv array. This may be part of an option, or it may be a non-option command-line argument. Flag: the letter or word set off by a '-' or '--'. Example: in '--output filename', '--output' is the flag. Parameter: the additional argument that is associated with the option. Example: in '--output filename', the 'filename' is the parameter. Option: the combination of a flag and its parameter, if any. Example: in '--output filename', the whole thing is the option.
The following features are supported:
The format for specifying options uses a PHP associative array. The key is has the format of a list of pipe-separated flag names, followed by an optional '=' to indicate a required parameter or '-' to indicate an optional parameter. Following that, the type of parameter may be specified as 's' for string, 'w' for word, or 'i' for integer.
Examples:
The values in the associative array are strings that are used as brief descriptions of the options when printing a usage message.
The simpler format for specifying options used by PHP's getopt() function is also supported. This is similar to GNU getopt and shell getopt format.
Example: 'abc:' means options '-a', '-b', and '-c' are legal, and the latter requires a string parameter.
category | Zend |
---|---|
package | Zend_Console_Getopt |
copyright | Copyright (c) 2005-2015 Zend Technologies USA Inc. (http://www.zend.com) |
license | New BSD License |
version | Release: @package_version@ |
since | Class available since Release 0.6.0 |
todo | Handle params with multiple values, e.g. --colors=red,green,blue Set value of parameter to the array of values. Allow user to specify the separator with Zend_Console_Getopt::CONFIG_PARAMETER_SEPARATOR. If this config value is null or empty string, do not split values into arrays. Default separator is comma (','). |
todo | Handle params with multiple values specified with separate options e.g. --colors red --colors green --colors blue should give one option with an array(red, green, blue). Enable with Zend_Console_Getopt::CONFIG_CUMULATIVE_PARAMETERS. Default is that subsequent options overwrite the parameter value. |
todo | Handle flags occurring multiple times, e.g. -v -v -v Set value of the option's parameter to the integer count of instances instead of a boolean. Enable with Zend_Console_Getopt::CONFIG_CUMULATIVE_FLAGS. Default is that the value is simply boolean true regardless of how many instances of the flag appear. |
todo | Handle flags that implicitly print usage message, e.g. --help |
todo | Handle freeform options, e.g. --set-variable Enable with Zend_Console_Getopt::CONFIG_FREEFORM_FLAGS All flag-like syntax is recognized, no flag generates an exception. |
todo | Handle numeric options, e.g. -1, -2, -3, -1000 Enable with Zend_Console_Getopt::CONFIG_NUMERIC_FLAGS The rule must specify a named flag and the '#' symbol as the parameter type. e.g., 'lines=#' |
todo | Enable user to specify header and footer content in the help message. |
todo | Feature request to handle option interdependencies. e.g. if -b is specified, -a must be specified or else the usage is invalid. |
todo | Feature request to implement callbacks. e.g. if -a is specified, run function 'handleOptionA'(). |
__construct(array $rules, array $argv= null
, array $getoptConfig= array()
) : void
The first parameter is $rules, which may be a string for gnu-style format, or a structured array for Zend-style format.
The second parameter is $argv, and it is optional. If not specified, $argv is inferred from the global argv.
The third parameter is an array of configuration parameters to control the behavior of this instance of Getopt; it is optional.
array
array
array
__get(string $key) : string
The magic __get method works in the context of naming the option as a virtual member of this class.
string
string
__isset(string $key) : boolean
string
boolean
__set(string $key, string $value) : void
string
string
__toString() : string
string
__unset(string $key) : void
string
addArguments(array $argv) : \Zend_Console_Getopt
These are appended to those defined when the constructor was called.
array
\Zend_Console_Getopt_Exception |
When not given an array as parameter |
---|
\Zend_Console_Getopt
Provides a fluent interfaceaddRules(array $rules) : \Zend_Console_Getopt
These are appended to the rules defined when the constructor was called.
array
\Zend_Console_Getopt
Provides a fluent interfacecheckRequiredArguments()
\Zend_Console_Getopt_Exception |
---|
getOption(string $flag) : mixed
This function returns true, or the parameter value to the option, if any. If the option was not given, this function returns null.
string
mixed
getOptions() : array
array
getRemainingArgs() : array
array
getUsageMessage() : string
Note that this usage information is provided in most Exceptions generated by this class.
string
parse() : \Zend_Console_Getopt | null
Also find option parameters, and remaining arguments after all options have been parsed.
\Zend_Console_Getopt
null
Provides a fluent interfacesetAliases(array $aliasMap) : \Zend_Console_Getopt
The parameter $aliasMap is an associative array mapping option name (short or long) to an alias.
array
\Zend_Console_Getopt_Exception |
---|
\Zend_Console_Getopt
Provides a fluent interfacesetArguments(array $argv) : \Zend_Console_Getopt
These replace any currently defined.
array
\Zend_Console_Getopt_Exception |
When not given an array as parameter |
---|
\Zend_Console_Getopt
Provides a fluent interfacesetHelp(array $helpMap) : \Zend_Console_Getopt
The parameter $help_map is an associative array mapping option name (short or long) to the help string.
array
\Zend_Console_Getopt
Provides a fluent interfacesetOption(string $configKey, string $configValue) : \Zend_Console_Getopt
These are not program options, but properties to configure the behavior of Zend_Console_Getopt.
string
string
\Zend_Console_Getopt
Provides a fluent interfacesetOptions(array $getoptConfig) : \Zend_Console_Getopt
These are not program options, but properties to configure the behavior of Zend_Console_Getopt.
array
\Zend_Console_Getopt
Provides a fluent interfacetoArray() : array
Clusters have been expanded, and option aliases have been mapped to their primary option names.
array
toJson() : string
string
toString() : string
string
toXml() : string
string
_addRulesModeGnu(string $rules) : void
string
_addRulesModeZend(array $rules) : void
array
\Zend_Console_Getopt_Exception |
---|
_checkParameterType(string $flag, string $param) : boolean
Throw an exception in most other cases.
string
string
\Zend_Console_Getopt_Exception |
---|
boolean
_parseLongOption($argv) : void
A long option is preceded by a double '--' character. Long options may not be clustered.
_parseShortOptionCluster($argv) : void
Short options are those preceded by a single '-' character. Short options may be clustered.
_parseSingleOption(string $flag, mixed $argv) : void
string
mixed
\Zend_Console_Getopt_Exception |
---|
$_argv : array
array()
$_getoptConfig
array(self::CONFIG_RULEMODE => self::MODE_ZEND, self::CONFIG_DASHDASH => true, self::CONFIG_IGNORECASE => false, self::CONFIG_PARSEALL => true)
$_parsed : boolean
false
$_progname : string
''
$_remainingArgs : array
array()
$_ruleMap : array
array()
$_rules : array
array()
CONFIG_DASHDASH = 'dashDash'
CONFIG_IGNORECASE = 'ignoreCase'
CONFIG_PARSEALL = 'parseAll'
CONFIG_RULEMODE = 'ruleMode'
ruleMode is either 'zend' or 'gnu' or a user-defined mode. dashDash is true if '--' signifies the end of command-line options. ignoreCase is true if '--opt' and '--OPT' are implicitly synonyms. parseAll is true if all options on the command line should be parsed, regardless of whether an argument appears before them.
MODE_GNU = 'gnu'
MODE_ZEND = 'zend'
modeGnu is for traditional 'ab:c:' style getopt format. modeZend is for a more structured format.
PARAM_OPTIONAL = '-'
PARAM_REQUIRED = '='
TYPE_INTEGER = 'i'
TYPE_STRING = 's'
TYPE_WORD = 'w'