PageRenderTime 15ms CodeModel.GetById 7ms app.highlight 5ms RepoModel.GetById 1ms app.codeStats 0ms

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

https://github.com/gullij/zf2-documentation
ReStructuredText | 88 lines | 58 code | 30 blank | 0 comment | 0 complexity | 946ac2d855cc1a1a941f2951caa9e008 MD5 | raw file
 1.. _zend.console.getopt.rules:
 2
 3Declaring Getopt Rules
 4======================
 5
 6The constructor for the ``Zend\Console\Getopt`` class takes from one to three arguments. The first argument
 7declares which options are supported by your application. This class supports alternative syntax forms for
 8declaring the options. See the sections below for the format and usage of these syntax forms.
 9
10The constructor takes two more arguments, both of which are optional. The second argument may contain the
11command-line arguments. This defaults to ``$_SERVER['argv']``.
12
13The third argument of the constructor may contain an configuration options to customize the behavior of
14``Zend\Console\Getopt``. See :ref:`Adding Configuration <zend.console.getopt.configuration.config>` for reference
15on the options available.
16
17.. _zend.console.getopt.rules.short:
18
19Declaring Options with the Short Syntax
20---------------------------------------
21
22``Zend\Console\Getopt`` supports a compact syntax similar to that used by *GNU* Getopt (see
23`http://www.gnu.org/software/libc/manual/html_node/Getopt.html`_. This syntax supports only single-character flags.
24In a single string, you type each of the letters that correspond to flags supported by your application. A letter
25followed by a colon character (**:**) indicates a flag that requires a parameter.
26
27.. _zend.console.getopt.rules.short.example:
28
29.. rubric:: Using the Short Syntax
30
31.. code-block:: php
32   :linenos:
33
34   $opts = new Zend\Console\Getopt('abp:');
35
36The example above shows using ``Zend\Console\Getopt`` to declare that options may be given as ``-a``, ``-b``, or
37``-p``. The latter flag requires a parameter.
38
39The short syntax is limited to flags of a single character. Aliases, parameter types, and help strings are not
40supported in the short syntax.
41
42.. _zend.console.getopt.rules.long:
43
44Declaring Options with the Long Syntax
45--------------------------------------
46
47A different syntax with more features is also available. This syntax allows you to specify aliases for flags, types
48of option parameters, and also help strings to describe usage to the user. Instead of the single string used in the
49short syntax to declare the options, the long syntax uses an associative array as the first argument to the
50constructor.
51
52The key of each element of the associative array is a string with a format that names the flag, with any aliases,
53separated by the pipe symbol ("**|**"). Following this series of flag aliases, if the option requires a parameter,
54is an equals symbol ("**=**") with a letter that stands for the **type** of the parameter:
55
56- "**=s**" for a string parameter
57
58- "**=w**" for a word parameter (a string containing no whitespace)
59
60- "**=i**" for an integer parameter
61
62If the parameter is optional, use a dash ("**-**") instead of the equals symbol.
63
64The value of each element in the associative array is a help string to describe to a user how to use your program.
65
66.. _zend.console.getopt.rules.long.example:
67
68.. rubric:: Using the Long Syntax
69
70.. code-block:: php
71   :linenos:
72
73   $opts = new Zend\Console\Getopt(
74     array(
75       'apple|a'    => 'apple option, with no parameter',
76       'banana|b=i' => 'banana option, with required integer parameter',
77       'pear|p-s'   => 'pear option, with optional string parameter'
78     )
79   );
80
81In the example declaration above, there are three options. ``--apple`` and ``-a`` are aliases for each other, and
82the option takes no parameter. ``--banana`` and ``-b`` are aliases for each other, and the option takes a mandatory
83integer parameter. Finally, ``--pear`` and ``-p`` are aliases for each other, and the option may take an optional
84string parameter.
85
86
87
88.. _`http://www.gnu.org/software/libc/manual/html_node/Getopt.html`: http://www.gnu.org/software/libc/manual/html_node/Getopt.html