<?php

/**

 * Zend_Console_Getopt is a class to parse options for command-line

 * applications.

 *

 * LICENSE

 *

 * This source file is subject to the new BSD license that is bundled

 * with this package in the file LICENSE.txt.

 * It is also available through the world-wide-web at this URL:

 * http://framework.zend.com/license/new-bsd

 * If you did not receive a copy of the license and are unable to

 * obtain it through the world-wide-web, please send an email

 * to license@zend.com so we can send you a copy immediately.

 *

 * @category   Zend

 * @package    Zend_Console_Getopt

 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

 * @license    http://framework.zend.com/license/new-bsd     New BSD License

 * @version    $Id: Getopt.php 22191 2010-05-17 21:50:14Z jan $

 */

/**

 * Zend_Console_Getopt is a class to parse options for command-line

 * applications.

 *

 * Terminology:

 * Argument: an element of the argv array.  This may be part of an option,

 *   or it may be a non-option command-line argument.

 * Flag: the letter or word set off by a '-' or '--'.  Example: in '--output filename',

 *   '--output' is the flag.

 * Parameter: the additional argument that is associated with the option.

 *   Example: in '--output filename', the 'filename' is the parameter.

 * Option: the combination of a flag and its parameter, if any.

 *   Example: in '--output filename', the whole thing is the option.

 *

 * The following features are supported:

 *

 * - Short flags like '-a'.  Short flags are preceded by a single

 *   dash.  Short flags may be clustered e.g. '-abc', which is the

 *   same as '-a' '-b' '-c'.

 * - Long flags like '--verbose'.  Long flags are preceded by a

 *   double dash.  Long flags may not be clustered.

 * - Options may have a parameter, e.g. '--output filename'.

 * - Parameters for long flags may also be set off with an equals sign,

 *   e.g. '--output=filename'.

 * - Parameters for long flags may be checked as string, word, or integer.

 * - Automatic generation of a helpful usage message.

 * - Signal end of options with '--'; subsequent arguments are treated

 *   as non-option arguments, even if they begin with '-'.

 * - Raise exception Zend_Console_Getopt_Exception in several cases

 *   when invalid flags or parameters are given.  Usage message is

 *   returned in the exception object.

 *

 * The format for specifying options uses a PHP associative array.

 * The key is has the format of a list of pipe-separated flag names,

 * followed by an optional '=' to indicate a required parameter or

 * '-' to indicate an optional parameter.  Following that, the type

 * of parameter may be specified as 's' for string, 'w' for word,

 * or 'i' for integer.

 *

 * Examples:

 * - 'user|username|u=s'  this means '--user' or '--username' or '-u'

 *   are synonyms, and the option requires a string parameter.

 * - 'p=i'  this means '-p' requires an integer parameter.  No synonyms.

 * - 'verbose|v-i'  this means '--verbose' or '-v' are synonyms, and

 *   they take an optional integer parameter.

 * - 'help|h'  this means '--help' or '-h' are synonyms, and

 *   they take no parameter.

 *

 * The values in the associative array are strings that are used as

 * brief descriptions of the options when printing a usage message.

 *

 * The simpler format for specifying options used by PHP's getopt()

 * function is also supported.  This is similar to GNU getopt and shell

 * getopt format.

 *

 * Example:  'abc:' means options '-a', '-b', and '-c'

 * are legal, and the latter requires a string parameter.

 *

 * @category   Zend

 * @package    Zend_Console_Getopt

 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

 * @license    http://framework.zend.com/license/new-bsd     New BSD License

 * @version    Release: @package_version@

 * @since      Class available since Release 0.6.0

 *

 * @todo  Handle params with multiple values, e.g. --colors=red,green,blue

 *        Set value of parameter to the array of values.  Allow user to specify

 *        the separator with Zend_Console_Getopt::CONFIG_PARAMETER_SEPARATOR.

 *        If this config value is null or empty string, do not split values

 *        into arrays.  Default separator is comma (',').

 *

 * @todo  Handle params with multiple values specified with separate options

 *        e.g. --colors red --colors green --colors blue should give one

 *        option with an array(red, green, blue).

 *        Enable with Zend_Console_Getopt::CONFIG_CUMULATIVE_PARAMETERS.

 *        Default is that subsequent options overwrite the parameter value.

 *

 * @todo  Handle flags occurring multiple times, e.g. -v -v -v

 *        Set value of the option's parameter to the integer count of instances

 *        instead of a boolean.

 *        Enable with Zend_Console_Getopt::CONFIG_CUMULATIVE_FLAGS.

 *        Default is that the value is simply boolean true regardless of

 *        how many instances of the flag appear.

 *

 * @todo  Handle flags that implicitly print usage message, e.g. --help

 *

 * @todo  Handle freeform options, e.g. --set-variable

 *        Enable with Zend_Console_Getopt::CONFIG_FREEFORM_FLAGS

 *        All flag-like syntax is recognized, no flag generates an exception.

 *

 * @todo  Handle numeric options, e.g. -1, -2, -3, -1000

 *        Enable with Zend_Console_Getopt::CONFIG_NUMERIC_FLAGS

 *        The rule must specify a named flag and the '#' symbol as the

 *        parameter type. e.g.,  'lines=#'

 *

 * @todo  Enable user to specify header and footer content in the help message.

 *

 * @todo  Feature request to handle option interdependencies.

 *        e.g. if -b is specified, -a must be specified or else the

 *        usage is invalid.

 *

 * @todo  Feature request to implement callbacks.

 *        e.g. if -a is specified, run function 'handleOptionA'().

 */

