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

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 15103 -->
<!-- Reviewed: no -->
<sect1 id="zend.console.getopt.configuration">
    <title>Configurer <classname>Zend_Console_Getopt</classname></title>

    <sect2 id="zend.console.getopt.configuration.addrules">
        <title>Ajouter des règles d'options</title>

        <para>
            Vous pouvez ajouter de nouvelles règles d'option en complément de celles
            indiquées dans le constructeur de <classname>Zend_Console_Getopt</classname>, en
            utilisant la méthode <code>addRules()</code>. L'argument d'<code>addRules()</code> est
            identique au premier argument du constructeur de classe. C'est soit une chaîne dans le
            format d'options de syntaxe courte, soit un tableau associatif dans le format
            d'options de syntaxe longue. Voir
            <link linkend="zend.console.getopt.rules">"Déclarer les règles Getopt"</link> pour les
            détails sur la syntaxe de déclaration des options.
        </para>

        <example>
            <title>Utilisation d'<code>addRules()</code></title>

            <programlisting role="php"><![CDATA[
$opts = new Zend_Console_Getopt('abp:');
$opts->addRules(
  array(
    'verbose|v' => 'Print verbose output'
  )
);
]]></programlisting>
        </example>

        <para>
            L'exemple au-dessus montre comment ajouter l'option "<code>--verbose</code>" avec
            l'alias "<code>-v</code>" à un ensemble d'options définies dans l'appel au
            constructeur. Notez que vous pouvez mélanger des options de syntaxe courte et de
            syntaxe longue dans la même instance de <classname>Zend_Console_Getopt</classname>.
        </para>
    </sect2>

    <sect2 id="zend.console.getopt.configuration.addhelp">
        <title>Ajouter des messages d'aide</title>

        <para>
            En plus d'indiquer les messages d'aide en déclarant les règles d'option dans le
            long format, vous pouvez associer des messages d'aide aux règles d'option en utilisant
            la méthode <code>setHelp()</code>. L'argument de la méthode <code>setHelp()</code> est
            un tableau associatif, dans laquelle la clé est un drapeau, et la valeur est le message
            d'aide correspondant.
        </para>

        <example>
            <title>Utiliser <code>setHelp()</code></title>

            <programlisting role="php"><![CDATA[
$opts = new Zend_Console_Getopt('abp:');
$opts->setHelp(
    array(
        'a' => 'option abricot, sans paramètres',
        'b' => 'option banane, avec un paramètre entier obligatoire',
        'p' => 'option pear, avec un paramètre chaîne de caractères optionel'
    )
);
]]></programlisting>
        </example>

        <para>
            Si vous déclarez des options avec des alias, vous pouvez employer n'importe quel
            alias comme clé du tableau associatif.
        </para>

        <para>
            La méthode <code>setHelp()</code> est la seule manière de définir des messages
            d'aide si vous déclarez les options en utilisant la syntaxe courte.
        </para>
    </sect2>

    <sect2 id="zend.console.getopt.configuration.addaliases">
        <title>Ajouter des alias aux options</title>

        <para>
            Vous pouvez déclarer des alias pour des options en utilisant la méthode
            <code>setAliases()</code>. L'argument est un tableau associatif, dont la clé est une
            chaîne de drapeau déclaré auparavant, et dont la valeur est un nouvel alias pour ce
            drapeau. Ces alias sont fusionnés avec tous les alias existants. En d'autres termes,
            les alias que vous avez déclarés plus tôt sont toujours actifs.
        </para>

        <para>
            Un alias ne peut être déclaré qu'une seule fois. Si vous essayez de redéfinir un
            alias, une <classname>Zend_Console_Getopt_Exception</classname> est levée.
        </para>

        <example>
            <title>Utiliser <code>setAliases()</code></title>

            <programlisting role="php"><![CDATA[
$opts = new Zend_Console_Getopt('abp:');
$opts->setAliases(
    array(
        'a' => 'apple',
        'a' => 'apfel',
        'p' => 'pear'
    )
);
]]></programlisting>
        </example>

        <para>
            Dans l'exemple ci-dessus, après leurs déclarations, "<code>-a</code>",
            "<code>--apple</code>" et "<code>--apfel</code>" sont des alias les un pour les autres.
            En outre "<code>-p</code>" et "<code>--pear</code>" sont des alias l'un pour
            l'autre.
        </para>

        <para>
            La méthode <code>setAliases()</code> est la seule manière de définir des alias si
            vous déclarez les options en utilisant la syntaxe courte.
        </para>
    </sect2>

    <sect2 id="zend.console.getopt.configuration.addargs">
        <title>Ajouter des listes d'arguments</title>

        <para>
            Par défaut, <classname>Zend_Console_Getopt</classname> utilise
            <code>$_SERVER['argv']</code> comme tableau des arguments de ligne de commande à
            analyser. De manière alternative, vous pouvez indiquer le tableau d'arguments comme
            deuxième argument de constructeur. En conclusion, vous pouvez ajouter de nouveaux
            d'arguments à ceux déjà utilisés en utilisant la méthode <code>addArguments()</code>,
            ou vous pouvez remplacer le choix courant d'arguments en utilisant la méthode
            <code>setArguments()</code>. Dans les deux cas, le paramètre de ces méthodes est un
            simple tableau de chaîne. L'ancienne méthode ajoutait le tableau aux arguments
            courants, et la nouvelle méthode substitue le tableau aux arguments courants.
        </para>

        <example>
            <title>
                Utilisation de <code>addArguments()</code> et <code>setArguments()</code>
            </title>

            <programlisting role="php"><![CDATA[
// Par défaut, le constructeur utilise $_SERVER['argv']
$opts = new Zend_Console_Getopt('abp:');

// Ajoute un tableau aux arguments existants
$opts->addArguments(array('-a', '-p', 'p_parameter', 'non_option_arg'));

// Remplace les arguments existants par un nouveau tableau
$opts->setArguments(array('-a', '-p', 'p_parameter', 'non_option_arg'));
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.console.getopt.configuration.config">
        <title>Ajouter une configuration</title>

        <para>
            Le troisième paramètre du constructeur de <classname>Zend_Console_Getopt</classname>
            est un tableau d'options de configuration qui affectent le comportement de l'instance
            d'objet retournée. Vous pouvez également indiquer des options de configuration en
            utilisant la méthode <code>setOptions()</code>, ou vous pouvez placer une option
            individuelle en utilisant la méthode <code>setOption()</code>.
        </para>

        <note>
            <title>Clarifier le terme "option"</title>
            <para>
                Le terme "option" est employé pour la configuration de la classe
                <classname>Zend_Console_Getopt</classname> afin de correspondre à la terminologie
                utilisée dans le reste de Zend Framework. Ce n'est pas la même chose que les
                options de la ligne de commande qui sont analysées par la classe
                <classname>Zend_Console_Getopt</classname>.
            </para>
        </note>

        <para>
            Les options actuellement supportées ont des définitions de constantes dans la
            classe. Les options, leurs constantes (avec des valeurs littérales entre parenthèses)
            sont énumérées ci-dessous&#160;:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <classname>Zend_Console_Getopt::CONFIG_DASHDASH</classname>
                    ("<code>dashDash</code>"), si "<code>true</code>", utilise le drapeau spécial
                    "<code>--</code>" pour signifier la fin des drapeaux. Les arguments de la ligne
                    de commande suivant le double-tiret ne sont pas interprétées comme options,
                    même si les arguments commencent par un tiret. Cette option de configuration
                    vaut "<code>true</code>" par défaut.
                </para>
            </listitem>
            <listitem>
                <para>
                    <classname>Zend_Console_Getopt::CONFIG_IGNORECASE</classname>
                    ("<code>ignoreCase</code>"), si "<code>true</code>", fait correspondre des
                    alias même s'ils différent en terme de casse. C'est-à-dire,"<code>-a</code>" et
                    "<code>-A</code>" seront considérés commes des synonymes. Cette option de
                    configuration vaut "<code>false</code>" par défaut.
                </para>
            </listitem>
            <listitem>
                <para>
                    <classname>Zend_Console_Getopt::CONFIG_RULEMODE</classname>
                    ("<code>ruleMode</code>") peut avoir les valeurs
                    <classname>Zend_Console_Getopt::MODE_ZEND</classname> ("zend") ou
                    <classname>Zend_Console_Getopt::MODE_GNU</classname> ("<code>gnu</code>"). Il
                    ne devrait pas être nécessaire d'employer cette option à moins que vous
                    n'étendiez la classe avec les formes additionnelles de syntaxe. Les deux modes
                    supportés dans la classe <classname>Zend_Console_Getopt</classname> de base
                    sont sans équivoque. Si le spécificateur est une chaîne de caractère, la classe
                    passe en <code>MODE_GNU</code>, autrement elle est en <code>MODE_ZEND</code>.
                    Mais si vous étendez la classe et ajoutez de nouvelles formes de syntaxe, vous
                    pouvez avoir à indiquer le mode en utilisant cette option.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Plus d'options de configuration pourront être ajoutées en tant que futurs
            perfectionnements de cette classe.
        </para>

        <para>
            Les deux arguments de la méthode <code>setOption()</code> sont un nom d'option de
            configuration et une valeur d'option.
        </para>

        <example>
            <title>Utilisation de <code>setOption()</code></title>

            <programlisting role="php"><![CDATA[
$opts = new Zend_Console_Getopt('abp:');
$opts->setOption('ignoreCase', true);
]]></programlisting>
        </example>

        <para>
            L'argument de la méthode <code>setOptions()</code> est un tableau associatif. Les
            clés de ce tableau sont les noms d'option de configuration, et les valeurs sont des
            valeurs de configuration. C'est également le format de tableau utilisé par le
            constructeur de classe. Les valeurs de configuration que vous indiquez sont fusionnées
            avec la configuration courante ; vous n'avez pas à énumérer toutes les options.
        </para>

        <example>
            <title>Utilisation de <code>setOptions()</code></title>

            <programlisting role="php"><![CDATA[
$opts = new Zend_Console_Getopt('abp:');
$opts->setOptions(
    array(
        'ignoreCase' => true,
        'dashDash'   => false
    )
);
]]></programlisting>
        </example>
    </sect2>
</sect1>