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