class Zend_Console_Getopt

{

    /**

     * The options for a given application can be in multiple formats.

     * modeGnu is for traditional 'ab:c:' style getopt format.

     * modeZend is for a more structured format.

     */

    const MODE_ZEND                         = 'zend';

    const MODE_GNU                          = 'gnu';

    /**

     * Constant tokens for various symbols used in the mode_zend

     * rule format.

     */

    const PARAM_REQUIRED                    = '=';

    const PARAM_OPTIONAL                    = '-';

    const TYPE_STRING                       = 's';

    const TYPE_WORD                         = 'w';

    const TYPE_INTEGER                      = 'i';

    /**

     * These are constants for optional behavior of this class.

     * ruleMode is either 'zend' or 'gnu' or a user-defined mode.

     * dashDash is true if '--' signifies the end of command-line options.

     * ignoreCase is true if '--opt' and '--OPT' are implicitly synonyms.

     * parseAll is true if all options on the command line should be parsed, regardless of

     * whether an argument appears before them.

     */

    const CONFIG_RULEMODE                   = 'ruleMode';

    const CONFIG_DASHDASH                   = 'dashDash';

    const CONFIG_IGNORECASE                 = 'ignoreCase';

    const CONFIG_PARSEALL                   = 'parseAll';

    /**

     * Defaults for getopt configuration are:

     * ruleMode is 'zend' format,

     * dashDash (--) token is enabled,

     * ignoreCase is not enabled,

     * parseAll is enabled.

     */

    protected $_getoptConfig = array(

        self::CONFIG_RULEMODE   => self::MODE_ZEND,

        self::CONFIG_DASHDASH   => true,

        self::CONFIG_IGNORECASE => false,

        self::CONFIG_PARSEALL   => true,

    );

    /**

     * Stores the command-line arguments for the calling applicaion.

     *

     * @var array

     */

    protected $_argv = array();

    /**

     * Stores the name of the calling applicaion.

     *

     * @var string

     */

    protected $_progname = '';

    /**

     * Stores the list of legal options for this application.

     *

     * @var array

     */

    protected $_rules = array();

    /**

     * Stores alternate spellings of legal options.

     *

     * @var array

     */

    protected $_ruleMap = array();

    /**

     * Stores options given by the user in the current invocation

     * of the application, as well as parameters given in options.

     *

     * @var array

     */

    protected $_options = array();

    /**

     * Stores the command-line arguments other than options.

     *

     * @var array

     */

    protected $_remainingArgs = array();

    /**

     * State of the options: parsed or not yet parsed?

     *

     * @var boolean

     */

    protected $_parsed = false;

    /**

     * The constructor takes one to three parameters.

     *

     * The first parameter is $rules, which may be a string for

     * gnu-style format, or a structured array for Zend-style format.

     *

     * The second parameter is $argv, and it is optional.  If not

     * specified, $argv is inferred from the global argv.

     *

     * The third parameter is an array of configuration parameters

     * to control the behavior of this instance of Getopt; it is optional.

     *

     * @param  array $rules

     * @param  array $argv

     * @param  array $getoptConfig

     * @return void

     */

    public function __construct($rules, $argv = null, $getoptConfig = array())

    {

        if (!isset($_SERVER['argv'])) {

            require_once 'Zend/Console/Getopt/Exception.php';

            if (ini_get('register_argc_argv') == false) {

                throw new Zend_Console_Getopt_Exception(

                    "argv is not available, because ini option 'register_argc_argv' is set Off"

                );

            } else {

                throw new Zend_Console_Getopt_Exception(

                    '$_SERVER["argv"] is not set, but Zend_Console_Getopt cannot work without this information.'

                );

            }

        }

        $this->_progname = $_SERVER['argv'][0];

        $this->setOptions($getoptConfig);

        $this->addRules($rules);

        if (!is_array($argv)) {

            $argv = array_slice($_SERVER['argv'], 1);

        }

        if (isset($argv)) {

            $this->addArguments((array)$argv);

        }

    }

