repo_zf1/documentation/manual/fr/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>Extraire les options et les arguments</title>

    <para>
        Après avoir déclaré les options que l'objet <classname>Zend_Console_Getopt</classname> doit
        identifier, et fourni les arguments de la ligne de commande ou un tableau, vous pouvez
        interroger l'objet pour connaître les options indiquées par un utilisateur lors d'un appel
        à votre programme en ligne de commande. La classe implémente les méthodes magiques ainsi
        vous pouvez interroger directement par les noms d'options.
    </para>

    <para>
        L'analyse des données est reportée jusqu'à ce que vous invoquiez pour la première
        fois l'objet <classname>Zend_Console_Getopt</classname> pour découvrir si une option était
        renseignée, l'objet exécute alors son analyse. Ceci permet plusieurs appels de méthode pour
        configurer les options, arguments, messages d'aide, et les options de configuration, avant
        que l'analyse ne soit lancée.
    </para>

    <sect2 id="zend.console.getopt.fetching.exceptions">
        <title>Manipuler les exceptions Getopt</title>

        <para>
            Si l'utilisateur a donné des options invalides sur la ligne de commande, la
            fonction d'analyse syntaxique lève une
            <classname>Zend_Console_Getopt_Exception</classname>. Vous devrez récupérer cette
            exception dans votre code d'application. Vous pouvez utiliser la méthode
            <methodname>parse()</methodname> pour forcer l'objet à analyser les arguments. C'est
            utile parce que vous pouvez invoquer <methodname>parse()</methodname> dans un bloc
            <emphasis>try</emphasis>. S'il passe, vous pouvez être sûrs que l'analyse syntaxique
            ne lèvera pas d'exception de nouveau. L'exception est lancée via une méthode
            personnalisée <methodname>getUsageMessage()</methodname>, qui retourne comme une
            chaîne de caractère l'ensemble formaté des messages d'utilisation pour toutes les
            options déclarées.
        </para>

        <example id="zend.console.getopt.fetching.exceptions.example">
            <title>Récupérer une exception Getopt</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>Les cas, où l'analyse syntaxique lève une exception, incluent&#160;:</para>

        <itemizedlist>
            <listitem>
                <para>L'option passée n'est pas reconnue.</para>
            </listitem>
            <listitem>
                <para>L'option nécessite un paramètre mais aucun n'est fourni.</para>
            </listitem>
            <listitem>
                <para>
                    Le paramètre d'option n'a pas le bon type. Par exemple, une chaîne de
                    caractères non-numérique quand un nombre entier a été exigé.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.console.getopt.fetching.byname">
        <title>Extraire les options par nom</title>

        <para>
            Vous pouvez employer la méthode <methodname>getOption()</methodname> pour connaître la
            valeur d'une option. Si l'option avait un paramètre, cette méthode retourne la valeur du
            paramètre. Si l'option n'avait aucun paramètre mais que l'utilisateur en indiquait sur
            dans la ligne de commande, la méthode retournerait <constant>TRUE</constant>. Sinon la
            méthode retournerait <constant>NULL</constant>.
        </para>

        <example id="zend.console.getopt.fetching.byname.example.setoption">
            <title>Utiliser getOption()</title>

            <programlisting language="php"><![CDATA[
$opts = new Zend_Console_Getopt('abp:');
$b = $opts->getOption('b');
$p_parameter = $opts->getOption('p');
]]></programlisting>
        </example>

        <para>
            De manière alternative, vous pouvez employer la fonction magique
            <methodname>__get()</methodname> pour rechercher la valeur d'une option comme si
            c'était une variable de membre de classe. La méthode magique
            <methodname>__isset()</methodname> est également implémentée.
        </para>

        <example id="zend.console.getopt.fetching.byname.example.magic">
            <title>Utiliser les méthodes magiques __get() et __isset()</title>

            <programlisting language="php"><![CDATA[
$opts = new Zend_Console_Getopt('abp:');
if (isset($opts->b)) {
    echo "J'ai recu l'option b.\n";
}
$p_parameter = $opts->p; // null si non fourni
]]></programlisting>
        </example>

        <para>
            Si vos options sont déclarées avec des alias, vous pouvez employer n'importe quel
            alias de l'option dans les méthodes ci-dessus.
        </para>
    </sect2>

    <sect2 id="zend.console.getopt.fetching.reporting">
        <title>Extraire les options</title>

        <para>
            Il y a plusieurs méthodes pour extraire l'ensemble complet des options fournies
            par l'utilisateur dans la ligne de commande courante.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Comme pour une chaîne de caractères&#160;: employez la méthode
                    <methodname>toString()</methodname>. Les options sont retournées sous la
                    forme d'une chaîne de caractère où les paires <command>drapeau=valeur</command>
                    sont séparées par des espaces. La valeur d'une option qui n'a pas de paramètre
                    est la chaîne "<constant>TRUE</constant>".
                </para>
            </listitem>
            <listitem>
                <para>
                    Comme un tableau&#160;: employez la méthode <methodname>toArray()</methodname>.
                    Les options sont retournées dans un tableau de chaînes de caractères indexé par
                    des nombres, les chaînes de drapeau sont suivies par les chaînes de paramètres
                    éventuels.
                </para>
            </listitem>
            <listitem>
                <para>
                    Comme une chaîne au format <acronym>JSON</acronym>&#160;: employez la méthode
                    <methodname>toJson()</methodname>.
                </para>
            </listitem>
            <listitem>
                <para>
                    Comme une chaîne au format <acronym>XML</acronym>&#160;: employez la méthode
                    <methodname>toXml()</methodname>.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Dans toutes les méthodes de déchargement ci-dessus, la chaîne du drapeau est la
            première chaîne dans la liste des alias correspondants. Par exemple, si les noms
            d'alias d'option étaient déclarés comme "<command>verbose|v</command>", alors la
            première chaîne, "<command>verbose</command>", est employé comme nom de l'option.
            Le nom du drapeau d'option n'inclut pas le tiret précédent.
        </para>
    </sect2>

    <sect2 id="zend.console.getopt.fetching.remainingargs">
        <title>Extraction des arguments sans option</title>

        <para>
            Après que les arguments d'option et ainsi que les paramètres de la ligne de
            commande ont été analysés, il peut exister des arguments additionnels restants. Vous
            pouvez interroger ces arguments en utilisant la méthode
            <methodname>getRemainingArgs()</methodname>. Cette méthode renvoie un tableau de chaîne
            qui ne fait partie d'aucune option.
        </para>

        <example id="zend.console.getopt.fetching.remainingargs.example">
            <title>Utiliser getRemainingArgs()</title>

            <programlisting language="php"><![CDATA[
$opts = new Zend_Console_Getopt('abp:');
$opts->setArguments(array('-p', 'p_parameter', 'nomdefichier'));
$args = $opts->getRemainingArgs(); // retourne array('nomdefichier')
]]></programlisting>
        </example>

        <para>
            <classname>Zend_Console_Getopt</classname> supporte la convention <acronym>GNU</acronym>
            selon laquelle un argument se composant d'un double-tiret signifie la fin des options.
            Tous les arguments suivant celui-ci doivent être traités en tant qu'arguments sans
            options. C'est utile si vous avez un argument sans options qui commence par
            un tiret. Par exemple : "<command>rm -- -nomdefichier-avec-tiret</command>".
        </para>
    </sect2>
</sect1>