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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.console.getopt.configuration">
   4     <title>Configuring Zend_Console_Getopt</title>
   5
   6     <sect2 id="zend.console.getopt.configuration.addrules">
   7         <title>Adding Option Rules</title>
   8
   9         <para>
  10             You can add more option rules in addition to those you specified
  11             in the <classname>Zend_Console_Getopt</classname> constructor, using the
  12             <methodname>addRules()</methodname> method. The argument to
  13             <methodname>addRules()</methodname> is the same as the first argument to the
  14             class constructor. It is either a string in the format of the
  15             short syntax options specification, or else an associative array
  16             in the format of a long syntax options specification.
  17             See <link linkend="zend.console.getopt.rules">Declaring Getopt Rules</link>
  18             for details on the syntax for specifying options.
  19         </para>
  20
  21         <example id="zend.console.getopt.configuration.addrules.example">
  22             <title>Using addRules()</title>
  23
  24             <programlisting language="php"><![CDATA[
  25 $opts = new Zend_Console_Getopt('abp:');
  26 $opts->addRules(
  27   array(
  28     'verbose|v' => 'Print verbose output'
  29   )
  30 );
  31 ]]></programlisting>
  32         </example>
  33
  34         <para>
  35             The example above shows adding the <command>--verbose</command> option
  36             with an alias of <command>-v</command> to a set of options
  37             defined in the call to the constructor. Notice that you can mix
  38             short format options and long format options in the same instance
  39             of <classname>Zend_Console_Getopt</classname>.
  40         </para>
  41     </sect2>
  42
  43     <sect2 id="zend.console.getopt.configuration.addhelp">
  44         <title>Adding Help Messages</title>
  45
  46         <para>
  47             In addition to specifying the help strings when declaring option
  48             rules in the long format, you can associate help strings
  49             with option rules using the <methodname>setHelp()</methodname>
  50             method. The argument to the <methodname>setHelp()</methodname> method is an
  51             associative array, in which the key is a flag, and the value is a
  52             corresponding help string.
  53         </para>
  54
  55         <example id="zend.console.getopt.configuration.addhelp.example">
  56             <title>Using setHelp()</title>
  57
  58             <programlisting language="php"><![CDATA[
  59 $opts = new Zend_Console_Getopt('abp:');
  60 $opts->setHelp(
  61     array(
  62         'a' => 'apple option, with no parameter',
  63         'b' => 'banana option, with required integer parameter',
  64         'p' => 'pear option, with optional string parameter'
  65     )
  66 );
  67 ]]></programlisting>
  68         </example>
  69
  70         <para>
  71             If you declared options with aliases, you can use any of the
  72             aliases as the key of the associative array.
  73         </para>
  74
  75         <para>
  76             The <methodname>setHelp()</methodname> method is the only way to define help
  77             strings if you declared the options using the short syntax.
  78         </para>
  79     </sect2>
  80
  81     <sect2 id="zend.console.getopt.configuration.addaliases">
  82         <title>Adding Option Aliases</title>
  83
  84         <para>
  85             You can declare aliases for options using the <methodname>setAliases()</methodname>
  86             method. The argument is an associative array, whose key is
  87             a flag string declared previously, and whose value is a new
  88             alias for that flag. These aliases are merged with any existing
  89             aliases. In other words, aliases you declared earlier are
  90             still in effect.
  91         </para>
  92
  93         <para>
  94             An alias may be declared only once. If you try to redefine
  95             an alias, a <classname>Zend_Console_Getopt_Exception</classname> is thrown.
  96         </para>
  97
  98         <example id="zend.console.getopt.configuration.addaliases.example">
  99             <title>Using setAliases()</title>
 100
 101             <programlisting language="php"><![CDATA[
 102 $opts = new Zend_Console_Getopt('abp:');
 103 $opts->setAliases(
 104     array(
 105         'a' => 'apple',
 106         'a' => 'apfel',
 107         'p' => 'pear'
 108     )
 109 );
 110 ]]></programlisting>
 111         </example>
 112
 113         <para>
 114             In the example above, after declaring these aliases,
 115             <command>-a</command>, <command>--apple</command> and
 116             <command>--apfel</command> are aliases for each other.
 117             Also <command>-p</command> and <command>--pear</command> are aliases
 118             for each other.
 119         </para>
 120
 121         <para>
 122             The <methodname>setAliases()</methodname> method is the only way to define aliases
 123             if you declared the options using the short syntax.
 124         </para>
 125     </sect2>
 126
 127     <sect2 id="zend.console.getopt.configuration.addargs">
 128         <title>Adding Argument Lists</title>
 129
 130         <para>
 131             By default, <classname>Zend_Console_Getopt</classname> uses
 132             <varname>$_SERVER['argv']</varname> for the array of command-line
 133             arguments to parse. You can alternatively specify the array of
 134             arguments as the second constructor argument. Finally, you
 135             can append more arguments to those already used using the
 136             <methodname>addArguments()</methodname> method, or you can replace the current
 137             array of arguments using the <methodname>setArguments()</methodname> method.
 138             In both cases, the parameter to these methods is a simple array of
 139             strings. The former method appends the array to the current
 140             arguments, and the latter method substitutes the array for the
 141             current arguments.
 142         </para>
 143
 144         <example id="zend.console.getopt.configuration.addargs.example">
 145             <title>Using addArguments() and setArguments()</title>
 146
 147             <programlisting language="php"><![CDATA[
 148 // By default, the constructor uses $_SERVER['argv']
 149 $opts = new Zend_Console_Getopt('abp:');
 150
 151 // Append an array to the existing arguments
 152 $opts->addArguments(array('-a', '-p', 'p_parameter', 'non_option_arg'));
 153
 154 // Substitute a new array for the existing arguments
 155 $opts->setArguments(array('-a', '-p', 'p_parameter', 'non_option_arg'));
 156 ]]></programlisting>
 157         </example>
 158     </sect2>
 159
 160     <sect2 id="zend.console.getopt.configuration.config">
 161         <title>Adding Configuration</title>
 162
 163         <para>
 164             The third parameter to the <classname>Zend_Console_Getopt</classname>
 165             constructor is an array of configuration options that affect
 166             the behavior of the object instance returned. You can also
 167             specify configuration options using the <methodname>setOptions()</methodname>
 168             method, or you can set an individual option using the
 169             <methodname>setOption()</methodname> method.
 170         </para>
 171
 172         <note>
 173             <title>Clarifying the Term "option"</title>
 174
 175             <para>
 176                 The term "option" is used for configuration of the
 177                 <classname>Zend_Console_Getopt</classname> class to match terminology
 178                 used elsewhere in Zend Framework. These are not the same
 179                 things as the command-line options that are parsed by
 180                 the <classname>Zend_Console_Getopt</classname> class.
 181             </para>
 182         </note>
 183
 184         <para>
 185             The currently supported
 186             options have const definitions in the class. The options,
 187             their const identifiers (with literal values in parentheses)
 188             are listed below:
 189         </para>
 190
 191         <itemizedlist>
 192             <listitem>
 193                 <para>
 194                     <constant>Zend_Console_Getopt::CONFIG_DASHDASH</constant> ("dashDash"),
 195                     if <constant>TRUE</constant>, enables the special flag <command>--</command> to
 196                     signify the end of flags. Command-line arguments following
 197                     the double-dash signifier are not interpreted as options,
 198                     even if the arguments start with a dash. This configuration
 199                     option is <constant>TRUE</constant> by default.
 200                 </para>
 201             </listitem>
 202
 203             <listitem>
 204                 <para>
 205                     <constant>Zend_Console_Getopt::CONFIG_IGNORECASE</constant> ("ignoreCase"),
 206                     if <constant>TRUE</constant>, makes flags aliases of each other if they differ
 207                     only in their case. That is, <command>-a</command> and
 208                     <command>-A</command> will be considered to be synonymous flags.
 209                     This configuration option is <constant>FALSE</constant> by default.
 210                 </para>
 211             </listitem>
 212
 213             <listitem>
 214                 <para>
 215                     <constant>Zend_Console_Getopt::CONFIG_RULEMODE</constant>
 216                     ("ruleMode") may have values
 217                     <constant>Zend_Console_Getopt::MODE_ZEND</constant> ("zend") and
 218                     <constant>Zend_Console_Getopt::MODE_GNU</constant> ("gnu"). It should not be
 219                     necessary to use this option unless you extend the class with additional syntax
 220                     forms. The two modes supported in the base
 221                     <classname>Zend_Console_Getopt</classname> class are unambiguous. If the
 222                     specifier is a string, the class assumes <constant>MODE_GNU</constant>,
 223                     otherwise it assumes <constant>MODE_ZEND</constant>. But if you extend the
 224                     class and add more syntax forms, you may need to specify the mode
 225                     using this option.
 226                 </para>
 227             </listitem>
 228         </itemizedlist>
 229
 230         <para>
 231             More configuration options may be added as future enhancements
 232             of this class.
 233         </para>
 234
 235         <para>
 236             The two arguments to the <methodname>setOption()</methodname> method are
 237             a configuration option name and an option value.
 238         </para>
 239
 240         <example id="zend.console.getopt.configuration.config.example.setoption">
 241             <title>Using setOption()</title>
 242
 243             <programlisting language="php"><![CDATA[
 244 $opts = new Zend_Console_Getopt('abp:');
 245 $opts->setOption('ignoreCase', true);
 246 ]]></programlisting>
 247         </example>
 248
 249         <para>
 250             The argument to the <methodname>setOptions()</methodname> method is
 251             an associative array. The keys of this array are the configuration
 252             option names, and the values are configuration values.
 253             This is also the array format used in the class constructor.
 254             The configuration values you specify are merged with the current
 255             configuration; you don't have to list all options.
 256         </para>
 257
 258         <example id="zend.console.getopt.configuration.config.example.setoptions">
 259             <title>Using setOptions()</title>
 260
 261             <programlisting language="php"><![CDATA[
 262 $opts = new Zend_Console_Getopt('abp:');
 263 $opts->setOptions(
 264     array(
 265         'ignoreCase' => true,
 266         'dashDash'   => false
 267     )
 268 );
 269 ]]></programlisting>
 270         </example>
 271     </sect2>
 272 </sect1>