    /**

     * Return the state of the option seen on the command line of the

     * current application invocation.  This function returns true, or the

     * parameter to the option, if any.  If the option was not given,

     * this function returns null.

     *

     * The magic __get method works in the context of naming the option

     * as a virtual member of this class.

     *

     * @param  string $key

     * @return string

     */

    public function __get($key)

    {

        return $this->getOption($key);

    }

    /**

     * Test whether a given option has been seen.

     *

     * @param  string $key

     * @return boolean

     */

    public function __isset($key)

    {

        $this->parse();

        if (isset($this->_ruleMap[$key])) {

            $key = $this->_ruleMap[$key];

            return isset($this->_options[$key]);

        }

        return false;

    }

    /**

     * Set the value for a given option.

     *

     * @param  string $key

     * @param  string $value

     * @return void

     */

    public function __set($key, $value)

    {

        $this->parse();

        if (isset($this->_ruleMap[$key])) {

            $key = $this->_ruleMap[$key];

            $this->_options[$key] = $value;

        }

    }

    /**

     * Return the current set of options and parameters seen as a string.

     *

     * @return string

     */

    public function __toString()

    {

        return $this->toString();

    }

    /**

     * Unset an option.

     *

     * @param  string $key

     * @return void

     */

    public function __unset($key)

    {

        $this->parse();

        if (isset($this->_ruleMap[$key])) {

            $key = $this->_ruleMap[$key];

            unset($this->_options[$key]);

        }

    }

    /**

     * Define additional command-line arguments.

     * These are appended to those defined when the constructor was called.

     *

     * @param  array $argv

     * @throws Zend_Console_Getopt_Exception When not given an array as parameter

     * @return Zend_Console_Getopt Provides a fluent interface

     */

    public function addArguments($argv)

    {

        if(!is_array($argv)) {

            require_once 'Zend/Console/Getopt/Exception.php';

            throw new Zend_Console_Getopt_Exception(

                "Parameter #1 to addArguments should be an array");

        }

        $this->_argv = array_merge($this->_argv, $argv);

        $this->_parsed = false;

        return $this;

    }

    /**

     * Define full set of command-line arguments.

     * These replace any currently defined.

     *

     * @param  array $argv

     * @throws Zend_Console_Getopt_Exception When not given an array as parameter

     * @return Zend_Console_Getopt Provides a fluent interface

     */

    public function setArguments($argv)

    {

        if(!is_array($argv)) {

            require_once 'Zend/Console/Getopt/Exception.php';

            throw new Zend_Console_Getopt_Exception(

                "Parameter #1 to setArguments should be an array");

        }

        $this->_argv = $argv;

        $this->_parsed = false;

        return $this;

    }

    /**

     * Define multiple configuration options from an associative array.

     * These are not program options, but properties to configure

     * the behavior of Zend_Console_Getopt.

     *

     * @param  array $getoptConfig

     * @return Zend_Console_Getopt Provides a fluent interface

     */

    public function setOptions($getoptConfig)

    {

        if (isset($getoptConfig)) {

            foreach ($getoptConfig as $key => $value) {

                $this->setOption($key, $value);

            }

        }

        return $this;

    }

    /**

     * Define one configuration option as a key/value pair.

     * These are not program options, but properties to configure

     * the behavior of Zend_Console_Getopt.

     *

     * @param  string $configKey

     * @param  string $configValue

     * @return Zend_Console_Getopt Provides a fluent interface

     */

    public function setOption($configKey, $configValue)

    {

        if ($configKey !== null) {

            $this->_getoptConfig[$configKey] = $configValue;

        }

        return $this;

    }

    /**

     * Define additional option rules.

     * These are appended to the rules defined when the constructor was called.

     *

     * @param  array $rules

     * @return Zend_Console_Getopt Provides a fluent interface

     */

    public function addRules($rules)

    {

        $ruleMode = $this->_getoptConfig['ruleMode'];

        switch ($this->_getoptConfig['ruleMode']) {

            case self::MODE_ZEND:

                if (is_array($rules)) {

                    $this->_addRulesModeZend($rules);

                    break;

                }

                // intentional fallthrough

            case self::MODE_GNU:

                $this->_addRulesModeGnu($rules);

                break;

            default:

                /**

                 * Call addRulesModeFoo() for ruleMode 'foo'.

                 * The developer should subclass Getopt and

                 * provide this method.

                 */

                $method = '_addRulesMode' . ucfirst($ruleMode);

                $this->$method($rules);

        }

        $this->_parsed = false;

        return $this;

    }

    /**

     * Return the current set of options and parameters seen as a string.

     *

     * @return string

     */

    public function toString()

    {

        $this->parse();

        $s = array();

        foreach ($this->_options as $flag => $value) {

            $s[] = $flag . '=' . ($value === true ? 'true' : $value);

        }

        return implode(' ', $s);

    }