$_description
$_description : string
Description text - displays before options when help is generated
Handles parsing the ARGV in the command line and provides support for GetOpt compatible option definition. Provides a builder pattern implementation for creating shell option parsers.
Named arguments come in two forms, long and short. Long arguments are preceded
by two - and give a more verbose option name. i.e. --version. Short arguments are
preceded by one - and are only one character long. They usually match with a long option,
and provide a more terse alternative.
Options can be defined with both long and short forms. By using $parser->addOption()
you can define new options. The name of the option is used as its long form, and you
can supply an additional short form, with the short option. Short options should
only be one letter long. Using more than one letter for a short option will raise an exception.
Calling options can be done using syntax similar to most *nix command line tools. Long options
cane either include an = or leave it out.
cake myshell command --connection default --name=something
Short options can be defined singly or in groups.
cake myshell command -cn
Short options can be combined into groups as seen above. Each letter in a group will be treated as a separate option. The previous example is equivalent to:
cake myshell command -c -n
Short options can also accept values:
cake myshell command -c default
If no positional arguments are defined, all of them will be parsed. If you define positional arguments any arguments greater than those defined will cause exceptions. Additionally you can declare arguments as optional, by setting the required param to false.
$parser->addArgument('model', ['required' => false]);By providing help text for your positional arguments and named arguments, the ConsoleOptionParser
can generate a help display for you. You can view the help for shells by using the --help or -h switch.
$_options : array<mixed,\Cake\Console\ConsoleInputOption>
Option definitions.
$_args : array<mixed,\Cake\Console\ConsoleInputArgument>
Positional argument definitions.
$_subcommands : array<mixed,\Cake\Console\ConsoleInputSubcommand>
Subcommands for this Shell.
__construct(string|null $command = null, boolean $defaultOptions = true)
Construct an OptionParser so you can define its behavior
| string|null | $command | The command name this parser is for. The command name is used for generating help. |
| boolean | $defaultOptions | Whether you want the verbose and quiet options set. Setting
this to false will prevent the addition of |
create(string|null $command, boolean $defaultOptions = true) : static
Static factory method for creating new OptionParsers so you can chain methods off of them.
| string|null | $command | The command name this parser is for. The command name is used for generating help. |
| boolean | $defaultOptions | Whether you want the verbose and quiet options set. |
buildFromArray(array $spec, boolean $defaultOptions = true) : static
Build a parser from an array. Uses an array like
$spec = [
'description' => 'text',
'epilog' => 'text',
'arguments' => [
// list of arguments compatible with addArguments.
],
'options' => [
// list of options compatible with addOptions
],
'subcommands' => [
// list of subcommands to add.
]
];| array | $spec | The spec to build the OptionParser with. |
| boolean | $defaultOptions | Whether you want the verbose and quiet options set. |
merge(array|\Cake\Console\ConsoleOptionParser $spec) : $this
Get or set the command name for shell/task.
| array|\Cake\Console\ConsoleOptionParser | $spec | ConsoleOptionParser or spec to merge with. |
description(string|array|null $text = null) : string|$this
Get or set the description text for shell/task.
| string|array|null | $text | The text to set, or null if you want to read. If an array the text will be imploded with "\n". |
If reading, the value of the description. If setting $this will be returned.
epilog(string|array|null $text = null) : string|$this
Gets or sets an epilog to the parser. The epilog is added to the end of the options and arguments listing when help is generated.
| string|array|null | $text | Text when setting or null when reading. If an array the text will be imploded with "\n". |
If reading, the value of the epilog. If setting $this will be returned.
addOption(\Cake\Console\ConsoleInputOption|string $name, array $options = array()) : $this
Add an option to the option parser. Options allow you to define optional or required parameters for your console application. Options are defined by the parameters they use.
short - The single letter variant for this option, leave undefined for none.help - Help text for this option. Used when generating help for the option.default - The default value for this option. Defaults are added into the parsed params when the
attached option is not provided or has no value. Using default and boolean together will not work.
are added into the parsed parameters when the option is undefined. Defaults to null.boolean - The option uses no value, it's just a boolean switch. Defaults to false.
If an option is defined as boolean, it will always be added to the parsed params. If no present
it will be false, if present it will be true.multiple - The option can be provided multiple times. The parsed option
will be an array of values when this option is enabled.choices A list of valid choices for this option. If left empty all values are valid..
An exception will be raised when parse() encounters an invalid value.| \Cake\Console\ConsoleInputOption|string | $name | The long name you want to the value to be parsed out as when options are parsed. Will also accept an instance of ConsoleInputOption |
| array | $options | An array of parameters that define the behavior of the option |
addArgument(\Cake\Console\ConsoleInputArgument|string $name, array $params = array()) : $this
Add a positional argument to the option parser.
help The help text to display for this argument.required Whether this parameter is required.index The index for the arg, if left undefined the argument will be put
onto the end of the arguments. If you define the same index twice the first
option will be overwritten.choices A list of valid choices for this argument. If left empty all values are valid..
An exception will be raised when parse() encounters an invalid value.| \Cake\Console\ConsoleInputArgument|string | $name | The name of the argument. Will also accept an instance of ConsoleInputArgument. |
| array | $params | Parameters for the argument, see above. |
addSubcommand(\Cake\Console\ConsoleInputSubcommand|string $name, array $options = array()) : $this
Append a subcommand to the subcommand list.
Subcommands are usually methods on your Shell, but can also be used to document Tasks.
help - Help text for the subcommand.parser - A ConsoleOptionParser for the subcommand. This allows you to create method
specific option parsers. When help is generated for a subcommand, if a parser is present
it will be used.| \Cake\Console\ConsoleInputSubcommand|string | $name | Name of the subcommand. Will also accept an instance of ConsoleInputSubcommand |
| array | $options | Array of params, see above. |
arguments() : array<mixed,\Cake\Console\ConsoleInputArgument>
Gets the arguments defined in the parser.
options() : array<mixed,\Cake\Console\ConsoleInputOption>
Get the defined options in the parser.
subcommands() : array<mixed,\Cake\Console\ConsoleInputSubcommand>
Get the array of defined subcommands
parse(array $argv) : array
Parse the argv array into a set of params and args. If $command is not null and $command is equal to a subcommand that has a parser, that parser will be used to parse the $argv
| array | $argv | Array of args (argv) to parse. |
When an invalid parameter is encountered.
[$params, $args]
help(string|null $subcommand = null, string $format = 'text', integer $width = 72) : string
Gets formatted help for this parser object.
Generates help text based on the description, options, arguments, subcommands and epilog in the parser.
| string|null | $subcommand | If present and a valid subcommand that has a linked parser. That subcommands help will be shown instead. |
| string | $format | Define the output format, can be text or xml |
| integer | $width | The width to format user content to. Defaults to 72 |
Generated help.
getCommandError(string $command) : string
Get the message output in the console stating that the command can not be found and tries to guess what the user wanted to say. Output a list of available subcommands as well.
| string | $command | Unknown command name trying to be dispatched. |
The message to be displayed in the console.
getOptionError(string $option) : string
Get the message output in the console stating that the option can not be found and tries to guess what the user wanted to say. Output a list of available options as well.
| string | $option | Unknown option name trying to be used. |
The message to be displayed in the console.
getShortOptionError(string $option) : string
Get the message output in the console stating that the short option can not be found. Output a list of available short options and what option they refer to as well.
| string | $option | Unknown short option name trying to be used. |
The message to be displayed in the console.
findClosestItem(string $needle, array<mixed,string> $haystack) : string|null
Tries to guess the item name the user originally wanted using the some regex pattern and the levenshtein algorithm.
| string | $needle | Unknown item (either a subcommand name or an option for instance) trying to be used. |
| array<mixed,string> | $haystack | List of items available for the type $needle belongs to. |
The closest name to the item submitted by the user.
_parseLongOption(string $option, array $params) : array
Parse the value for a long option out of $this->_tokens. Will handle options with an `=` in them.
| string | $option | The option to parse. |
| array | $params | The params to append the parsed value into |
Params with $option added in.
_parseShortOption(string $option, array $params) : array
Parse the value for a short option out of $this->_tokens If the $option is a combination of multiple shortcuts like -otf they will be shifted onto the token stack and parsed individually.
| string | $option | The option to parse. |
| array | $params | The params to append the parsed value into |
When unknown short options are encountered.
Params with $option added in.
_parseArg(string $argument, array $args) : array
Parse an argument, and ensure that the argument doesn't exceed the number of arguments and that the argument is a valid choice.
| string | $argument | The argument to append |
| array | $args | The array of parsed args to append to. |
Args