123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366 |
- <?php
-
- /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
-
- /**
- * This file is part of the PEAR Console_CommandLine package.
- *
- * PHP version 5
- *
- * LICENSE: This source file is subject to the MIT license that is available
- * through the world-wide-web at the following URI:
- * http://opensource.org/licenses/mit-license.php
- *
- * @category Console
- * @package Console_CommandLine
- * @author David JEAN LOUIS <izimobil@gmail.com>
- * @copyright 2007 David JEAN LOUIS
- * @license http://opensource.org/licenses/mit-license.php MIT License
- * @version CVS: $Id$
- * @link http://pear.php.net/package/Console_CommandLine
- * @since File available since release 0.1.0
- * @filesource
- */
-
- /**
- * Required by this class.
- */
- require_once 'Console/CommandLine.php';
- require_once 'Console/CommandLine/Element.php';
-
- /**
- * Class that represent a commandline option.
- *
- * @category Console
- * @package Console_CommandLine
- * @author David JEAN LOUIS <izimobil@gmail.com>
- * @copyright 2007 David JEAN LOUIS
- * @license http://opensource.org/licenses/mit-license.php MIT License
- * @version Release: 1.2.2
- * @link http://pear.php.net/package/Console_CommandLine
- * @since Class available since release 0.1.0
- */
- class Console_CommandLine_Option extends Console_CommandLine_Element
- {
- // Public properties {{{
-
- /**
- * The option short name (ex: -v).
- *
- * @var string $short_name Short name of the option
- */
- public $short_name;
-
- /**
- * The option long name (ex: --verbose).
- *
- * @var string $long_name Long name of the option
- */
- public $long_name;
-
- /**
- * The option action, defaults to "StoreString".
- *
- * @var string $action Option action
- */
- public $action = 'StoreString';
-
- /**
- * An array of possible values for the option. If this array is not empty
- * and the value passed is not in the array an exception is raised.
- * This only make sense for actions that accept values of course.
- *
- * @var array $choices Valid choices for the option
- */
- public $choices = array();
-
- /**
- * The callback function (or method) to call for an action of type
- * Callback, this can be any callable supported by the php function
- * call_user_func.
- *
- * Example:
- *
- * <code>
- * $parser->addOption('myoption', array(
- * 'short_name' => '-m',
- * 'long_name' => '--myoption',
- * 'action' => 'Callback',
- * 'callback' => 'myCallbackFunction'
- * ));
- * </code>
- *
- * @var callable $callback The option callback
- */
- public $callback;
-
- /**
- * An associative array of additional params to pass to the class
- * corresponding to the action, this array will also be passed to the
- * callback defined for an action of type Callback, Example:
- *
- * <code>
- * // for a custom action
- * $parser->addOption('myoption', array(
- * 'short_name' => '-m',
- * 'long_name' => '--myoption',
- * 'action' => 'MyCustomAction',
- * 'action_params' => array('foo'=>true, 'bar'=>false)
- * ));
- *
- * // if the user type:
- * // $ <yourprogram> -m spam
- * // in your MyCustomAction class the execute() method will be called
- * // with the value 'spam' as first parameter and
- * // array('foo'=>true, 'bar'=>false) as second parameter
- * </code>
- *
- * @var array $action_params Additional parameters to pass to the action
- */
- public $action_params = array();
-
- /**
- * For options that expect an argument, this property tells the parser if
- * the option argument is optional and can be ommited.
- *
- * @var bool $argumentOptional Whether the option arg is optional or not
- */
- public $argument_optional = false;
-
- /**
- * For options that uses the "choice" property only.
- * Adds a --list-<choice> option to the parser that displays the list of
- * choices for the option.
- *
- * @var bool $add_list_option Whether to add a list option or not
- */
- public $add_list_option = false;
-
- // }}}
- // Private properties {{{
-
- /**
- * When an action is called remember it to allow for multiple calls.
- *
- * @var object $action_instance Placeholder for action
- */
- private $_action_instance = null;
-
- // }}}
- // __construct() {{{
-
- /**
- * Constructor.
- *
- * @param string $name The name of the option
- * @param array $params An optional array of parameters
- *
- * @return void
- */
- public function __construct($name = null, $params = array())
- {
- parent::__construct($name, $params);
- if ($this->action == 'Password') {
- // special case for Password action, password can be passed to the
- // commandline or prompted by the parser
- $this->argument_optional = true;
- }
- }
-
- // }}}
- // toString() {{{
-
- /**
- * Returns the string representation of the option.
- *
- * @param string $delim Delimiter to use between short and long option
- *
- * @return string The string representation of the option
- * @todo use __toString() instead
- */
- public function toString($delim = ", ")
- {
- $ret = '';
- $padding = '';
- if ($this->short_name != null) {
- $ret .= $this->short_name;
- if ($this->expectsArgument()) {
- $ret .= ' ' . $this->help_name;
- }
- $padding = $delim;
- }
- if ($this->long_name != null) {
- $ret .= $padding . $this->long_name;
- if ($this->expectsArgument()) {
- $ret .= '=' . $this->help_name;
- }
- }
- return $ret;
- }
-
- // }}}
- // expectsArgument() {{{
-
- /**
- * Returns true if the option requires one or more argument and false
- * otherwise.
- *
- * @return bool Whether the option expects an argument or not
- */
- public function expectsArgument()
- {
- if ($this->action == 'StoreTrue' || $this->action == 'StoreFalse' ||
- $this->action == 'Help' || $this->action == 'Version' ||
- $this->action == 'Counter' || $this->action == 'List') {
- return false;
- }
- return true;
- }
-
- // }}}
- // dispatchAction() {{{
-
- /**
- * Formats the value $value according to the action of the option and
- * updates the passed Console_CommandLine_Result object.
- *
- * @param mixed $value The value to format
- * @param Console_CommandLine_Result $result The result instance
- * @param Console_CommandLine $parser The parser instance
- *
- * @return void
- * @throws Console_CommandLine_Exception
- */
- public function dispatchAction($value, $result, $parser)
- {
- $actionInfo = Console_CommandLine::$actions[$this->action];
- if (true === $actionInfo[1]) {
- // we have a "builtin" action
- $tokens = explode('_', $actionInfo[0]);
- include_once implode('/', $tokens) . '.php';
- }
- $clsname = $actionInfo[0];
- if ($this->_action_instance === null) {
- $this->_action_instance = new $clsname($result, $this, $parser);
- }
-
- // check value is in option choices
- if (!empty($this->choices) && !in_array($this->_action_instance->format($value), $this->choices)) {
- throw Console_CommandLine_Exception::factory(
- 'OPTION_VALUE_NOT_VALID',
- array(
- 'name' => $this->name,
- 'choices' => implode('", "', $this->choices),
- 'value' => $value,
- ),
- $parser,
- $this->messages
- );
- }
- $this->_action_instance->execute($value, $this->action_params);
- }
-
- // }}}
- // validate() {{{
-
- /**
- * Validates the option instance.
- *
- * @return void
- * @throws Console_CommandLine_Exception
- * @todo use exceptions instead
- */
- public function validate()
- {
- // check if the option name is valid
- if (!preg_match('/^[a-zA-Z_\x7f-\xff]+[a-zA-Z0-9_\x7f-\xff]*$/',
- $this->name)) {
- Console_CommandLine::triggerError('option_bad_name',
- E_USER_ERROR, array('{$name}' => $this->name));
- }
- // call the parent validate method
- parent::validate();
- // a short_name or a long_name must be provided
- if ($this->short_name == null && $this->long_name == null) {
- Console_CommandLine::triggerError('option_long_and_short_name_missing',
- E_USER_ERROR, array('{$name}' => $this->name));
- }
- // check if the option short_name is valid
- if ($this->short_name != null &&
- !(preg_match('/^\-[a-zA-Z]{1}$/', $this->short_name))) {
- Console_CommandLine::triggerError('option_bad_short_name',
- E_USER_ERROR, array(
- '{$name}' => $this->name,
- '{$short_name}' => $this->short_name
- ));
- }
- // check if the option long_name is valid
- if ($this->long_name != null &&
- !preg_match('/^\-\-[a-zA-Z]+[a-zA-Z0-9_\-]*$/', $this->long_name)) {
- Console_CommandLine::triggerError('option_bad_long_name',
- E_USER_ERROR, array(
- '{$name}' => $this->name,
- '{$long_name}' => $this->long_name
- ));
- }
- // check if we have a valid action
- if (!is_string($this->action)) {
- Console_CommandLine::triggerError('option_bad_action',
- E_USER_ERROR, array('{$name}' => $this->name));
- }
- if (!isset(Console_CommandLine::$actions[$this->action])) {
- Console_CommandLine::triggerError('option_unregistered_action',
- E_USER_ERROR, array(
- '{$action}' => $this->action,
- '{$name}' => $this->name
- ));
- }
- // if the action is a callback, check that we have a valid callback
- if ($this->action == 'Callback' && !is_callable($this->callback)) {
- Console_CommandLine::triggerError('option_invalid_callback',
- E_USER_ERROR, array('{$name}' => $this->name));
- }
- }
-
- // }}}
- // setDefaults() {{{
-
- /**
- * Set the default value according to the configured action.
- *
- * Note that for backward compatibility issues this method is only called
- * when the 'force_options_defaults' is set to true, it will become the
- * default behaviour in the next major release of Console_CommandLine.
- *
- * @return void
- */
- public function setDefaults()
- {
- if ($this->default !== null) {
- // already set
- return;
- }
- switch ($this->action) {
- case 'Counter':
- case 'StoreInt':
- $this->default = 0;
- break;
- case 'StoreFloat':
- $this->default = 0.0;
- break;
- case 'StoreArray':
- $this->default = array();
- break;
- case 'StoreTrue':
- $this->default = false;
- break;
- case 'StoreFalse':
- $this->default = true;
- break;
- default:
- return;
- }
- }
-
- // }}}
- }
|