PageRenderTime 224ms CodeModel.GetById 120ms app.highlight 9ms RepoModel.GetById 92ms app.codeStats 1ms

/docs/languages/en/modules/zend.console.getopt.configuration.rst

https://github.com/Xerkus/zf2-documentation
ReStructuredText | 197 lines | 137 code | 60 blank | 0 comment | 0 complexity | 5b17e1d9a328abd8762eb42ced3a9fb5 MD5 | raw file
  1.. _zend.console.getopt.configuration:
  2
  3Configuring Zend\\Console\\Getopt
  4=================================
  5
  6.. _zend.console.getopt.configuration.addrules:
  7
  8Adding Option Rules
  9-------------------
 10
 11You can add more option rules in addition to those you specified in the ``Zend\Console\Getopt`` constructor, using
 12the ``addRules()`` method. The argument to ``addRules()`` is the same as the first argument to the class
 13constructor. It is either a string in the format of the short syntax options specification, or else an associative
 14array in the format of a long syntax options specification. See :ref:`Declaring Getopt Rules
 15<zend.console.getopt.rules>` for details on the syntax for specifying options.
 16
 17.. _zend.console.getopt.configuration.addrules.example:
 18
 19Using addRules()
 20^^^^^^^^^^^^^^^^
 21
 22.. code-block:: php
 23   :linenos:
 24
 25   $opts = new Zend\Console\Getopt('abp:');
 26   $opts->addRules(
 27     array(
 28       'verbose|v' => 'Print verbose output'
 29     )
 30   );
 31
 32The example above shows adding the ``--verbose`` option with an alias of ``-v`` to a set of options defined in the
 33call to the constructor. Notice that you can mix short format options and long format options in the same instance
 34of ``Zend\Console\Getopt``.
 35
 36.. _zend.console.getopt.configuration.addhelp:
 37
 38Adding Help Messages
 39--------------------
 40
 41In addition to specifying the help strings when declaring option rules in the long format, you can associate help
 42strings with option rules using the ``setHelp()`` method. The argument to the ``setHelp()`` method is an
 43associative array, in which the key is a flag, and the value is a corresponding help string.
 44
 45.. _zend.console.getopt.configuration.addhelp.example:
 46
 47Using setHelp()
 48^^^^^^^^^^^^^^^
 49
 50.. code-block:: php
 51   :linenos:
 52
 53   $opts = new Zend\Console\Getopt('abp:');
 54   $opts->setHelp(
 55       array(
 56           'a' => 'apple option, with no parameter',
 57           'b' => 'banana option, with required integer parameter',
 58           'p' => 'pear option, with optional string parameter'
 59       )
 60   );
 61
 62If you declared options with aliases, you can use any of the aliases as the key of the associative array.
 63
 64The ``setHelp()`` method is the only way to define help strings if you declared the options using the short syntax.
 65
 66.. _zend.console.getopt.configuration.addaliases:
 67
 68Adding Option Aliases
 69---------------------
 70
 71You can declare aliases for options using the ``setAliases()`` method. The argument is an associative array, whose
 72key is a flag string declared previously, and whose value is a new alias for that flag. These aliases are merged
 73with any existing aliases. In other words, aliases you declared earlier are still in effect.
 74
 75An alias may be declared only once. If you try to redefine an alias, a ``Zend\Console\Getopt\Exception`` is thrown.
 76
 77.. _zend.console.getopt.configuration.addaliases.example:
 78
 79Using setAliases()
 80^^^^^^^^^^^^^^^^^^
 81
 82.. code-block:: php
 83   :linenos:
 84
 85   $opts = new Zend\Console\Getopt('abp:');
 86   $opts->setAliases(
 87       array(
 88           'a' => 'apple',
 89           'a' => 'apfel',
 90           'p' => 'pear'
 91       )
 92   );
 93
 94In the example above, after declaring these aliases, ``-a``, ``--apple`` and ``--apfel`` are aliases for each
 95other. Also ``-p`` and ``--pear`` are aliases for each other.
 96
 97The ``setAliases()`` method is the only way to define aliases if you declared the options using the short syntax.
 98
 99.. _zend.console.getopt.configuration.addargs:
