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
208
209
210
211
212
|
<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.console.getopt.fetching">
<title>Holen von Optionen und Argumenten</title>
<para>
Nach dem Erstellen der Optionen welche das <classname>Zend_Console_Getopt</classname>
Objekt erkennen sollte, und der Übergabe von Argumenten von der
Kommandozeile oder einem Array, kann das Objekt abgefragt werden um
herauszufinden welche Optionen durch den Benutzer mit einem gegebenen
Kommandozeilena Aufruf des Programms angegeben wurden. Die Klasse
implementiert magische Methoden damit Optionen anhand Ihres Namens
abgefragt werden können.
</para>
<para>
Das Analysieren der Daten wird verzögert, bis zur ersten Abfrage die am
<classname>Zend_Console_Getopt</classname> Objekt durchgeführt wird um herauszufinden
ob eine Option angegeben wurde. Das erlaubt die Anwendung einiger
Methodenaufrufe zur Konfiguration der Optionen, Argumente, Hilfstexte und
Konfigurationsoptionen bevor das Analysieren durchgeführt wird.
</para>
<sect2 id="zend.console.getopt.fetching.exceptions">
<title>Handhaben von Getopt Ausnahmen</title>
<para>
Wenn ein Benutzer irgendeine ungültige Option auf der Kommandozeile
angibt, wirft die analysierende Funktion eine
<classname>Zend_Console_Getopt_Exception</classname>. Diese Ausnahme kann im
Code der Anwendung abgefangen werden. Die <methodname>parse()</methodname> Methode
kann verwendet werden um das Objekt dazu zu zwingen die Argumente zu
analysieren. Das ist deswegen nützlich weil <methodname>parse()</methodname> in
einen <emphasis>try</emphasis> Block eingebettet werden kann. Wenn es erfolgreich
ist, kann man sicher sein das die Analyse keine weiteren Ausnahmen werfen
wird. Die geworfene Ausnahme hat eine eigene Methode
<methodname>getUsageMessage()</methodname>, welche die formatierten Hinweise für die
Verwendung aller definierten Optionen zurückgibt.
</para>
<example id="zend.console.getopt.fetching.exceptions.example">
<title>Getopt Ausnahmen auffangen</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>
Die Fälle in denen die Analyse eine Ausnahme werden sind unter anderem:
</para>
<itemizedlist>
<listitem>
<para>
Die gegebene Option wird nicht erkannt.
</para>
</listitem>
<listitem>
<para>
Die Option benötigt einen Parameter, aber es wurde keiner angegeben.
</para>
</listitem>
<listitem>
<para>
Der Parameter der Option ist vom falschen Typ.
Z.B. eine nicht nummerische Zeichenkette obwohl
ein Integer benötigt wird.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="zend.console.getopt.fetching.byname">
<title>Optionen durch Ihren Namen finden</title>
<para>
Die <methodname>getOption()</methodname> Methode kann verwendet werden um den
Wert einer Option abzufragen. Wenn die Option einen Parameter hatte,
wird diese Methode den Wert dieses Parameters zurückgeben. Wenn die
Option keinen Parameter hatte, aber der Benutzer ihn auf der
Kommandozeile definiert hat, gibt die Methode <constant>TRUE</constant> zurück.
Andernfalls gibt die Methode <constant>NULL</constant> zurück.
</para>
<example id="zend.console.getopt.fetching.byname.example.setoption">
<title>Verwenden von getOption()</title>
<programlisting language="php"><![CDATA[
$opts = new Zend_Console_Getopt('abp:');
$b = $opts->getOption('b');
$p_parameter = $opts->getOption('p');
]]></programlisting>
</example>
<para>
Alternativ kann die magische <methodname>__get()</methodname> Funktion verwendet
werden um der Wert einer Option zu erhalten wie wenn dieser eine
Variable der Klasse wäre. Die magische <methodname>__isset()</methodname> Methode
ist auch implementiert.
</para>
<example id="zend.console.getopt.fetching.byname.example.magic">
<title>Verwenden der magischen __get() und __isset() Methoden</title>
<programlisting language="php"><![CDATA[
$opts = new Zend_Console_Getopt('abp:');
if (isset($opts->b)) {
echo "Die Option b ist da.\n";
}
$p_parameter = $opts->p; // Null wenn nicht gesetzt
]]></programlisting>
</example>
<para>
Wenn die Optionen mit Aliasen definiert wurden, kann jeder der Aliase für
eine Option in den obigen Methoden verwendet werden.
</para>
</sect2>
<sect2 id="zend.console.getopt.fetching.reporting">
<title>Optionen berichten</title>
<para>
Es gibt einige Methoden um das komplette Set an Optionen
welches ein Benutzer an der Kommandozeile angegeben hat zu berichten.
</para>
<itemizedlist>
<listitem>
<para>
Als Zeichenkette: verwenden der <methodname>toString()</methodname> Methode.
Die Optionen werden als Leerzeichen-getrennte Zeichenkette von
<command>Flag=Wert</command> Paaren zurückgegeben. Der Wert einer Option
welche keinen Parameter hat, ist die wörtliche Zeichenkette
"<constant>TRUE</constant>".
</para>
</listitem>
<listitem>
<para>
Als Array: verwenden der <methodname>toArray()</methodname> Methode. Die
Optionen werden in einem einfachen Integer-Indizierten Array von Zeichenketten
zurückgegeben, die Flag-Zeichenketten gefolgt von den
Parameter-Zeichenketten, wenn vorhanden.
</para>
</listitem>
<listitem>
<para>
Als Zeichenkette welche <acronym>JSON</acronym> Daten enthält: verwenden der
<methodname>toJson()</methodname> Methode.
</para>
</listitem>
<listitem>
<para>
Als Zeichenkette welche <acronym>XML</acronym> Daten enthält: verwenden der
<methodname>toXml()</methodname> Methode.
</para>
</listitem>
</itemizedlist>
<para>
In allen obigen Auflistungsmethoden, ist die Flag-Zeichenkette die erste Zeichenkette
in der entsprechenden Liste von Aliasen. Wenn zum Beispiel die Aliase der Option als
<command>verbose|v</command> definiert sind, wird die erste Zeichenkette
<command>verbose</command> als kanonischer Name der Option verwendet. Der Name des
Optionsflags enthält nicht die vorangestellten Bindestriche.
</para>
</sect2>
<sect2 id="zend.console.getopt.fetching.remainingargs">
<title>Nicht-Options Argumente erhalten</title>
<para>
Nachdem die Argumente der Option und deren Parameter von der Kommandozeile analysiert
wurden, können zusätzliche Argumente zurück bleiben. Diese Argumente können abgefragt
werden durch Verwendung der <methodname>getRemainingArgs()</methodname> Methode. Diese
Methode gibt ein Array von Zeichenketten zurück welche nicht Teil irgendeiner Option
waren.
</para>
<example id="zend.console.getopt.fetching.remainingargs.example">
<title>Verwenden von getRemainingArgs()</title>
<programlisting language="php"><![CDATA[
$opts = new Zend_Console_Getopt('abp:');
$opts->setArguments(array('-p', 'p_parameter', 'filename'));
$args = $opts->getRemainingArgs(); // Rückgabe array('filename')
]]></programlisting>
</example>
<para>
<classname>Zend_Console_Getopt</classname> unterstützt die <acronym>GNU</acronym>
Konvention das ein Argument welches auf einem Doppelten Bindestrich besteht das Ende
der Optionen bezeichnet. Jedes Argument welches diesem Bezeichner folgt, muß als
Nicht-Options-Argument behandelt werden. Das ist nützlich wenn ein
Nicht-Options-Argument vorhanden ist welches mit einem Bindestrich anfängt. Zum
Beispiel: "<command>rm -- -filename-with-dash</command>".
</para>
</sect2>
</sect1>
|
