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

<?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>