documentation/manual/en/module_specs/Zend_Console_Getopt-Rules.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.console.getopt.rules">
   4     <title>Declaring Getopt Rules</title>
   5
   6     <para>
   7         The constructor for the <classname>Zend_Console_Getopt</classname> class takes
   8         from one to three arguments. The first argument
   9         declares which options are supported by your application.
  10         This class supports alternative syntax forms for declaring the options.
  11         See the sections below for the format and usage of these syntax forms.
  12     </para>
  13
  14     <para>
  15         The constructor takes two more arguments, both of which are optional.
  16         The second argument may contain the command-line arguments.
  17         This defaults to <varname>$_SERVER['argv']</varname>.
  18     </para>
  19
  20     <para>
  21         The third argument of the constructor may contain an
  22         configuration options to customize the behavior of
  23         <classname>Zend_Console_Getopt</classname>.
  24         See <link linkend="zend.console.getopt.configuration.config">Adding Configuration</link>
  25         for reference on the options available.
  26     </para>
  27
  28     <sect2 id="zend.console.getopt.rules.short">
  29         <title>Declaring Options with the Short Syntax</title>
  30
  31         <para>
  32             <classname>Zend_Console_Getopt</classname> supports a compact syntax similar
  33             to that used by <acronym>GNU</acronym> Getopt (see <ulink
  34                 url="http://www.gnu.org/software/libc/manual/html_node/Getopt.html">http://www.gnu.org/software/libc/manual/html_node/Getopt.html</ulink>.
  35             This syntax supports only single-character flags. In a single
  36             string, you type each of the letters that correspond to flags
  37             supported by your application. A letter followed by a colon
  38             character (<emphasis>:</emphasis>) indicates a flag that requires a
  39             parameter.
  40         </para>
  41
  42         <example id="zend.console.getopt.rules.short.example">
  43             <title>Using the Short Syntax</title>
  44
  45             <programlisting language="php"><![CDATA[
  46 $opts = new Zend_Console_Getopt('abp:');
  47 ]]></programlisting>
  48         </example>
  49
  50         <para>
  51             The example above shows using <classname>Zend_Console_Getopt</classname>
  52             to declare that options may be given as <command>-a</command>,
  53             <command>-b</command>, or <command>-p</command>. The latter flag
  54             requires a parameter.
  55         </para>
  56
  57         <para>
  58             The short syntax is limited to flags of a single character.
  59             Aliases, parameter types, and help strings are not supported
  60             in the short syntax.
  61         </para>
  62     </sect2>
  63
  64     <sect2 id="zend.console.getopt.rules.long">
  65         <title>Declaring Options with the Long Syntax</title>
  66
  67         <para>
  68             A different syntax with more features is also available. This
  69             syntax allows you to specify aliases for flags, types of option
  70             parameters, and also help strings to describe usage to the user.
  71             Instead of the single string used in the short syntax to declare
  72             the options, the long syntax uses an associative array as the
  73             first argument to the constructor.
  74         </para>
  75
  76         <para>
  77             The key of each element of the associative array is a string with
  78             a format that names the flag, with any aliases, separated by the
  79             pipe symbol ("<emphasis>|</emphasis>"). Following this series of flag
  80             aliases, if the option requires a parameter, is an equals symbol
  81             ("<emphasis>=</emphasis>") with a letter that stands for the
  82             <emphasis>type</emphasis> of the parameter:
  83         </para>
  84
  85         <itemizedlist>
  86             <listitem>
  87                 <para>
  88                     "<emphasis>=s</emphasis>" for a string parameter
  89                 </para>
  90             </listitem>
  91
  92             <listitem>
  93                 <para>
  94                     "<emphasis>=w</emphasis>" for a word parameter
  95                     (a string containing no whitespace)
  96                 </para>
  97             </listitem>
  98
  99             <listitem>
 100                 <para>
 101                     "<emphasis>=i</emphasis>" for an integer parameter
 102                 </para>
 103             </listitem>
 104         </itemizedlist>
 105
 106         <para>
 107             If the parameter is optional, use a dash ("<emphasis>-</emphasis>")
 108             instead of the equals symbol.
 109         </para>
 110
 111         <para>
 112             The value of each element in the associative array is a help string
 113             to describe to a user how to use your program.
 114         </para>
 115
 116         <example id="zend.console.getopt.rules.long.example">
 117             <title>Using the Long Syntax</title>
 118
 119             <programlisting language="php"><![CDATA[
 120 $opts = new Zend_Console_Getopt(
 121   array(
 122     'apple|a'    => 'apple option, with no parameter',
 123     'banana|b=i' => 'banana option, with required integer parameter',
 124     'pear|p-s'   => 'pear option, with optional string parameter'
 125   )
 126 );
 127 ]]></programlisting>
 128         </example>
 129
 130         <para>
 131             In the example declaration above, there are three options.
 132             <command>--apple</command> and <command>-a</command> are aliases for each
 133             other, and the option takes no parameter.
 134             <command>--banana</command> and <command>-b</command> are aliases for each
 135             other, and the option takes a mandatory integer parameter.
 136             Finally, <command>--pear</command> and <command>-p</command> are aliases
 137             for each other, and the option may take an optional string parameter.
 138         </para>
 139     </sect2>
 140 </sect1>