1: <?php
2: /**
3: * CakePHP(tm) : Rapid Development Framework (https://cakephp.org)
4: * Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
5: *
6: * Licensed under The MIT License
7: * For full copyright and license information, please see the LICENSE.txt
8: * Redistributions of files must retain the above copyright notice.
9: *
10: * @copyright Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
11: * @link https://cakephp.org CakePHP(tm) Project
12: * @since 2.0.0
13: * @license https://opensource.org/licenses/mit-license.php MIT License
14: */
15: namespace Cake\Console;
16:
17: use Cake\Console\Exception\ConsoleException;
18: use SimpleXMLElement;
19:
20: /**
21: * An object to represent a single option used in the command line.
22: * ConsoleOptionParser creates these when you use addOption()
23: *
24: * @see \Cake\Console\ConsoleOptionParser::addOption()
25: */
26: class ConsoleInputOption
27: {
28:
29: /**
30: * Name of the option
31: *
32: * @var string
33: */
34: protected $_name;
35:
36: /**
37: * Short (1 character) alias for the option.
38: *
39: * @var string
40: */
41: protected $_short;
42:
43: /**
44: * Help text for the option.
45: *
46: * @var string
47: */
48: protected $_help;
49:
50: /**
51: * Is the option a boolean option. Boolean options do not consume a parameter.
52: *
53: * @var bool
54: */
55: protected $_boolean;
56:
57: /**
58: * Default value for the option
59: *
60: * @var mixed
61: */
62: protected $_default;
63:
64: /**
65: * Can the option accept multiple value definition.
66: *
67: * @var bool
68: */
69: protected $_multiple;
70:
71: /**
72: * An array of choices for the option.
73: *
74: * @var array
75: */
76: protected $_choices;
77:
78: /**
79: * Make a new Input Option
80: *
81: * @param string|array $name The long name of the option, or an array with all the properties.
82: * @param string $short The short alias for this option
83: * @param string $help The help text for this option
84: * @param bool $boolean Whether this option is a boolean option. Boolean options don't consume extra tokens
85: * @param string $default The default value for this option.
86: * @param array $choices Valid choices for this option.
87: * @param bool $multiple Whether this option can accept multiple value definition.
88: * @throws \Cake\Console\Exception\ConsoleException
89: */
90: public function __construct(
91: $name,
92: $short = '',
93: $help = '',
94: $boolean = false,
95: $default = '',
96: $choices = [],
97: $multiple = false
98: ) {
99: if (is_array($name) && isset($name['name'])) {
100: foreach ($name as $key => $value) {
101: $this->{'_' . $key} = $value;
102: }
103: } else {
104: $this->_name = $name;
105: $this->_short = $short;
106: $this->_help = $help;
107: $this->_boolean = $boolean;
108: $this->_default = $default;
109: $this->_choices = $choices;
110: $this->_multiple = $multiple;
111: }
112: if (strlen($this->_short) > 1) {
113: throw new ConsoleException(
114: sprintf('Short option "%s" is invalid, short options must be one letter.', $this->_short)
115: );
116: }
117: }
118:
119: /**
120: * Get the value of the name attribute.
121: *
122: * @return string Value of this->_name.
123: */
124: public function name()
125: {
126: return $this->_name;
127: }
128:
129: /**
130: * Get the value of the short attribute.
131: *
132: * @return string Value of this->_short.
133: */
134: public function short()
135: {
136: return $this->_short;
137: }
138:
139: /**
140: * Generate the help for this this option.
141: *
142: * @param int $width The width to make the name of the option.
143: * @return string
144: */
145: public function help($width = 0)
146: {
147: $default = $short = '';
148: if ($this->_default && $this->_default !== true) {
149: $default = sprintf(' <comment>(default: %s)</comment>', $this->_default);
150: }
151: if ($this->_choices) {
152: $default .= sprintf(' <comment>(choices: %s)</comment>', implode('|', $this->_choices));
153: }
154: if (strlen($this->_short) > 0) {
155: $short = ', -' . $this->_short;
156: }
157: $name = sprintf('--%s%s', $this->_name, $short);
158: if (strlen($name) < $width) {
159: $name = str_pad($name, $width, ' ');
160: }
161:
162: return sprintf('%s%s%s', $name, $this->_help, $default);
163: }
164:
165: /**
166: * Get the usage value for this option
167: *
168: * @return string
169: */
170: public function usage()
171: {
172: $name = (strlen($this->_short) > 0) ? ('-' . $this->_short) : ('--' . $this->_name);
173: $default = '';
174: if (strlen($this->_default) > 0 && $this->_default !== true) {
175: $default = ' ' . $this->_default;
176: }
177: if ($this->_choices) {
178: $default = ' ' . implode('|', $this->_choices);
179: }
180:
181: return sprintf('[%s%s]', $name, $default);
182: }
183:
184: /**
185: * Get the default value for this option
186: *
187: * @return mixed
188: */
189: public function defaultValue()
190: {
191: return $this->_default;
192: }
193:
194: /**
195: * Check if this option is a boolean option
196: *
197: * @return bool
198: */
199: public function isBoolean()
200: {
201: return (bool)$this->_boolean;
202: }
203:
204: /**
205: * Check if this option accepts multiple values.
206: *
207: * @return bool
208: */
209: public function acceptsMultiple()
210: {
211: return (bool)$this->_multiple;
212: }
213:
214: /**
215: * Check that a value is a valid choice for this option.
216: *
217: * @param string $value The choice to validate.
218: * @return bool
219: * @throws \Cake\Console\Exception\ConsoleException
220: */
221: public function validChoice($value)
222: {
223: if (empty($this->_choices)) {
224: return true;
225: }
226: if (!in_array($value, $this->_choices)) {
227: throw new ConsoleException(
228: sprintf(
229: '"%s" is not a valid value for --%s. Please use one of "%s"',
230: $value,
231: $this->_name,
232: implode(', ', $this->_choices)
233: )
234: );
235: }
236:
237: return true;
238: }
239:
240: /**
241: * Append the option's xml into the parent.
242: *
243: * @param \SimpleXMLElement $parent The parent element.
244: * @return \SimpleXMLElement The parent with this option appended.
245: */
246: public function xml(SimpleXMLElement $parent)
247: {
248: $option = $parent->addChild('option');
249: $option->addAttribute('name', '--' . $this->_name);
250: $short = '';
251: if (strlen($this->_short) > 0) {
252: $short = '-' . $this->_short;
253: }
254: $option->addAttribute('short', $short);
255: $option->addAttribute('help', $this->_help);
256: $option->addAttribute('boolean', (int)$this->_boolean);
257: $option->addChild('default', $this->_default);
258: $choices = $option->addChild('choices');
259: foreach ($this->_choices as $valid) {
260: $choices->addChild('choice', $valid);
261: }
262:
263: return $parent;
264: }
265: }
266: