Zend\Console\Getopt
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:
- Short flags like '-a'. Short flags are preceded by a single
dash. Short flags may be clustered e.g. '-abc', which is the
same as '-a' '-b' '-c'.
- Long flags like '--verbose'. Long flags are preceded by a
double dash. Long flags may not be clustered.
- Options may have a parameter, e.g. '--output filename'.
- Parameters for long flags may also be set off with an equals sign,
e.g. '--output=filename'.
- Parameters for long flags may be checked as string, word, or integer.
- Automatic generation of a helpful usage message.
- Signal end of options with '--'; subsequent arguments are treated
as non-option arguments, even if they begin with '-'.
- Raise exception Zend\Console\Exception\* in several cases
when invalid flags or parameters are given. Usage message is
returned in the exception object.
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:
- 'user|username|u=s' this means '--user' or '--username' or '-u'
are synonyms, and the option requires a string parameter.
- 'p=i' this means '-p' requires an integer parameter. No synonyms.
- 'verbose|v-i' this means '--verbose' or '-v' are synonyms, and
they take an optional integer parameter.
- 'help|h' this means '--help' or '-h' are synonyms, and
they take no parameter.
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.
Synopsis
- // constants
- const MODE_ZEND = 'zend';
- const MODE_GNU = 'gnu';
- const PARAM_REQUIRED = '=';
- const PARAM_OPTIONAL = '-';
- const TYPE_STRING = 's';
- const TYPE_WORD = 'w';
- const TYPE_INTEGER = 'i';
- const TYPE_NUMERIC_FLAG = '#';
- const CONFIG_RULEMODE = 'ruleMode';
- const CONFIG_DASHDASH = 'dashDash';
- const CONFIG_IGNORECASE = 'ignoreCase';
- const CONFIG_PARSEALL = 'parseAll';
- const CONFIG_CUMULATIVE_PARAMETERS = 'cumulativeParameters';
- const CONFIG_CUMULATIVE_FLAGS = 'cumulativeFlags';
- const CONFIG_PARAMETER_SEPARATOR = 'parameterSeparator';
- const CONFIG_FREEFORM_FLAGS = 'freeformFlags';
- const CONFIG_NUMERIC_FLAGS = 'numericFlags';
- // members
- protected array $getoptConfig;
- protected array $argv;
- protected string $progname;
- protected array $rules;
- protected array $ruleMap;
- protected array $options;
- protected array $remainingArgs;
- protected bool $parsed;
- protected array $optionCallbacks;
- // methods
- public void __construct()
- public string __get()
- public bool __isset()
- public void __set()
- public string __toString()
- public void __unset()
- public self addArguments()
- public self setArguments()
- public self setOptions()
- public self setOption()
- public self addRules()
- public string toString()
- public array toArray()
- public string toJson()
- public string toXml()
- public array getOptions()
- public mixed getOption()
- public array getRemainingArgs()
- public void getArguments()
- public string getUsageMessage()
- public self setAliases()
- public self setHelp()
- public self parse()
- public self setOptionCallback()
- protected void triggerCallbacks()
- protected void _parseLongOption()
- protected void _parseShortOptionCluster()
- protected void _parseSingleOption()
- protected void _setNumericOptionValue()
- protected void _setSingleOptionValue()
- protected void _setBooleanFlagValue()
- protected bool _checkParameterType()
- protected void _addRulesModeGnu()
- protected void _addRulesModeZend()
Constants
Name | Value |
---|---|
MODE_ZEND | 'zend' |
MODE_GNU | 'gnu' |
PARAM_REQUIRED | '=' |
PARAM_OPTIONAL | '-' |
TYPE_STRING | 's' |
TYPE_WORD | 'w' |
TYPE_INTEGER | 'i' |
TYPE_NUMERIC_FLAG | '#' |
CONFIG_RULEMODE | 'ruleMode' |
CONFIG_DASHDASH | 'dashDash' |
CONFIG_IGNORECASE | 'ignoreCase' |
CONFIG_PARSEALL | 'parseAll' |
CONFIG_CUMULATIVE_PARAMETERS | 'cumulativeParameters' |
CONFIG_CUMULATIVE_FLAGS | 'cumulativeFlags' |
CONFIG_PARAMETER_SEPARATOR | 'parameterSeparator' |
CONFIG_FREEFORM_FLAGS | 'freeformFlags' |
CONFIG_NUMERIC_FLAGS | 'numericFlags' |
Members
protected
- $argv
—
array
Stores the command-line arguments for the calling application. -
$getoptConfig
Defaults for getopt configuration are: ruleMode is 'zend' format, dashDash (--) token is enabled, ignoreCase is not enabled, parseAll is enabled, cumulative parameters are disabled, this means that subsequent options overwrite the parameter value, cumulative flags are disable, freeform flags are disable. - $optionCallbacks
—
array
A list of callbacks to call when a particular option is present. - $options
—
array
Stores options given by the user in the current invocation of the application, as well as parameters given in options. - $parsed
—
Zend\Console\bool
State of the options: parsed or not yet parsed? - $progname
—
string
Stores the name of the calling application. - $remainingArgs
—
array
Stores the command-line arguments other than options. - $ruleMap
—
array
Stores alternate spellings of legal options. - $rules
—
array
Stores the list of legal options for this application.
Methods
protected
- _addRulesModeGnu() — Define legal options using the gnu-style format.
- _addRulesModeZend() — Define legal options using the Zend-style format.
- _checkParameterType() — Return true if the parameter is in a valid format for the option $flag.
- _parseLongOption() — Parse command-line arguments for a single long option.
- _parseShortOptionCluster() — Parse command-line arguments for short options.
- _parseSingleOption() — Parse command-line arguments for a single option.
- _setBooleanFlagValue() — Set TRUE value to given flag, if this option does not exist yet In other case increase value to show count of flags' usage
- _setNumericOptionValue() — Set given value as value of numeric option
- _setSingleOptionValue() — Add relative to options' flag value
- triggerCallbacks() — Triggers all the registered callbacks.
public
- __construct() — The constructor takes one to three parameters.
- __get() — Return the state of the option seen on the command line of the current application invocation. This function returns true, or the parameter to the option, if any. If the option was not given, this function returns null.
- __isset() — Test whether a given option has been seen.
- __set() — Set the value for a given option.
- __toString() — Return the current set of options and parameters seen as a string.
- __unset() — Unset an option.
- addArguments() — Define additional command-line arguments.
- addRules() — Define additional option rules.
- getArguments()
- getOption() — Return the state of the option seen on the command line of the current application invocation.
- getOptions() — Return a list of options that have been seen in the current argv.
- getRemainingArgs() — Return the arguments from the command-line following all options found.
- getUsageMessage() — Return a useful option reference, formatted for display in an error message.
- parse() — Parse command-line arguments and find both long and short options.
- setAliases() — Define aliases for options.
- setArguments() — Define full set of command-line arguments.
- setHelp() — Define help messages for options.
- setOption() — Define one configuration option as a key/value pair.
- setOptionCallback()
- setOptions() — Define multiple configuration options from an associative array.
- toArray() — Return the current set of options and parameters seen as an array of canonical options and parameters.
- toJson() — Return the current set of options and parameters seen in Json format.
- toString() — Return the current set of options and parameters seen as a string.
- toXml() — Return the current set of options and parameters seen in XML format.