Class ConsoleOptionParser
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.
Options
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.
Using Options
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 my_command --connection default --name=something
Short options can be defined singly or in groups.
cake my_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 my_command -c -n
Short options can also accept values:
cake my_command -c default
Positional arguments
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]);
Providing Help text
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.
Property Summary
-
$_args protected
array<Cake\Console\ConsoleInputArgument>
Positional argument definitions.
-
$_command protected
string
Command name.
-
$_description protected
string
Description text - displays before options when help is generated
-
$_epilog protected
string
Epilog text - displays after options when help is generated
-
$_options protected
array<string, \Cake\Console\ConsoleInputOption>
Option definitions.
-
$_shortOptions protected
array<string, string>
Map of short -> long options, generated when using addOption()
-
$_subcommandSort protected
bool
Subcommand sorting option
-
$_subcommands protected
array<string, \Cake\Console\ConsoleInputSubcommand>
Subcommands for this Shell.
-
$_tokens protected
array
Array of args (argv).
-
$rootName protected
string
Root alias used in help output
Method Summary
-
__construct() public
Construct an OptionParser so you can define its behavior
-
_nextToken() protected
Find the next token in the argv set.
-
_optionExists() protected
Check to see if $name has an option (short/long) defined for it.
-
_parseArg() protected
Parse an argument, and ensure that the argument doesn't exceed the number of arguments and that the argument is a valid choice.
-
_parseLongOption() protected
Parse the value for a long option out of $this->_tokens. Will handle options with an
=
in them. -
_parseOption() protected
Parse an option by its name index.
-
_parseShortOption() protected
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.
-
addArgument() public
Add a positional argument to the option parser.
-
addArguments() public
Add multiple arguments at once. Take an array of argument definitions. The keys are used as the argument names, and the values as params for the argument.
-
addOption() public
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.
-
addOptions() public
Add multiple options at once. Takes an array of option definitions. The keys are used as option names, and the values as params for the option.
-
addSubcommand() public
Append a subcommand to the subcommand list. Subcommands are usually methods on your Shell, but can also be used to document Tasks.
-
addSubcommands() public
Add multiple subcommands at once.
-
argumentNames() public
Get the list of argument names.
-
arguments() public
Gets the arguments defined in the parser.
-
buildFromArray() public static
Build a parser from an array. Uses an array like
-
create() public static
Static factory method for creating new OptionParsers so you can chain methods off of them.
-
enableSubcommandSort() public
Enables sorting of subcommands
-
getCommand() public
Gets the command name for shell/task.
-
getDescription() public
Gets the description text for shell/task.
-
getEpilog() public
Gets the epilog.
-
help() public
Gets formatted help for this parser object.
-
isSubcommandSortEnabled() public
Checks whether sorting is enabled for subcommands.
-
merge() public
Get or set the command name for shell/task.
-
options() public
Get the defined options in the parser.
-
parse() public
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
-
removeOption() public
Remove an option from the option parser.
-
removeSubcommand() public
Remove a subcommand from the option parser.
-
setCommand() public
Sets the command name for shell/task.
-
setDescription() public
Sets the description text for shell/task.
-
setEpilog() public
Sets an epilog to the parser. The epilog is added to the end of the options and arguments listing when help is generated.
-
setRootName() public
Set the root name used in the HelpFormatter
-
subcommands() public
Get the array of defined subcommands
-
toArray() public
Returns an array representation of this parser.
Method Detail
__construct() ¶ public
__construct(string $command = '', bool $defaultOptions = true)
Construct an OptionParser so you can define its behavior
Parameters
-
string
$command optional The command name this parser is for. The command name is used for generating help.
-
bool
$defaultOptions optional Whether you want the verbose and quiet options set. Setting this to false will prevent the addition of
--verbose
&--quiet
options.
_optionExists() ¶ protected
_optionExists(string $name): bool
Check to see if $name has an option (short/long) defined for it.
Parameters
-
string
$name The name of the option.
Returns
bool
_parseArg() ¶ protected
_parseArg(string $argument, array $args): array<string>
Parse an argument, and ensure that the argument doesn't exceed the number of arguments and that the argument is a valid choice.
Parameters
-
string
$argument The argument to append
-
array
$args The array of parsed args to append to.
Returns
array<string>
Throws
Cake\Console\Exception\ConsoleException
_parseLongOption() ¶ protected
_parseLongOption(string $option, array<string, mixed> $params): array
Parse the value for a long option out of $this->_tokens. Will handle
options with an =
in them.
Parameters
-
string
$option The option to parse.
-
array<string, mixed>
$params The params to append the parsed value into
Returns
array
_parseOption() ¶ protected
_parseOption(string $name, array<string, mixed> $params): array<string, mixed>
Parse an option by its name index.
Parameters
-
string
$name The name to parse.
-
array<string, mixed>
$params The params to append the parsed value into
Returns
array<string, mixed>
Throws
Cake\Console\Exception\ConsoleException
_parseShortOption() ¶ protected
_parseShortOption(string $option, array<string, mixed> $params): array<string, mixed>
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.
Parameters
-
string
$option The option to parse.
-
array<string, mixed>
$params The params to append the parsed value into
Returns
array<string, mixed>
Throws
Cake\Console\Exception\ConsoleException
When unknown short options are encountered.
addArgument() ¶ public
addArgument(Cake\Console\ConsoleInputArgument|string $name, array<string, mixed> $params = []): $this
Add a positional argument to the option parser.
Params
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.
Parameters
-
Cake\Console\ConsoleInputArgument|string
$name The name of the argument. Will also accept an instance of ConsoleInputArgument.
-
array<string, mixed>
$params optional Parameters for the argument, see above.
Returns
$this
addArguments() ¶ public
addArguments(array $args): $this
Add multiple arguments at once. Take an array of argument definitions. The keys are used as the argument names, and the values as params for the argument.
Parameters
-
array
$args Array of arguments to add.
Returns
$this
See Also
addOption() ¶ public
addOption(Cake\Console\ConsoleInputOption|string $name, array<string, mixed> $options = []): $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.
Options
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.
Parameters
-
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<string, mixed>
$options optional An array of parameters that define the behavior of the option
Returns
$this
addOptions() ¶ public
addOptions(array<string, mixed> $options): $this
Add multiple options at once. Takes an array of option definitions. The keys are used as option names, and the values as params for the option.
Parameters
-
array<string, mixed>
$options Array of options to add.
Returns
$this
See Also
addSubcommand() ¶ public
addSubcommand(Cake\Console\ConsoleInputSubcommand|string $name, array<string, mixed> $options = []): $this
Append a subcommand to the subcommand list. Subcommands are usually methods on your Shell, but can also be used to document Tasks.
Options
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.
Parameters
-
Cake\Console\ConsoleInputSubcommand|string
$name Name of the subcommand. Will also accept an instance of ConsoleInputSubcommand.
-
array<string, mixed>
$options optional Array of params, see above.
Returns
$this
addSubcommands() ¶ public
addSubcommands(array<string, mixed> $commands): $this
Add multiple subcommands at once.
Parameters
-
array<string, mixed>
$commands Array of subcommands.
Returns
$this
argumentNames() ¶ public
argumentNames(): array<string>
Get the list of argument names.
Returns
array<string>
arguments() ¶ public
arguments(): array<Cake\Console\ConsoleInputArgument>
Gets the arguments defined in the parser.
Returns
array<Cake\Console\ConsoleInputArgument>
buildFromArray() ¶ public static
buildFromArray(array<string, mixed> $spec, bool $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.
]
];
Parameters
-
array<string, mixed>
$spec The spec to build the OptionParser with.
-
bool
$defaultOptions optional Whether you want the verbose and quiet options set.
Returns
static
create() ¶ public static
create(string $command, bool $defaultOptions = true): static
Static factory method for creating new OptionParsers so you can chain methods off of them.
Parameters
-
string
$command The command name this parser is for. The command name is used for generating help.
-
bool
$defaultOptions optional Whether you want the verbose and quiet options set.
Returns
static
enableSubcommandSort() ¶ public
enableSubcommandSort(bool $value = true): $this
Enables sorting of subcommands
Parameters
-
bool
$value optional Whether to sort subcommands
Returns
$this
getDescription() ¶ public
getDescription(): string
Gets the description text for shell/task.
Returns
string
help() ¶ public
help(string|null $subcommand = null, string $format = 'text', int $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.
Parameters
-
string|null
$subcommand optional If present and a valid subcommand that has a linked parser. That subcommands help will be shown instead.
-
string
$format optional Define the output format, can be text or XML
-
int
$width optional The width to format user content to. Defaults to 72
Returns
string
isSubcommandSortEnabled() ¶ public
isSubcommandSortEnabled(): bool
Checks whether sorting is enabled for subcommands.
Returns
bool
merge() ¶ public
merge(Cake\Console\ConsoleOptionParser|array $spec): $this
Get or set the command name for shell/task.
Parameters
-
Cake\Console\ConsoleOptionParser|array
$spec ConsoleOptionParser or spec to merge with.
Returns
$this
options() ¶ public
options(): array<string, \Cake\Console\ConsoleInputOption>
Get the defined options in the parser.
Returns
array<string, \Cake\Console\ConsoleInputOption>
parse() ¶ public
parse(array $argv, Cake\Console\ConsoleIo|null $io = null): 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
Parameters
-
array
$argv Array of args (argv) to parse.
-
Cake\Console\ConsoleIo|null
$io optional A ConsoleIo instance or null. If null prompt options will error.
Returns
array
Throws
Cake\Console\Exception\ConsoleException
When an invalid parameter is encountered.
removeOption() ¶ public
removeOption(string $name): $this
Remove an option from the option parser.
Parameters
-
string
$name The option name to remove.
Returns
$this
removeSubcommand() ¶ public
removeSubcommand(string $name): $this
Remove a subcommand from the option parser.
Parameters
-
string
$name The subcommand name to remove.
Returns
$this
setCommand() ¶ public
setCommand(string $text): $this
Sets the command name for shell/task.
Parameters
-
string
$text The text to set.
Returns
$this
setDescription() ¶ public
setDescription(array<string>|string $text): $this
Sets the description text for shell/task.
Parameters
-
array<string>|string
$text The text to set. If an array the text will be imploded with "\n".
Returns
$this
setEpilog() ¶ public
setEpilog(array<string>|string $text): $this
Sets an epilog to the parser. The epilog is added to the end of the options and arguments listing when help is generated.
Parameters
-
array<string>|string
$text The text to set. If an array the text will be imploded with "\n".
Returns
$this
setRootName() ¶ public
setRootName(string $name): $this
Set the root name used in the HelpFormatter
Parameters
-
string
$name The root command name
Returns
$this
subcommands() ¶ public
subcommands(): array<string, \Cake\Console\ConsoleInputSubcommand>
Get the array of defined subcommands
Returns
array<string, \Cake\Console\ConsoleInputSubcommand>
toArray() ¶ public
toArray(): array<string, mixed>
Returns an array representation of this parser.
Returns
array<string, mixed>
Property Detail
$_description ¶ protected
Description text - displays before options when help is generated
Type
string
$_shortOptions ¶ protected
Map of short -> long options, generated when using addOption()
Type
array<string, string>
$_subcommands ¶ protected
Subcommands for this Shell.
Type
array<string, \Cake\Console\ConsoleInputSubcommand>