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 signally 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', array('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.
$_args
protected array
$_command
protected string
$_description
protected string
$_epilog
protected string
$_options
protected array
$_shortOptions
protected string
$_subcommands
protected array
Parse an argument, and ensure that the argument doesn't exceed the number of arguments and that the argument is a valid choice.
Parse the value for a long option out of $this->_tokens. Will handle options with an =
in them.
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.
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.
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.
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.
Append a subcommand to the subcommand list. Subcommands are usually methods on your Shell, but can also be used to document Tasks.
Get or set an epilog to the parser. The epilog is added to the end of the options and arguments listing when help is generated.
Gets formatted help for this parser object. Generates help text based on the description, options, arguments, subcommands and epilog in the parser.
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
__construct( string $command null , boolean $defaultOptions true )
Construct an OptionParser so you can define its behavior
$command
optional null $defaultOptions
optional true Whether you want the verbose and quiet options set. Setting this to false will prevent the addition of --verbose
& --quiet
options.
_nextToken( )
Find the next token in the argv set.
_optionExists( string $name )
Check to see if $name has an option (short/long) defined for it.
$name
_parseArg( string $argument , array $args )
Parse an argument, and ensure that the argument doesn't exceed the number of arguments and that the argument is a valid choice.
$argument
$args
ConsoleException
_parseLongOption( string $option , array $params )
Parse the value for a long option out of $this->_tokens. Will handle options with an =
in them.
$option
$params
_parseOption( string $name , array $params )
Parse an option by its name index.
$name
$params
ConsoleException
_parseShortOption( string $option , array $params )
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.
$option
$params
ConsoleException
addArgument( ConsoleInputArgument|string $name , array $params array() )
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.ConsoleInputArgument
|string $name
$params
optional array() ConsoleOptionParser
addArguments( array $args )
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.
$args
ConsoleOptionParser
addOption( ConsoleInputOption|string $name , array $options array() )
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, its 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.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.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
$options
optional array() ConsoleOptionParser
addOptions( array $options )
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.
$options
ConsoleOptionParser
addSubcommand( ConsoleInputSubcommand|string $name , array $options array() )
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.ConsoleInputSubcommand
|string $name
$options
optional array() ConsoleOptionParser
addSubcommands( array $commands )
Add multiple subcommands at once.
$commands
ConsoleOptionParser
arguments( )
Gets the arguments defined in the parser.
buildFromArray( array $spec )
Build a parser from an array. Uses an array like
$spec = array( 'description' => 'text', 'epilog' => 'text', 'arguments' => array( // list of arguments compatible with addArguments. ), 'options' => array( // list of options compatible with addOptions ), 'subcommands' => array( // list of subcommands to add. ) );
$spec
ConsoleOptionParser
command( string $text null )
Get or set the command name for shell/task.
$text
optional null ConsoleOptionParser
create( string $command , boolean $defaultOptions true )
Static factory method for creating new OptionParsers so you can chain methods off of them.
$command
$defaultOptions
optional true ConsoleOptionParser
description( string|array $text null )
Get or set the description text for shell/task.
$text
optional null The text to set, or null if you want to read. If an array the text will be imploded with "\n"
ConsoleOptionParser
epilog( string|array $text null )
Get or set an epilog to the parser. The epilog is added to the end of the options and arguments listing when help is generated.
$text
optional null ConsoleOptionParser
help( string $subcommand null , string $format 'text' , integer $width 72 )
Gets formatted help for this parser object. Generates help text based on the description, options, arguments, subcommands and epilog in the parser.
$subcommand
optional null If present and a valid subcommand that has a linked parser. That subcommands help will be shown instead.
$format
optional 'text' $width
optional 72 parse( array $argv , string $command null )
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
$argv
$command
optional null The subcommand to use. If this parameter is a subcommand, that has a parser, That parser will be used to parse $argv instead.
ConsoleException
removeSubcommand( string $name )
Remove a subcommand from the option parser.
$name
ConsoleOptionParser
protected array
Positional argument definitions.
array()
protected string
Description text - displays before options when help is generated
null
protected string
Epilog text - displays after options when help is generated
null
protected string
Map of short -> long options, generated when using addOption()
array()
protected array
Subcommands for this Shell.
array()
© 2005–2016 The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/2.9/class-ConsoleOptionParser.html