100
101Adding Argument Lists
102---------------------
103
104By default, ``Zend\Console\Getopt`` uses ``$_SERVER['argv']`` for the array of command-line arguments to parse. You
105can alternatively specify the array of arguments as the second constructor argument. Finally, you can append more
106arguments to those already used using the ``addArguments()`` method, or you can replace the current array of
107arguments using the ``setArguments()`` method. In both cases, the parameter to these methods is a simple array of
108strings. The former method appends the array to the current arguments, and the latter method substitutes the array
109for the current arguments.
110
111.. _zend.console.getopt.configuration.addargs.example:
112
113Using addArguments() and setArguments()
114^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
115
116.. code-block:: php
117   :linenos:
118
119   // By default, the constructor uses $_SERVER['argv']
120   $opts = new Zend\Console\Getopt('abp:');
121
122   // Append an array to the existing arguments
123   $opts->addArguments(array('-a', '-p', 'p_parameter', 'non_option_arg'));
124
125   // Substitute a new array for the existing arguments
126   $opts->setArguments(array('-a', '-p', 'p_parameter', 'non_option_arg'));
127
128.. _zend.console.getopt.configuration.config:
129
130Adding Configuration
131--------------------
132
133The third parameter to the ``Zend\Console\Getopt`` constructor is an array of configuration options that affect the
134behavior of the object instance returned. You can also specify configuration options using the ``setOptions()``
135method, or you can set an individual option using the ``setOption()`` method.
136
137.. note::
138
139   **Clarifying the Term "option"**
140
141   The term "option" is used for configuration of the ``Zend\Console\Getopt`` class to match terminology used
142   elsewhere in Zend Framework. These are not the same things as the command-line options that are parsed by the
143   ``Zend\Console\Getopt`` class.
144
145The currently supported options have const definitions in the class. The options, their const identifiers (with
146literal values in parentheses) are listed below:
147
148- ``Zend\Console\Getopt::CONFIG_DASHDASH`` ("dashDash"), if ``TRUE``, enables the special flag ``--`` to signify
149  the end of flags. Command-line arguments following the double-dash signifier are not interpreted as options, even
150  if the arguments start with a dash. This configuration option is ``TRUE`` by default.
151
152- ``Zend\Console\Getopt::CONFIG_IGNORECASE`` ("ignoreCase"), if ``TRUE``, makes flags aliases of each other if they
153  differ only in their case. That is, ``-a`` and ``-A`` will be considered to be synonymous flags. This
154  configuration option is ``FALSE`` by default.
155
156- ``Zend\Console\Getopt::CONFIG_RULEMODE`` ("ruleMode") may have values ``Zend\Console\Getopt::MODE_ZEND`` ("zend")
157  and ``Zend\Console\Getopt::MODE_GNU`` ("gnu"). It should not be necessary to use this option unless you extend
158  the class with additional syntax forms. The two modes supported in the base ``Zend\Console\Getopt`` class are
159  unambiguous. If the specifier is a string, the class assumes ``MODE_GNU``, otherwise it assumes ``MODE_ZEND``.
160  But if you extend the class and add more syntax forms, you may need to specify the mode using this option.
161
162More configuration options may be added as future enhancements of this class.
163
164The two arguments to the ``setOption()`` method are a configuration option name and an option value.
165
166.. _zend.console.getopt.configuration.config.example.setoption:
167
168Using setOption()
169^^^^^^^^^^^^^^^^^
170
171.. code-block:: php
172   :linenos:
173
174   $opts = new Zend\Console\Getopt('abp:');
175   $opts->setOption('ignoreCase', true);
176
177The argument to the ``setOptions()`` method is an associative array. The keys of this array are the configuration
178option names, and the values are configuration values. This is also the array format used in the class constructor.
179The configuration values you specify are merged with the current configuration; you don't have to list all options.
180
181.. _zend.console.getopt.configuration.config.example.setoptions:
182
183Using setOptions()
184^^^^^^^^^^^^^^^^^^
185
186.. code-block:: php
187   :linenos:
188
189   $opts = new Zend\Console\Getopt('abp:');
190   $opts->setOptions(
191       array(
192           'ignoreCase' => true,
193           'dashDash'   => false
194       )
195   );
196
197