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

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 15103 -->
<!-- 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 <code>Getopt</code></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
            <code>parse()</code> pour forcer l'objet à analyser les arguments. C'est utile
            parce que vous pouvez invoquer <code>parse()</code> dans un bloc <code>try</code>. 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
            <code>getUsageMessage()</code>, 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 <code>Getopt</code></title>

            <programlisting role="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 <code>getOption()</code> 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 <code>true</code>. Sinon la méthode
            retournerait <code>null</code>.
        </para>

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

            <programlisting role="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
            <code>__get()</code> pour rechercher la valeur d'une option comme si c'était une
            variable de membre de classe. La méthode magique <code>__isset()</code> est également
            implémentée.
        </para>

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

            <programlisting role="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
                    <code>toString()</code>. Les options sont retournées sous la forme d'une chaîne
                    de caractère où les paires "<code>drapeau=valeur</code>" sont séparées par des
                    espaces. La valeur d'une option qui n'a pas de paramètre est la chaîne
                    "<code>true</code>".
                </para>
            </listitem>
            <listitem>
                <para>
                    Comme un tableau&#160;: employez la méthode <code>toArray()</code>. 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 JSON&#160;: employez la méthode
                    <code>toJson()</code>.
                </para>
            </listitem>
            <listitem>
                <para>
                    Comme une chaîne au format XML&#160;: employez la méthode <code>toXml()</code>.
                </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 "<code>verbose|v</code>", alors la première
            chaîne, "<code>verbose</code>", 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
            <code>getRemainingArgs()</code>. 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 <code>getRemainingArgs()</code></title>

            <programlisting role="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 GNU 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>