## Apache Zeta Components Manual :: File Source for option.php

## Source for file option.php

Documentation is available at option.php

1. <?php
2. /**
3. * File containing the ezcConsoleOption class.
4. *
5. * Licensed to the Apache Software Foundation (ASF) under one
6. * or more contributor license agreements. See the NOTICE file
7. * distributed with this work for additional information
8. * regarding copyright ownership. The ASF licenses this file
9. * to you under the Apache License, Version 2.0 (the
10. * "License"); you may not use this file except in compliance
11. * with the License. You may obtain a copy of the License at
12. *
13. * http://www.apache.org/licenses/LICENSE-2.0
14. *
15. * Unless required by applicable law or agreed to in writing,
16. * software distributed under the License is distributed on an
17. * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18. * KIND, either express or implied. See the License for the
19. * specific language governing permissions and limitations
20. * under the License.
21. *
22. * @package ConsoleTools
23. * @version //autogentag//
24. * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
25. * @filesource
26. */
28. /**
29. * Objects of this class store data about a single option for ezcConsoleInput.
30. *
31. * This class represents a single command line option, which can be handled by
32. * the ezcConsoleInput class. This classes only purpose is the storage of
33. * the parameter data, the handling of options and arguments is done by the
34. * class {@link ezcConsoleInput}.
35. *
36. * @property-read string $short
37. * Short name of the parameter without '-' (eg. 'f').
38. * @property-read string $long
39. * Long name of the parameter without '--' (eg. 'file').
40. * @property int $type
41. * Value type of this parameter, default is ezcConsoleInput::TYPE_NONE.
42. * See {@link ezcConsoleInput::TYPE_NONE},
43. * {@link ezcConsoleInput::TYPE_INT} and
44. * {@link ezcConsoleInput::TYPE_STRING}.
45. * @property mixed $default
46. * Default value if the parameter is submitted without value. If a
47. * parameter is eg. of type ezcConsoleInput::TYPE_STRING and
48. * therefore expects a value when being submitted, it may be
49. * submitted without a value and automatically get the default value
50. * specified here.
51. * @property bool $multiple
52. * Is the submission of multiple instances of this parameters
53. * allowed?
54. * @property string $shorthelp
55. * Short help text. Usually displayed when showing parameter help
56. * overview.
57. * @property string $longhelp
58. * Long help text. Usually displayed when showing parameter detailed
59. * help.
60. * @property bool $arguments
61. * Whether arguments to the program are allowed, when this parameter
62. * is submitted.
63. * @property bool $mandatory
64. * Whether a parameter is mandatory to be set. If this flag is true,
65. * the parameter must be submitted whenever the program is run.
66. * @property bool $isHelpOption
67. * Whether a parameter is a help option. If this flag is true, and
68. * the parameter is set, all options marked as mandatory may be
69. * skipped.
70. *
71. * @package ConsoleTools
72. * @version //autogen//
73. */
74. class ezcConsoleOption
75. {
76. /**
77. * Container to hold the properties
78. *
79. * @var array(string=>mixed)
80. */
81. protected $properties ;
83. /**
84. * Dependency rules of this parameter.
85. *
86. * @see ezcConsoleOption::addDependency()
87. * @see ezcConsoleOption::removeDependency()
88. * @see ezcConsoleOption::hasDependency()
89. * @see ezcConsoleOption::getDependencies()
90. * @see ezcConsoleOption::resetDependencies()
91. *
92. * @var array(string=>ezcConsoleParamemterRule)
93. */
94. protected $dependencies = array();
96. /**
97. * Exclusion rules of this parameter.
98. *
99. * @see ezcConsoleOption::addExclusion()
100. * @see ezcConsoleOption::removeExclusion()
101. * @see ezcConsoleOption::hasExclusion()
102. * @see ezcConsoleOption::getExclusions()
103. * @see ezcConsoleOption::resetExclusions()
104. *
105. * @var array(string=>ezcConsoleParamemterRule)
106. */
107. protected $exclusions = array();
109. /**
110. * The value the parameter was assigned to when being submitted.
111. * Boolean false indicates the parameter was not submitted, boolean
112. * true means the parameter was submitted, but did not have a value.
113. * In any other case, this caries the submitted value.
114. *
115. * @var mixed
116. */
117. public $value = false;
119. /**
120. * Create a new parameter struct.
121. * Creates a new basic parameter struct with the base information "$short"
122. * (the short name of the parameter) and "$long" (the long version). You
123. * simply apply these parameters as strings (without '-' or '--'). So
124. *
125. * <code>
126. * $param = new ezcConsoleOption( 'f', 'file' );
127. * </code>
128. *
129. * will result in a parameter that can be accessed using
130. *
131. * <code>
132. * $ mytool -f
133. * </code>
134. *
135. * or
136. *
137. * <code>
138. * $ mytool --file
139. * </code>
140. * .
141. *
142. * The newly created parameter contains only it's 2 names and each other
143. * attribute is set to it's default value. You can simply manipulate
144. * those attributes by accessing them directly.
145. *
146. * @param string $short Short name of the parameter without '-' (eg. 'f').
147. * @param string $long Long name of the parameter without '--' (eg. 'file').
148. * @param int $type Value type of the parameter. One of ezcConsoleInput::TYPE_*.
149. * @param mixed $default Default value the parameter holds if not submitted.
150. * @param bool $multiple If the parameter may be submitted multiple times.
151. * @param string $shorthelp Short help text.
152. * @param string $longhelp Long help text.
153. * @param array(ezcConsoleOptionRule) $dependencies Dependency rules.
154. * @param array(ezcConsoleOptionRule) $exclusions Exclusion rules.
155. * @param bool $arguments Whether supplying arguments is allowed when this parameter is set.
156. * @param bool $mandatory Whether the parameter must be always submitted.
157. * @param bool $isHelpOption Indicates that the given parameter is a help
158. * option. If a help option is set, all rule
159. * checking is skipped (dependency/exclusion/
160. * mandatory).
161. *
162. * @throws ezcConsoleInvalidOptionNameException If the option names start with a "-"
163. * sign or contain whitespaces.
164. */
165. public function __construct (
166. $short = '',
167. $long,
168. $type = ezcConsoleInput::TYPE_NONE,
169. $default = null,
170. $multiple = false,
171. $shorthelp = 'No help available.',
172. $longhelp = 'Sorry, there is no help text available for this parameter.',
173. array $dependencies = array(),
174. array $exclusions = array(),
175. $arguments = true,
176. $mandatory = false,
177. $isHelpOption = false
178. )
179. {
180. $this-> properties ['short'] = '';
181. $this-> properties ['long'] = '';
182. $this-> properties ['arguments'] = $arguments;
184. if ( !self::validateOptionName( $short ) )
185. {
186. throw new ezcConsoleInvalidOptionNameException ( $short );
187. }
188. $this-> properties ['short'] = $short;
190. if ( !self::validateOptionName( $long ) )
191. {
192. throw new ezcConsoleInvalidOptionNameException ( $long );
193. }
194. $this-> properties ['long'] = $long;
196. $this->__set( "type", $type !== null ? $type : ezcConsoleInput ::TYPE_NONE );
197. $this->__set( "multiple", $multiple !== null ? $multiple : false );
198. $this->__set( "default", $default !== null ? $default : null );
199. $this->__set( "shorthelp", $shorthelp !== null ? $shorthelp : 'No help available.' );
200. $this->__set( "longhelp", $longhelp !== null ? $longhelp : 'Sorry, there is no help text available for this parameter.' );
202. $dependencies = $dependencies !== null && is_array ( $dependencies ) ? $dependencies : array();
203. foreach ( $dependencies as $dep )
204. {
205. $this-> addDependency ( $dep );
206. }
208. $exclusions = $exclusions !== null && is_array ( $exclusions ) ? $exclusions : array();
209. foreach ( $exclusions as $exc )
210. {
211. $this-> addExclusion ( $exc );
212. }
214. $this->__set( "mandatory", $mandatory !== null ? $mandatory : false );
215. $this->__set( "isHelpOption", $isHelpOption !== null ? $isHelpOption : false );
216. }
218. /**
219. * Add a new dependency for a parameter.
220. * This registeres a new dependency rule with the parameter. If you try
221. * to add an already registered rule it will simply be ignored. Else,
222. * the submitted rule will be added to the parameter as a dependency.
223. *
224. * @param ezcConsoleOptionRule $rule The rule to add.
225. * @return void
226. */
227. public function addDependency ( ezcConsoleOptionRule $rule )
228. {
229. foreach ( $this-> dependencies as $existRule )
230. {
231. if ( $rule == $existRule )
232. {
233. return;
234. }
235. }
236. $this-> dependencies [] = $rule;
237. }
239. /**
240. * Remove a dependency rule from a parameter.
241. * This removes a given rule from a parameter, if it exists. If the rule is
242. * not registered with the parameter, the method call will simply be ignored.
243. *
244. * @param ezcConsoleOptionRule $rule The rule to be removed.
245. * @return void
246. */
247. public function removeDependency ( ezcConsoleOptionRule $rule )
248. {
249. foreach ( $this-> dependencies as $id => $existRule )
250. {
251. if ( $rule == $existRule )
252. {
253. unset( $this-> dependencies [$id] );
254. }
255. }
256. }
258. /**
259. * Remove all dependency rule referring to a parameter.
260. * This removes all dependency rules from a parameter, that refer to as specific
261. * parameter. If no rule is registered with this parameter as reference, the
262. * method call will simply be ignored.
263. *
264. * @param ezcConsoleOption $param The param to be check for rules.
265. * @return void
266. */
267. public function removeAllDependencies ( ezcConsoleOption $param )
268. {
269. foreach ( $this-> dependencies as $id => $rule )
270. {
271. if ( $rule->option == $param )
272. {
273. unset( $this-> dependencies [$id] );
274. }
275. }
276. }
278. /**
279. * Returns if a dependency to the given option exists.
280. * Returns true if a dependency rule to the given option is registered,
281. * otherwise false.
282. *
283. * @param ezcConsoleOption $param The param to check if a dependency exists to.
284. * @return bool True if rule is registered, otherwise false.
285. */
286. public function hasDependency ( ezcConsoleOption $param )
287. {
288. foreach ( $this-> dependencies as $id => $rule )
289. {
290. if ( $rule->option == $param )
291. {
292. return true;
293. }
294. }
295. return false;
296. }
298. /**
299. * Returns the dependency rules registered with this parameter.
300. * Returns an array of registered dependencies.
301. *
302. * For example:
303. * <code>
304. * array(
305. * 0 => ezcConsoleOptionRule,
306. * 1 => ezcConsoleOptionRule,
307. * 2 => ezcConsoleOptionRule,
308. * );
309. * </code>
310. *
311. * @return array(ezcConsoleOptionRule) Dependency definition.
312. */
313. public function getDependencies ()
314. {
315. return $this-> dependencies ;
316. }
318. /**
319. * Reset existing dependency rules.
320. * Deletes all registered dependency rules from the option definition.
321. *
322. * @return void
323. */
324. public function resetDependencies ()
325. {
326. $this-> dependencies = array();
327. }
329. /**
330. * Add a new exclusion for an option.
331. * This registeres a new exclusion rule with the option. If you try
332. * to add an already registered rule it will simply be ignored. Else,
333. * the submitted rule will be added to the option as a exclusion.
334. *
335. * @param ezcConsoleOptionRule $rule The rule to add.
336. * @return void
337. */
338. public function addExclusion ( ezcConsoleOptionRule $rule )
339. {
340. foreach ( $this-> exclusions as $existRule )
341. {
342. if ( $rule == $existRule )
343. {
344. return;
345. }
346. }
347. $this-> exclusions [] = $rule;
348. }
350. /**
351. * Remove a exclusion rule from a option.
352. * This removes a given rule from a option, if it exists. If the rule is
353. * not registered with the option, the method call will simply be ignored.
354. *
355. * @param ezcConsoleOptionRule $rule The rule to be removed.
356. * @return void
357. */
358. public function removeExclusion ( ezcConsoleOptionRule $rule )
359. {
360. foreach ( $this-> exclusions as $id => $existRule )
361. {
362. if ( $rule == $existRule )
363. {
364. unset( $this-> exclusions [$id] );
365. }
366. }
367. }
369. /**
370. * Remove all exclusion rule referring to a option.
371. * This removes all exclusion rules from a option, that refer to as specific
372. * option. If no rule is registered with this option as reference, the
373. * method call will simply be ignored.
374. *
375. * @param ezcConsoleOption $param The option to remove rule for.
376. * @return void
377. */
378. public function removeAllExclusions ( ezcConsoleOption $param )
379. {
380. foreach ( $this-> exclusions as $id => $rule )
381. {
382. if ( $rule->option == $param )
383. {
384. unset( $this-> exclusions [$id] );
385. }
386. }
387. }
389. /**
390. * Returns if a given exclusion rule is registered with the option.
391. * Returns true if a exclusion rule to the given option is registered,
392. * otherwise false.
393. *
394. * @param ezcConsoleOption $param The param to check if exclusions exist for.
395. * @return bool True if rule is registered, otherwise false.
396. */
397. public function hasExclusion ( ezcConsoleOption $param )
398. {
399. foreach ( $this-> exclusions as $id => $rule )
400. {
401. if ( $rule->option == $param )
402. {
403. return true;
404. }
405. }
406. return false;
407. }
409. /**
410. * Returns the exclusion rules registered with this parameter.
411. * Returns an array of registered exclusions.
412. *
413. * For example:
414. * <code>
415. * array(
416. * 0 => ezcConsoleOptionRule,
417. * 1 => ezcConsoleOptionRule,
418. * 2 => ezcConsoleOptionRule,
419. * );
420. * </code>
421. *
422. * @return array(ezcConsoleOptionRule) Exclusions definition.
423. */
424. public function getExclusions ()
425. {
426. return $this-> exclusions ;
427. }
429. /**
430. * Reset existing exclusion rules.
431. * Deletes all registered exclusion rules from the option definition.
432. *
433. * @return void
434. */
435. public function resetExclusions ()
436. {
437. $this-> exclusions = array();
438. }
440. /**
441. * Property read access.
442. * Provides read access to the properties of the object.
443. *
444. * @param string $key The name of the property.
445. * @return mixed The value if property exists and isset, otherwise null.
446. * @ignore
447. */
448. public function __get( $key )
449. {
450. switch ( $key )
451. {
452. case 'short':
453. case 'long':
454. case 'type':
455. case 'default':
456. case 'multiple':
457. case 'shorthelp':
458. case 'longhelp':
459. case 'arguments':
460. case 'isHelpOption':
461. case 'mandatory':
462. return $this-> properties [$key];
463. case 'dependencies':
464. default:
465. throw new ezcBasePropertyNotFoundException ( $key );
466. }
467. }
469. /**
470. * Property write access.
471. *
472. * @param string $key Name of the property.
473. * @param mixed $val The value for the property.
474. *
475. * @throws ezcBasePropertyPermissionException
476. * If the property you try to access is read-only.
477. * @throws ezcBasePropertyNotFoundException
478. * If the the desired property is not found.
479. * @ignore
480. */
481. public function __set( $key, $val )
482. {
483. switch ( $key )
484. {
485. case 'type':
486. if ( $val !== ezcConsoleInput ::TYPE_NONE
487. && $val !== ezcConsoleInput ::TYPE_INT
488. && $val !== ezcConsoleInput ::TYPE_STRING )
489. {
490. throw new ezcBaseValueException (
491. $key,
492. $val,
493. 'ezcConsoleInput::TYPE_STRING, ezcConsoleInput::TYPE_INT or ezcConsoleInput::TYPE_NONE'
494. );
495. }
496. break;
497. case 'default':
498. if ( ( is_scalar ( $val ) === false && $val !== null ) )
499. {
500. // Newly allow arrays, if multiple is true
501. if ( $this->multiple === true && is_array ( $val ) === true )
502. {
503. break;
504. }
505. throw new ezcBaseValueException ( $key, $val, 'a string or a number, if multiple == true also an array' );
506. }
507. break;
508. case 'multiple':
509. if ( ! is_bool ( $val ) )
510. {
511. throw new ezcBaseValueException ( $key, $val, 'bool' );
512. }
513. break;
514. case 'shorthelp':
515. if ( ! is_string ( $val ) )
516. {
517. throw new ezcBaseValueException ( $key, $val, 'string' );
518. }
519. break;
520. case 'longhelp':
521. if ( ! is_string ( $val ) )
522. {
523. throw new ezcBaseValueException ( $key, $val, 'string' );
524. }
525. break;
526. case 'arguments':
527. if ( ! is_bool ( $val ) )
528. {
529. throw new ezcBaseValueException ( $key, $val, 'bool' );
530. }
531. break;
532. case 'mandatory':
533. if ( ! is_bool ( $val ) )
534. {
535. throw new ezcBaseValueException ( $key, $val, 'bool' );
536. }
537. break;
538. case 'isHelpOption':
539. if ( ! is_bool ( $val ) )
540. {
541. throw new ezcBaseValueException ( $key, $val, 'bool' );
542. }
543. break;
544. case 'long':
545. case 'short':
546. throw new ezcBasePropertyPermissionException ( $key, ezcBasePropertyPermissionException ::READ );
547. break;
548. default:
549. throw new ezcBasePropertyNotFoundException ( $key );
550. break;
551. }
552. $this-> properties [$key] = $val;
553. }
555. /**
556. * Property isset access.
557. *
558. * @param string $key Name of the property.
559. * @return bool True is the property is set, otherwise false.
560. * @ignore
561. */
562. public function __isset( $key )
563. {
564. switch ( $key )
565. {
566. case 'short':
567. case 'long':
568. case 'type':
569. case 'default':
570. case 'multiple':
571. case 'shorthelp':
572. case 'longhelp':
573. case 'arguments':
574. case 'isHelpOption':
575. case 'mandatory':
576. return ( $this-> properties [$key] !== null );
577. }
578. return false;
579. }
581. /**
582. * Returns if a given name if valid for use as a parameter name a parameter.
583. * Checks if a given parameter name is generally valid for use. It checks a)
584. * that the name does not start with '-' or '--' and b) if it contains
585. * whitespaces. Note, that this method does not check any conflicts with already
586. * used parameter names.
587. *
588. * @param string $name The name to check.
589. * @return bool True if the name is valid, otherwise false.
590. */
591. public static function validateOptionName ( $name )
592. {
593. if ( substr ( $name, 0, 1 ) === '-' || strpos ( $name, ' ' ) !== false )
594. {
595. return false;
596. }
597. return true;
598. }
599. }
601. ?>

Documentation generated by phpDocumentor 1.4.3