PageRenderTime 63ms CodeModel.GetById 35ms app.highlight 6ms RepoModel.GetById 19ms app.codeStats 0ms

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

https://github.com/gullij/zf2-documentation
ReStructuredText | 133 lines | 88 code | 45 blank | 0 comment | 0 complexity | 8eb2b8f43b7df36f8e8761ab844152dc MD5 | raw file
  1.. _zend.console.getopt.fetching:
  2
  3Fetching Options and Arguments
  4==============================
  5
  6After you have declared the options that the ``Zend\Console\Getopt`` object should recognize, and supply arguments
  7from the command-line or an array, you can query the object to find out which options were specified by a user in a
  8given command-line invocation of your program. The class implements magic methods so you can query for options by
  9name.
 10
 11The parsing of the data is deferred until the first query you make against the ``Zend\Console\Getopt`` object to
 12find out if an option was given, the object performs its parsing. This allows you to use several method calls to
 13configure the options, arguments, help strings, and configuration options before parsing takes place.
 14
 15.. _zend.console.getopt.fetching.exceptions:
 16
 17Handling Getopt Exceptions
 18--------------------------
 19
 20If the user gave any invalid options on the command-line, the parsing function throws a
 21``Zend\Console\Getopt\Exception``. You should catch this exception in your application code. You can use the
 22``parse()`` method to force the object to parse the arguments. This is useful because you can invoke ``parse()`` in
 23a **try** block. If it passes, you can be sure that the parsing won't throw an exception again. The exception
 24thrown has a custom method ``getUsageMessage()``, which returns as a string the formatted set of usage messages for
 25all declared options.
 26
 27.. _zend.console.getopt.fetching.exceptions.example:
 28
 29.. rubric:: Catching Getopt Exceptions
 30
 31.. code-block:: php
 32   :linenos:
 33
 34   try {
 35       $opts = new Zend\Console\Getopt('abp:');
 36       $opts->parse();
 37   } catch (Zend\Console\Getopt\Exception $e) {
 38       echo $e->getUsageMessage();
 39       exit;
 40   }
 41
 42Cases where parsing throws an exception include:
 43
 44- Option given is not recognized.
 45
 46- Option requires a parameter but none was given.
 47
 48- Option parameter is of the wrong type. E.g. a non-numeric string when an integer was required.
 49
 50.. _zend.console.getopt.fetching.byname:
 51
 52Fetching Options by Name
 53------------------------
 54
 55You can use the ``getOption()`` method to query the value of an option. If the option had a parameter, this method
 56returns the value of the parameter. If the option had no parameter but the user did specify it on the command-line,
 57the method returns ``TRUE``. Otherwise the method returns ``NULL``.
 58
 59.. _zend.console.getopt.fetching.byname.example.setoption:
 60
 61.. rubric:: Using getOption()
 62
 63.. code-block:: php
 64   :linenos:
 65
 66   $opts = new Zend\Console\Getopt('abp:');
 67   $b = $opts->getOption('b');
 68   $p_parameter = $opts->getOption('p');
 69
 70Alternatively, you can use the magic ``__get()`` function to retrieve the value of an option as if it were a class
 71member variable. The ``__isset()`` magic method is also implemented.
 72
 73.. _zend.console.getopt.fetching.byname.example.magic:
 74
 75.. rubric:: Using \__get() and \__isset() Magic Methods
 76
 77.. code-block:: php
 78   :linenos:
 79
 80   $opts = new Zend\Console\Getopt('abp:');
 81   if (isset($opts->b)) {
 82       echo "I got the b option.\n";
 83   }
 84   $p_parameter = $opts->p; // null if not set
 85
 86If your options are declared with aliases, you may use any of the aliases for an option in the methods above.
 87
 88.. _zend.console.getopt.fetching.reporting:
 89
 90Reporting Options
 91-----------------
 92
 93There are several methods to report the full set of options given by the user on the current command-line.
 94
 95- As a string: use the ``toString()`` method. The options are returned as a space-separated string of
 96  ``flag=value`` pairs. The value of an option that does not have a parameter is the literal string "``TRUE``".
 97
 98- As an array: use the ``toArray()`` method. The options are returned in a simple integer-indexed array of strings,
 99  the flag strings followed by parameter strings, if any.
100
101- As a string containing *JSON* data: use the ``toJson()`` method.
102
103- As a string containing *XML* data: use the ``toXml()`` method.
104
105In all of the above dumping methods, the flag string is the first string in the corresponding list of aliases. For
106example, if the option aliases were declared like ``verbose|v``, then the first string, ``verbose``, is used as the
107canonical name of the option. The name of the option flag does not include any preceding dashes.
108
109.. _zend.console.getopt.fetching.remainingargs:
110
111Fetching Non-option Arguments
112-----------------------------
113
114After option arguments and their parameters have been parsed from the command-line, there may be additional
115arguments remaining. You can query these arguments using the ``getRemainingArgs()`` method. This method returns an
116array of the strings that were not part of any options.
117
118.. _zend.console.getopt.fetching.remainingargs.example:
119
120.. rubric:: Using getRemainingArgs()
121
122.. code-block:: php
123   :linenos:
124
125   $opts = new Zend\Console\Getopt('abp:');
126   $opts->setArguments(array('-p', 'p_parameter', 'filename'));
127   $args = $opts->getRemainingArgs(); // returns array('filename')
128
129``Zend\Console\Getopt`` supports the *GNU* convention that an argument consisting of a double-dash signifies the
130end of options. Any arguments following this signifier must be treated as non-option arguments. This is useful if
131you might have a non-option argument that begins with a dash. For example: "``rm -- -filename-with-dash``".
132
133