1: <?php
2: /**
3: * ConsoleOptionParser file
4: *
5: * PHP 5
6: *
7: * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
8: * Copyright 2005-2012, Cake Software Foundation, Inc. (http://cakefoundation.org)
9: *
10: * Licensed under The MIT License
11: * Redistributions of files must retain the above copyright notice.
12: *
13: * @copyright Copyright 2005-2012, Cake Software Foundation, Inc. (http://cakefoundation.org)
14: * @link http://cakephp.org CakePHP(tm) Project
15: * @since CakePHP(tm) v 2.0
16: * @license MIT License (http://www.opensource.org/licenses/mit-license.php)
17: */
18:
19: App::uses('TaskCollection', 'Console');
20: App::uses('ConsoleOutput', 'Console');
21: App::uses('ConsoleInput', 'Console');
22: App::uses('ConsoleInputSubcommand', 'Console');
23: App::uses('ConsoleInputOption', 'Console');
24: App::uses('ConsoleInputArgument', 'Console');
25: App::uses('ConsoleOptionParser', 'Console');
26: App::uses('HelpFormatter', 'Console');
27:
28: /**
29: * Handles parsing the ARGV in the command line and provides support
30: * for GetOpt compatible option definition. Provides a builder pattern implementation
31: * for creating shell option parsers.
32: *
33: * ### Options
34: *
35: * Named arguments come in two forms, long and short. Long arguments are preceded
36: * by two - and give a more verbose option name. i.e. `--version`. Short arguments are
37: * preceded by one - and are only one character long. They usually match with a long option,
38: * and provide a more terse alternative.
39: *
40: * ### Using Options
41: *
42: * Options can be defined with both long and short forms. By using `$parser->addOption()`
43: * you can define new options. The name of the option is used as its long form, and you
44: * can supply an additional short form, with the `short` option. Short options should
45: * only be one letter long. Using more than one letter for a short option will raise an exception.
46: *
47: * Calling options can be done using syntax similar to most *nix command line tools. Long options
48: * cane either include an `=` or leave it out.
49: *
50: * `cake myshell command --connection default --name=something`
51: *
52: * Short options can be defined signally or in groups.
53: *
54: * `cake myshell command -cn`
55: *
56: * Short options can be combined into groups as seen above. Each letter in a group
57: * will be treated as a separate option. The previous example is equivalent to:
58: *
59: * `cake myshell command -c -n`
60: *
61: * Short options can also accept values:
62: *
63: * `cake myshell command -c default`
64: *
65: * ### Positional arguments
66: *
67: * If no positional arguments are defined, all of them will be parsed. If you define positional
68: * arguments any arguments greater than those defined will cause exceptions. Additionally you can
69: * declare arguments as optional, by setting the required param to false.
70: *
71: * `$parser->addArgument('model', array('required' => false));`
72: *
73: * ### Providing Help text
74: *
75: * By providing help text for your positional arguments and named arguments, the ConsoleOptionParser
76: * can generate a help display for you. You can view the help for shells by using the `--help` or `-h` switch.
77: *
78: * @package Cake.Console
79: */
80: class ConsoleOptionParser {
81:
82: /**
83: * Description text - displays before options when help is generated
84: *
85: * @see ConsoleOptionParser::description()
86: * @var string
87: */
88: protected $_description = null;
89:
90: /**
91: * Epilog text - displays after options when help is generated
92: *
93: * @see ConsoleOptionParser::epilog()
94: * @var string
95: */
96: protected $_epilog = null;
97:
98: /**
99: * Option definitions.
100: *
101: * @see ConsoleOptionParser::addOption()
102: * @var array
103: */
104: protected $_options = array();
105:
106: /**
107: * Map of short -> long options, generated when using addOption()
108: *
109: * @var string
110: */
111: protected $_shortOptions = array();
112:
113: /**
114: * Positional argument definitions.
115: *
116: * @see ConsoleOptionParser::addArgument()
117: * @var array
118: */
119: protected $_args = array();
120:
121: /**
122: * Subcommands for this Shell.
123: *
124: * @see ConsoleOptionParser::addSubcommand()
125: * @var array
126: */
127: protected $_subcommands = array();
128:
129: /**
130: * Command name.
131: *
132: * @var string
133: */
134: protected $_command = '';
135:
136: /**
137: * Construct an OptionParser so you can define its behavior
138: *
139: * @param string $command The command name this parser is for. The command name is used for generating help.
140: * @param boolean $defaultOptions Whether you want the verbose and quiet options set. Setting
141: * this to false will prevent the addition of `--verbose` & `--quiet` options.
142: */
143: public function __construct($command = null, $defaultOptions = true) {
144: $this->command($command);
145:
146: $this->addOption('help', array(
147: 'short' => 'h',
148: 'help' => __d('cake_console', 'Display this help.'),
149: 'boolean' => true
150: ));
151:
152: if ($defaultOptions) {
153: $this->addOption('verbose', array(
154: 'short' => 'v',
155: 'help' => __d('cake_console', 'Enable verbose output.'),
156: 'boolean' => true
157: ))->addOption('quiet', array(
158: 'short' => 'q',
159: 'help' => __d('cake_console', 'Enable quiet output.'),
160: 'boolean' => true
161: ));
162: }
163: }
164:
165: /**
166: * Static factory method for creating new OptionParsers so you can chain methods off of them.
167: *
168: * @param string $command The command name this parser is for. The command name is used for generating help.
169: * @param boolean $defaultOptions Whether you want the verbose and quiet options set.
170: * @return ConsoleOptionParser
171: */
172: public static function create($command, $defaultOptions = true) {
173: return new ConsoleOptionParser($command, $defaultOptions);
174: }
175:
176: /**
177: * Build a parser from an array. Uses an array like
178: *
179: * {{{
180: * $spec = array(
181: * 'description' => 'text',
182: * 'epilog' => 'text',
183: * 'arguments' => array(
184: * // list of arguments compatible with addArguments.
185: * ),
186: * 'options' => array(
187: * // list of options compatible with addOptions
188: * ),
189: * 'subcommands' => array(
190: * // list of subcommands to add.
191: * )
192: * );
193: * }}}
194: *
195: * @param array $spec The spec to build the OptionParser with.
196: * @return ConsoleOptionParser
197: */
198: public static function buildFromArray($spec) {
199: $parser = new ConsoleOptionParser($spec['command']);
200: if (!empty($spec['arguments'])) {
201: $parser->addArguments($spec['arguments']);
202: }
203: if (!empty($spec['options'])) {
204: $parser->addOptions($spec['options']);
205: }
206: if (!empty($spec['subcommands'])) {
207: $parser->addSubcommands($spec['subcommands']);
208: }
209: if (!empty($spec['description'])) {
210: $parser->description($spec['description']);
211: }
212: if (!empty($spec['epilog'])) {
213: $parser->epilog($spec['epilog']);
214: }
215: return $parser;
216: }
217:
218: /**
219: * Get or set the command name for shell/task.
220: *
221: * @param string $text The text to set, or null if you want to read
222: * @return mixed If reading, the value of the command. If setting $this will be returned
223: */
224: public function command($text = null) {
225: if ($text !== null) {
226: $this->_command = Inflector::underscore($text);
227: return $this;
228: }
229: return $this->_command;
230: }
231:
232: /**
233: * Get or set the description text for shell/task.
234: *
235: * @param string|array $text The text to set, or null if you want to read. If an array the
236: * text will be imploded with "\n"
237: * @return mixed If reading, the value of the description. If setting $this will be returned
238: */
239: public function description($text = null) {
240: if ($text !== null) {
241: if (is_array($text)) {
242: $text = implode("\n", $text);
243: }
244: $this->_description = $text;
245: return $this;
246: }
247: return $this->_description;
248: }
249:
250: /**
251: * Get or set an epilog to the parser. The epilog is added to the end of
252: * the options and arguments listing when help is generated.
253: *
254: * @param string|array $text Text when setting or null when reading. If an array the text will be imploded with "\n"
255: * @return mixed If reading, the value of the epilog. If setting $this will be returned.
256: */
257: public function epilog($text = null) {
258: if ($text !== null) {
259: if (is_array($text)) {
260: $text = implode("\n", $text);
261: }
262: $this->_epilog = $text;
263: return $this;
264: }
265: return $this->_epilog;
266: }
267:
268: /**
269: * Add an option to the option parser. Options allow you to define optional or required
270: * parameters for your console application. Options are defined by the parameters they use.
271: *
272: * ### Options
273: *
274: * - `short` - The single letter variant for this option, leave undefined for none.
275: * - `help` - Help text for this option. Used when generating help for the option.
276: * - `default` - The default value for this option. Defaults are added into the parsed params when the
277: * attached option is not provided or has no value. Using default and boolean together will not work.
278: * are added into the parsed parameters when the option is undefined. Defaults to null.
279: * - `boolean` - The option uses no value, its just a boolean switch. Defaults to false.
280: * If an option is defined as boolean, it will always be added to the parsed params. If no present
281: * it will be false, if present it will be true.
282: * - `choices` A list of valid choices for this option. If left empty all values are valid..
283: * An exception will be raised when parse() encounters an invalid value.
284: *
285: * @param ConsoleInputOption|string $name The long name you want to the value to be parsed out as when options are parsed.
286: * Will also accept an instance of ConsoleInputOption
287: * @param array $options An array of parameters that define the behavior of the option
288: * @return ConsoleOptionParser $this.
289: */
290: public function addOption($name, $options = array()) {
291: if (is_object($name) && $name instanceof ConsoleInputOption) {
292: $option = $name;
293: $name = $option->name();
294: } else {
295: $defaults = array(
296: 'name' => $name,
297: 'short' => null,
298: 'help' => '',
299: 'default' => null,
300: 'boolean' => false,
301: 'choices' => array()
302: );
303: $options = array_merge($defaults, $options);
304: $option = new ConsoleInputOption($options);
305: }
306: $this->_options[$name] = $option;
307: if ($option->short() !== null) {
308: $this->_shortOptions[$option->short()] = $name;
309: }
310: return $this;
311: }
312:
313: /**
314: * Add a positional argument to the option parser.
315: *
316: * ### Params
317: *
318: * - `help` The help text to display for this argument.
319: * - `required` Whether this parameter is required.
320: * - `index` The index for the arg, if left undefined the argument will be put
321: * onto the end of the arguments. If you define the same index twice the first
322: * option will be overwritten.
323: * - `choices` A list of valid choices for this argument. If left empty all values are valid..
324: * An exception will be raised when parse() encounters an invalid value.
325: *
326: * @param ConsoleInputArgument|string $name The name of the argument. Will also accept an instance of ConsoleInputArgument
327: * @param array $params Parameters for the argument, see above.
328: * @return ConsoleOptionParser $this.
329: */
330: public function addArgument($name, $params = array()) {
331: if (is_object($name) && $name instanceof ConsoleInputArgument) {
332: $arg = $name;
333: $index = count($this->_args);
334: } else {
335: $defaults = array(
336: 'name' => $name,
337: 'help' => '',
338: 'index' => count($this->_args),
339: 'required' => false,
340: 'choices' => array()
341: );
342: $options = array_merge($defaults, $params);
343: $index = $options['index'];
344: unset($options['index']);
345: $arg = new ConsoleInputArgument($options);
346: }
347: $this->_args[$index] = $arg;
348: ksort($this->_args);
349: return $this;
350: }
351:
352: /**
353: * Add multiple arguments at once. Take an array of argument definitions.
354: * The keys are used as the argument names, and the values as params for the argument.
355: *
356: * @param array $args Array of arguments to add.
357: * @see ConsoleOptionParser::addArgument()
358: * @return ConsoleOptionParser $this
359: */
360: public function addArguments(array $args) {
361: foreach ($args as $name => $params) {
362: $this->addArgument($name, $params);
363: }
364: return $this;
365: }
366:
367: /**
368: * Add multiple options at once. Takes an array of option definitions.
369: * The keys are used as option names, and the values as params for the option.
370: *
371: * @param array $options Array of options to add.
372: * @see ConsoleOptionParser::addOption()
373: * @return ConsoleOptionParser $this
374: */
375: public function addOptions(array $options) {
376: foreach ($options as $name => $params) {
377: $this->addOption($name, $params);
378: }
379: return $this;
380: }
381:
382: /**
383: * Append a subcommand to the subcommand list.
384: * Subcommands are usually methods on your Shell, but can also be used to document Tasks.
385: *
386: * ### Options
387: *
388: * - `help` - Help text for the subcommand.
389: * - `parser` - A ConsoleOptionParser for the subcommand. This allows you to create method
390: * specific option parsers. When help is generated for a subcommand, if a parser is present
391: * it will be used.
392: *
393: * @param ConsoleInputSubcommand|string $name Name of the subcommand. Will also accept an instance of ConsoleInputSubcommand
394: * @param array $options Array of params, see above.
395: * @return ConsoleOptionParser $this.
396: */
397: public function addSubcommand($name, $options = array()) {
398: if (is_object($name) && $name instanceof ConsoleInputSubcommand) {
399: $command = $name;
400: $name = $command->name();
401: } else {
402: $defaults = array(
403: 'name' => $name,
404: 'help' => '',
405: 'parser' => null
406: );
407: $options = array_merge($defaults, $options);
408: $command = new ConsoleInputSubcommand($options);
409: }
410: $this->_subcommands[$name] = $command;
411: return $this;
412: }
413:
414: /**
415: * Add multiple subcommands at once.
416: *
417: * @param array $commands Array of subcommands.
418: * @return ConsoleOptionParser $this
419: */
420: public function addSubcommands(array $commands) {
421: foreach ($commands as $name => $params) {
422: $this->addSubcommand($name, $params);
423: }
424: return $this;
425: }
426:
427: /**
428: * Gets the arguments defined in the parser.
429: *
430: * @return array Array of argument descriptions
431: */
432: public function arguments() {
433: return $this->_args;
434: }
435:
436: /**
437: * Get the defined options in the parser.
438: *
439: * @return array
440: */
441: public function options() {
442: return $this->_options;
443: }
444:
445: /**
446: * Get the array of defined subcommands
447: *
448: * @return array
449: */
450: public function subcommands() {
451: return $this->_subcommands;
452: }
453:
454: /**
455: * Parse the argv array into a set of params and args. If $command is not null
456: * and $command is equal to a subcommand that has a parser, that parser will be used
457: * to parse the $argv
458: *
459: * @param array $argv Array of args (argv) to parse.
460: * @param string $command The subcommand to use. If this parameter is a subcommand, that has a parser,
461: * That parser will be used to parse $argv instead.
462: * @return Array array($params, $args)
463: * @throws ConsoleException When an invalid parameter is encountered.
464: */
465: public function parse($argv, $command = null) {
466: if (isset($this->_subcommands[$command]) && $this->_subcommands[$command]->parser()) {
467: return $this->_subcommands[$command]->parser()->parse($argv);
468: }
469: $params = $args = array();
470: $this->_tokens = $argv;
471: while (($token = array_shift($this->_tokens)) !== null) {
472: if (substr($token, 0, 2) == '--') {
473: $params = $this->_parseLongOption($token, $params);
474: } elseif (substr($token, 0, 1) == '-') {
475: $params = $this->_parseShortOption($token, $params);
476: } else {
477: $args = $this->_parseArg($token, $args);
478: }
479: }
480: foreach ($this->_args as $i => $arg) {
481: if ($arg->isRequired() && !isset($args[$i]) && empty($params['help'])) {
482: throw new ConsoleException(
483: __d('cake_console', 'Missing required arguments. %s is required.', $arg->name())
484: );
485: }
486: }
487: foreach ($this->_options as $option) {
488: $name = $option->name();
489: $isBoolean = $option->isBoolean();
490: $default = $option->defaultValue();
491:
492: if ($default !== null && !isset($params[$name]) && !$isBoolean) {
493: $params[$name] = $default;
494: }
495: if ($isBoolean && !isset($params[$name])) {
496: $params[$name] = false;
497: }
498: }
499: return array($params, $args);
500: }
501:
502: /**
503: * Gets formatted help for this parser object.
504: * Generates help text based on the description, options, arguments, subcommands and epilog
505: * in the parser.
506: *
507: * @param string $subcommand If present and a valid subcommand that has a linked parser.
508: * That subcommands help will be shown instead.
509: * @param string $format Define the output format, can be text or xml
510: * @param integer $width The width to format user content to. Defaults to 72
511: * @return string Generated help.
512: */
513: public function help($subcommand = null, $format = 'text', $width = 72) {
514: if (
515: isset($this->_subcommands[$subcommand]) &&
516: $this->_subcommands[$subcommand]->parser() instanceof self
517: ) {
518: $subparser = $this->_subcommands[$subcommand]->parser();
519: $subparser->command($this->command() . ' ' . $subparser->command());
520: return $subparser->help(null, $format, $width);
521: }
522: $formatter = new HelpFormatter($this);
523: if ($format == 'text' || $format === true) {
524: return $formatter->text($width);
525: } elseif ($format == 'xml') {
526: return $formatter->xml();
527: }
528: }
529:
530: /**
531: * Parse the value for a long option out of $this->_tokens. Will handle
532: * options with an `=` in them.
533: *
534: * @param string $option The option to parse.
535: * @param array $params The params to append the parsed value into
536: * @return array Params with $option added in.
537: */
538: protected function _parseLongOption($option, $params) {
539: $name = substr($option, 2);
540: if (strpos($name, '=') !== false) {
541: list($name, $value) = explode('=', $name, 2);
542: array_unshift($this->_tokens, $value);
543: }
544: return $this->_parseOption($name, $params);
545: }
546:
547: /**
548: * Parse the value for a short option out of $this->_tokens
549: * If the $option is a combination of multiple shortcuts like -otf
550: * they will be shifted onto the token stack and parsed individually.
551: *
552: * @param string $option The option to parse.
553: * @param array $params The params to append the parsed value into
554: * @return array Params with $option added in.
555: * @throws ConsoleException When unknown short options are encountered.
556: */
557: protected function _parseShortOption($option, $params) {
558: $key = substr($option, 1);
559: if (strlen($key) > 1) {
560: $flags = str_split($key);
561: $key = $flags[0];
562: for ($i = 1, $len = count($flags); $i < $len; $i++) {
563: array_unshift($this->_tokens, '-' . $flags[$i]);
564: }
565: }
566: if (!isset($this->_shortOptions[$key])) {
567: throw new ConsoleException(__d('cake_console', 'Unknown short option `%s`', $key));
568: }
569: $name = $this->_shortOptions[$key];
570: return $this->_parseOption($name, $params);
571: }
572:
573: /**
574: * Parse an option by its name index.
575: *
576: * @param string $name The name to parse.
577: * @param array $params The params to append the parsed value into
578: * @return array Params with $option added in.
579: * @throws ConsoleException
580: */
581: protected function _parseOption($name, $params) {
582: if (!isset($this->_options[$name])) {
583: throw new ConsoleException(__d('cake_console', 'Unknown option `%s`', $name));
584: }
585: $option = $this->_options[$name];
586: $isBoolean = $option->isBoolean();
587: $nextValue = $this->_nextToken();
588: $emptyNextValue = (empty($nextValue) && $nextValue !== '0');
589: if (!$isBoolean && !$emptyNextValue && !$this->_optionExists($nextValue)) {
590: array_shift($this->_tokens);
591: $value = $nextValue;
592: } elseif ($isBoolean) {
593: $value = true;
594: } else {
595: $value = $option->defaultValue();
596: }
597: if ($option->validChoice($value)) {
598: $params[$name] = $value;
599: return $params;
600: }
601: }
602:
603: /**
604: * Check to see if $name has an option (short/long) defined for it.
605: *
606: * @param string $name The name of the option.
607: * @return boolean
608: */
609: protected function _optionExists($name) {
610: if (substr($name, 0, 2) === '--') {
611: return isset($this->_options[substr($name, 2)]);
612: }
613: if ($name{0} === '-' && $name{1} !== '-') {
614: return isset($this->_shortOptions[$name{1}]);
615: }
616: return false;
617: }
618:
619: /**
620: * Parse an argument, and ensure that the argument doesn't exceed the number of arguments
621: * and that the argument is a valid choice.
622: *
623: * @param string $argument The argument to append
624: * @param array $args The array of parsed args to append to.
625: * @return array Args
626: * @throws ConsoleException
627: */
628: protected function _parseArg($argument, $args) {
629: if (empty($this->_args)) {
630: $args[] = $argument;
631: return $args;
632: }
633: $next = count($args);
634: if (!isset($this->_args[$next])) {
635: throw new ConsoleException(__d('cake_console', 'Too many arguments.'));
636: }
637:
638: if ($this->_args[$next]->validChoice($argument)) {
639: $args[] = $argument;
640: return $args;
641: }
642: }
643:
644: /**
645: * Find the next token in the argv set.
646: *
647: * @return string next token or ''
648: */
649: protected function _nextToken() {
650: return isset($this->_tokens[0]) ? $this->_tokens[0] : '';
651: }
652:
653: }
654: