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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.console.getopt.fetching">
   4     <title>Fetching Options and Arguments</title>
   5
   6     <para>
   7         After you have declared the options that the
   8         <classname>Zend_Console_Getopt</classname> object should recognize, and supply
   9         arguments from the command-line or an array, you can
  10         query the object to find out which options were specified by a user in
  11         a given command-line invocation of your program. The class implements
  12         magic methods so you can query for options by name.
  13     </para>
  14
  15     <para>
  16         The parsing of the data is deferred until the first query you make
  17         against the <classname>Zend_Console_Getopt</classname> object to find out if an
  18         option was given, the object performs its parsing. This allows you to
  19         use several method calls to configure the options, arguments, help
  20         strings, and configuration options before parsing takes place.
  21     </para>
  22
  23     <sect2 id="zend.console.getopt.fetching.exceptions">
  24         <title>Handling Getopt Exceptions</title>
  25
  26         <para>
  27             If the user gave any invalid options on the command-line,
  28             the parsing function throws a <classname>Zend_Console_Getopt_Exception</classname>.
  29             You should catch this exception in your application code.
  30             You can use the <methodname>parse()</methodname> method to force the object
  31             to parse the arguments. This is useful because you can invoke
  32             <methodname>parse()</methodname> in a <emphasis>try</emphasis> block. If it passes,
  33             you can be sure that the parsing won't throw an exception again.
  34             The exception thrown has a custom method <methodname>getUsageMessage()</methodname>,
  35             which returns as a string the formatted set of usage messages for
  36             all declared options.
  37         </para>
  38
  39         <example id="zend.console.getopt.fetching.exceptions.example">
  40             <title>Catching Getopt Exceptions</title>
  41
  42             <programlisting language="php"><![CDATA[
  43 try {
  44     $opts = new Zend_Console_Getopt('abp:');
  45     $opts->parse();
  46 } catch (Zend_Console_Getopt_Exception $e) {
  47     echo $e->getUsageMessage();
  48     exit;
  49 }
  50 ]]></programlisting>
  51         </example>
  52
  53         <para>
  54             Cases where parsing throws an exception include:
  55         </para>
  56
  57         <itemizedlist>
  58             <listitem>
  59                 <para>
  60                     Option given is not recognized.
  61                 </para>
  62             </listitem>
  63
  64             <listitem>
  65                 <para>
  66                     Option requires a parameter but none was given.
  67                 </para>
  68             </listitem>
  69
  70             <listitem>
  71                 <para>
  72                     Option parameter is of the wrong type.
  73                     E.g. a non-numeric string when an integer
  74                     was required.
  75                 </para>
  76             </listitem>
  77         </itemizedlist>
  78     </sect2>
  79
  80     <sect2 id="zend.console.getopt.fetching.byname">
  81         <title>Fetching Options by Name</title>
  82
  83         <para>
  84             You can use the <methodname>getOption()</methodname> method to query the value
  85             of an option. If the option had a parameter, this method returns
  86             the value of the parameter. If the option had no parameter but
  87             the user did specify it on the command-line, the method returns
  88             <constant>TRUE</constant>. Otherwise the method returns <constant>NULL</constant>.
  89         </para>
  90
  91         <example id="zend.console.getopt.fetching.byname.example.setoption">
  92             <title>Using getOption()</title>
  93
  94             <programlisting language="php"><![CDATA[
  95 $opts = new Zend_Console_Getopt('abp:');
  96 $b = $opts->getOption('b');
  97 $p_parameter = $opts->getOption('p');
  98 ]]></programlisting>
  99         </example>
 100
 101         <para>
 102             Alternatively, you can use the magic <methodname>__get()</methodname> function
 103             to retrieve the value of an option as if it were a class member
 104             variable. The <methodname>__isset()</methodname> magic method is also
 105             implemented.
 106         </para>
 107
 108         <example id="zend.console.getopt.fetching.byname.example.magic">
 109             <title>Using __get() and __isset() Magic Methods</title>
 110
 111             <programlisting language="php"><![CDATA[
 112 $opts = new Zend_Console_Getopt('abp:');
 113 if (isset($opts->b)) {
 114     echo "I got the b option.\n";
 115 }
 116 $p_parameter = $opts->p; // null if not set
 117 ]]></programlisting>
 118         </example>
 119
 120         <para>
 121             If your options are declared with aliases, you may use any of the
 122             aliases for an option in the methods above.
 123         </para>
 124     </sect2>
 125
 126     <sect2 id="zend.console.getopt.fetching.reporting">
 127         <title>Reporting Options</title>
 128
 129         <para>
 130             There are several methods to report the full set of
 131             options given by the user on the current command-line.
 132         </para>
 133
 134         <itemizedlist>
 135             <listitem>
 136                 <para>
 137                     As a string: use the <methodname>toString()</methodname> method. The options
 138                     are returned as a space-separated string of <command>flag=value</command>
 139                     pairs. The value of an option that does not have a parameter
 140                     is the literal string "<constant>TRUE</constant>".
 141                 </para>
 142             </listitem>
 143
 144             <listitem>
 145                 <para>
 146                     As an array: use the <methodname>toArray()</methodname> method. The options
 147                     are returned in a simple integer-indexed array of strings, the flag
 148                     strings followed by parameter strings, if any.
 149                 </para>
 150             </listitem>
 151
 152             <listitem>
 153                 <para>
 154                     As a string containing <acronym>JSON</acronym> data: use the
 155                     <methodname>toJson()</methodname> method.
 156                 </para>
 157             </listitem>
 158
 159             <listitem>
 160                 <para>
 161                     As a string containing <acronym>XML</acronym> data: use the
 162                     <methodname>toXml()</methodname> method.
 163                 </para>
 164             </listitem>
 165         </itemizedlist>
 166
 167         <para>
 168             In all of the above dumping methods, the flag string is the
 169             first string in the corresponding list of aliases. For example,
 170             if the option aliases were declared like <command>verbose|v</command>,
 171             then the first string, <command>verbose</command>, is used as the
 172             canonical name of the option. The name of the option flag does not
 173             include any preceding dashes.
 174         </para>
 175     </sect2>
 176
 177     <sect2 id="zend.console.getopt.fetching.remainingargs">
 178         <title>Fetching Non-option Arguments</title>
 179
 180         <para>
 181             After option arguments and their parameters have been
 182             parsed from the command-line, there may be additional arguments
 183             remaining. You can query these arguments using the
 184             <methodname>getRemainingArgs()</methodname> method. This method returns
 185             an array of the strings that were not part of any options.
 186         </para>
 187
 188         <example id="zend.console.getopt.fetching.remainingargs.example">
 189             <title>Using getRemainingArgs()</title>
 190
 191             <programlisting language="php"><![CDATA[
 192 $opts = new Zend_Console_Getopt('abp:');
 193 $opts->setArguments(array('-p', 'p_parameter', 'filename'));
 194 $args = $opts->getRemainingArgs(); // returns array('filename')
 195 ]]></programlisting>
 196         </example>
 197
 198         <para>
 199             <classname>Zend_Console_Getopt</classname> supports the <acronym>GNU</acronym>
 200             convention that an argument consisting of a double-dash signifies the end of
 201             options. Any arguments following this signifier must be treated as
 202             non-option arguments. This is useful if you might have a non-option
 203             argument that begins with a dash.
 204             For example: "<command>rm -- -filename-with-dash</command>".
 205         </para>
 206     </sect2>
 207 </sect1>