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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.console.getopt.introduction">
   4     <title>Introduction</title>
   5
   6     <para>
   7         The <classname>Zend_Console_Getopt</classname> class helps command-line
   8         applications to parse their options and arguments.
   9     </para>
  10
  11     <para>
  12         Users may specify command-line arguments when
  13         they execute your application. These arguments have meaning to the
  14         application, to change the behavior in some way, or choose resources,
  15         or specify parameters. Many options have developed customary meaning,
  16         for example <command>--verbose</command> enables extra output from many
  17         applications. Other options may have a meaning that is different for
  18         each application. For example, <command>-c</command> enables different
  19         features in <command>grep</command>, <command>ls</command>, and
  20         <command>tar</command>.
  21     </para>
  22
  23     <para>
  24         Below are a few definitions of terms. Common usage of the terms
  25         varies, but this documentation will use the definitions below.
  26     </para>
  27
  28     <itemizedlist>
  29         <listitem>
  30             <para>
  31                 "argument": a string that occurs on the command-line
  32                 following the name of the command. Arguments may be
  33                 options or else may appear without an option, to name
  34                 resources on which the command operates.
  35             </para>
  36         </listitem>
  37
  38         <listitem>
  39             <para>
  40                 "option": an argument that signifies that the command
  41                 should change its default behavior in some way.
  42             </para>
  43         </listitem>
  44
  45         <listitem>
  46             <para>
  47                 "flag": the first part of an option, identifies
  48                 the purpose of the option. A flag is preceded
  49                 conventionally by one or two dashes
  50                 (<command>-</command> or <command>--</command>).
  51                 A single dash precedes a single-character flag
  52                 or a cluster of single-character flags.
  53                 A double-dash precedes a multi-character flag.
  54                 Long flags cannot be clustered.
  55             </para>
  56         </listitem>
  57
  58         <listitem>
  59             <para>
  60                 "parameter": the secondary part of an option; a data value
  61                 that may accompany a flag, if it is applicable to the
  62                 given option. For example, many commands accept a
  63                 <command>--verbose</command> option, but typically
  64                 this option has no parameter. However, an option like
  65                 <command>--user</command> almost always requires
  66                 a following parameter.
  67             </para>
  68
  69             <para>
  70                 A parameter may be given as a separate argument following a
  71                 flag argument, or as part of the same argument string,
  72                 separated from the flag by an equals symbol (<command>=</command>).
  73                 The latter form is supported only by long flags.
  74                 For example,
  75                 <command>-u username</command>, <command>--user username</command>,
  76                 and <command>--user=username</command> are forms supported
  77                 by <classname>Zend_Console_Getopt</classname>.
  78             </para>
  79         </listitem>
  80
  81         <listitem>
  82             <para>
  83                 "cluster": multiple single-character flags combined
  84                 in a single string argument and preceded by a single
  85                 dash. For example, "<command>ls -1str</command>"
  86                 uses a cluster of four short flags. This command is
  87                 equivalent to "<command>ls -1 -s -t -r</command>".
  88                 Only single-character flags can be clustered.
  89                 You cannot make a cluster of long flags.
  90             </para>
  91         </listitem>
  92     </itemizedlist>
  93
  94     <para>
  95         For example, in <command>mysql --user=root mydatabase</command>,
  96         <command>mysql</command> is a <emphasis>command</emphasis>,
  97         <command>--user=root</command> is an <emphasis>option</emphasis>,
  98         <command>--user</command> is a <emphasis>flag</emphasis>,
  99         <command>root</command> is a <emphasis>parameter</emphasis> to the option,
 100         and <command>mydatabase</command> is an argument but not an option
 101         by our definition.
 102     </para>
 103
 104     <para>
 105         <classname>Zend_Console_Getopt</classname> provides an interface to declare
 106         which flags are valid for your application, output an error and usage
 107         message if they use an invalid flag, and report to your application
 108         code which flags the user specified.
 109     </para>
 110
 111     <note>
 112         <title>Getopt is not an Application Framework</title>
 113
 114         <para>
 115             <classname>Zend_Console_Getopt</classname> does <emphasis>not</emphasis>
 116             interpret the meaning of flags and parameters, nor does this class
 117             implement application workflow or invoke application code.
 118             You must implement those actions in your own application code.
 119             You can use the <classname>Zend_Console_Getopt</classname> class to parse
 120             the command-line and provide object-oriented methods for querying
 121             which options were given by a user, but code to use this
 122             information to invoke parts of your application should be in
 123             another <acronym>PHP</acronym> class.
 124         </para>
 125     </note>
 126
 127     <para>
 128         The following sections describe usage of <classname>Zend_Console_Getopt</classname>.
 129     </para>
 130 </sect1>