repo_zf1/documentation/manual/de/module_specs/Zend_Console_Getopt-Fetching.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 20765 -->
<!-- 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>