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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.console.getopt.configuration">
    <title>Configuring Zend_Console_Getopt</title>

    <sect2 id="zend.console.getopt.configuration.addrules">
        <title>Adding Option Rules</title>

        <para>
            You can add more option rules in addition to those you specified
            in the <classname>Zend_Console_Getopt</classname> constructor, using the
            <methodname>addRules()</methodname> method. The argument to
            <methodname>addRules()</methodname> is the same as the first argument to the
            class constructor. It is either a string in the format of the
            short syntax options specification, or else an associative array
            in the format of a long syntax options specification.
            See <link linkend="zend.console.getopt.rules">Declaring Getopt Rules</link>
            for details on the syntax for specifying options.
        </para>

        <example id="zend.console.getopt.configuration.addrules.example">
            <title>Using addRules()</title>

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

        <para>
            The example above shows adding the <command>--verbose</command> option
            with an alias of <command>-v</command> to a set of options
            defined in the call to the constructor. Notice that you can mix
            short format options and long format options in the same instance
            of <classname>Zend_Console_Getopt</classname>.
        </para>
    </sect2>

    <sect2 id="zend.console.getopt.configuration.addhelp">
        <title>Adding Help Messages</title>

        <para>
            In addition to specifying the help strings when declaring option
            rules in the long format, you can associate help strings
            with option rules using the <methodname>setHelp()</methodname>
            method. The argument to the <methodname>setHelp()</methodname> method is an
            associative array, in which the key is a flag, and the value is a
            corresponding help string.
        </para>

        <example id="zend.console.getopt.configuration.addhelp.example">
            <title>Using setHelp()</title>

            <programlisting language="php"><![CDATA[
$opts = new Zend_Console_Getopt('abp:');
$opts->setHelp(
    array(
        'a' => 'apple option, with no parameter',
        'b' => 'banana option, with required integer parameter',
        'p' => 'pear option, with optional string parameter'
    )
);
]]></programlisting>
        </example>

        <para>
            If you declared options with aliases, you can use any of the
            aliases as the key of the associative array.
        </para>

        <para>
            The <methodname>setHelp()</methodname> method is the only way to define help
            strings if you declared the options using the short syntax.
        </para>
    </sect2>

    <sect2 id="zend.console.getopt.configuration.addaliases">
        <title>Adding Option Aliases</title>

        <para>
            You can declare aliases for options using the <methodname>setAliases()</methodname>
            method. The argument is an associative array, whose key is
            a flag string declared previously, and whose value is a new
            alias for that flag. These aliases are merged with any existing
            aliases. In other words, aliases you declared earlier are
            still in effect.
        </para>

        <para>
            An alias may be declared only once. If you try to redefine
            an alias, a <classname>Zend_Console_Getopt_Exception</classname> is thrown.
        </para>

        <example id="zend.console.getopt.configuration.addaliases.example">
            <title>Using setAliases()</title>

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

        <para>
            In the example above, after declaring these aliases,
            <command>-a</command>, <command>--apple</command> and
            <command>--apfel</command> are aliases for each other.
            Also <command>-p</command> and <command>--pear</command> are aliases
            for each other.
        </para>

        <para>
            The <methodname>setAliases()</methodname> method is the only way to define aliases
            if you declared the options using the short syntax.
        </para>
    </sect2>

    <sect2 id="zend.console.getopt.configuration.addargs">
        <title>Adding Argument Lists</title>

        <para>
            By default, <classname>Zend_Console_Getopt</classname> uses
            <varname>$_SERVER['argv']</varname> for the array of command-line
            arguments to parse. You can alternatively specify the array of
            arguments as the second constructor argument. Finally, you
            can append more arguments to those already used using the
            <methodname>addArguments()</methodname> method, or you can replace the current
            array of arguments using the <methodname>setArguments()</methodname> method.
            In both cases, the parameter to these methods is a simple array of
            strings. The former method appends the array to the current
            arguments, and the latter method substitutes the array for the
            current arguments.
        </para>

        <example id="zend.console.getopt.configuration.addargs.example">
            <title>Using addArguments() and setArguments()</title>

            <programlisting language="php"><![CDATA[
// By default, the constructor uses $_SERVER['argv']
$opts = new Zend_Console_Getopt('abp:');

// Append an array to the existing arguments
$opts->addArguments(array('-a', '-p', 'p_parameter', 'non_option_arg'));

// Substitute a new array for the existing arguments
$opts->setArguments(array('-a', '-p', 'p_parameter', 'non_option_arg'));
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.console.getopt.configuration.config">
        <title>Adding Configuration</title>

        <para>
            The third parameter to the <classname>Zend_Console_Getopt</classname>
            constructor is an array of configuration options that affect
            the behavior of the object instance returned. You can also
            specify configuration options using the <methodname>setOptions()</methodname>
            method, or you can set an individual option using the
            <methodname>setOption()</methodname> method.
        </para>

        <note>
            <title>Clarifying the Term "option"</title>

            <para>
                The term "option" is used for configuration of the
                <classname>Zend_Console_Getopt</classname> class to match terminology
                used elsewhere in Zend Framework. These are not the same
                things as the command-line options that are parsed by
                the <classname>Zend_Console_Getopt</classname> class.
            </para>
        </note>

        <para>
            The currently supported
            options have const definitions in the class. The options,
            their const identifiers (with literal values in parentheses)
            are listed below:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <constant>Zend_Console_Getopt::CONFIG_DASHDASH</constant> ("dashDash"),
                    if <constant>TRUE</constant>, enables the special flag <command>--</command> to
                    signify the end of flags. Command-line arguments following
                    the double-dash signifier are not interpreted as options,
                    even if the arguments start with a dash. This configuration
                    option is <constant>TRUE</constant> by default.
                </para>
            </listitem>

            <listitem>
                <para>
                    <constant>Zend_Console_Getopt::CONFIG_IGNORECASE</constant> ("ignoreCase"),
                    if <constant>TRUE</constant>, makes flags aliases of each other if they differ
                    only in their case. That is, <command>-a</command> and
                    <command>-A</command> will be considered to be synonymous flags.
                    This configuration option is <constant>FALSE</constant> by default.
                </para>
            </listitem>

            <listitem>
                <para>
                    <constant>Zend_Console_Getopt::CONFIG_RULEMODE</constant>
                    ("ruleMode") may have values
                    <constant>Zend_Console_Getopt::MODE_ZEND</constant> ("zend") and
                    <constant>Zend_Console_Getopt::MODE_GNU</constant> ("gnu"). It should not be
                    necessary to use this option unless you extend the class with additional syntax
                    forms. The two modes supported in the base
                    <classname>Zend_Console_Getopt</classname> class are unambiguous. If the
                    specifier is a string, the class assumes <constant>MODE_GNU</constant>,
                    otherwise it assumes <constant>MODE_ZEND</constant>. But if you extend the
                    class and add more syntax forms, you may need to specify the mode
                    using this option.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            More configuration options may be added as future enhancements
            of this class.
        </para>

        <para>
            The two arguments to the <methodname>setOption()</methodname> method are
            a configuration option name and an option value.
        </para>

        <example id="zend.console.getopt.configuration.config.example.setoption">
            <title>Using setOption()</title>

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

        <para>
            The argument to the <methodname>setOptions()</methodname> method is
            an associative array. The keys of this array are the configuration
            option names, and the values are configuration values.
            This is also the array format used in the class constructor.
            The configuration values you specify are merged with the current
            configuration; you don't have to list all options.
        </para>

        <example id="zend.console.getopt.configuration.config.example.setoptions">
            <title>Using setOptions()</title>

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