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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24249 -->
<sect1 id="zend.console.getopt.configuration">
    <title>Zend_Console_Getopt の設定</title>

    <sect2 id="zend.console.getopt.configuration.addrules">
        <title>オプションの規則の追加</title>
        <para>
            <classname>Zend_Console_Getopt</classname> のコンストラクタで指定するもの以外にも、
            追加でオプションの規則を指定できます。その際には
            <methodname>addRules()</methodname> メソッドを使用します。
            <methodname>addRules()</methodname> に渡す引数は、コンストラクタの最初の引数と同じです。
            短い形式のオプション指定を表す文字列、
            あるいは長い形式のオプション指定を表す連想配列となります。
            オプションを指定する構文の詳細は、
            <link linkend="zend.console.getopt.rules">Getopt
            の規則の宣言</link>を参照ください。
        </para>
        <example id="zend.console.getopt.configuration.addrules.example">
            <title>addRules() の使用法</title>
            <programlisting language="php"><![CDATA[
$opts = new Zend_Console_Getopt('abp:');
$opts->addRules(
  array(
    'verbose|v' => '詳細な出力を表示する'
  )
);
]]></programlisting>
        </example>
        <para>
            上の例は、<command>--verbose</command> というオプションと
            そのエイリアス <command>-v</command> を
            コンストラクタで定義したオプションに追加しています。
            <classname>Zend_Console_Getopt</classname> のインスタンスには、
            短い形式のオプションと長い形式のオプションが共存可能であることに注意しましょう。
        </para>
    </sect2>

    <sect2 id="zend.console.getopt.configuration.addhelp">
        <title>ヘルプメッセージの追加</title>
        <para>
            長い形式のオプション規則を宣言する際に指定するヘルプ文字列に加え、
            <methodname>setHelp()</methodname> メソッドでもヘルプ文字列を規則と関連付けることができます。
            <methodname>setHelp()</methodname> メソッドの引数は連想配列で、
            キーがフラグ名、値が対応するヘルプ文字列となります。
        </para>
        <example id="zend.console.getopt.configuration.addhelp.example">
            <title>setHelp() の使用法</title>
            <programlisting language="php"><![CDATA[
$opts = new Zend_Console_Getopt('abp:');
$opts->setHelp(
    array(
        'a' => 'リンゴです。パラメータは不要です。',
        'b' => 'バナナです。整数パラメータが必須です。',
        'p' => '洋ナシです。オプションで文字列パラメータを指定します。'
    )
);
]]></programlisting>
        </example>
        <para>
            エイリアスつきでオプションを宣言した場合は、
            どのエイリアスでも連想配列のキーに使用できます。
        </para>
        <para>
            オプションを短い構文で宣言した場合、ヘルプ文字列を設定するには
            <methodname>setHelp()</methodname> メソッドが唯一の手段となります。
        </para>
    </sect2>

    <sect2 id="zend.console.getopt.configuration.addaliases">
        <title>オプションのエイリアスの追加</title>
        <para>
            オプションのエイリアスを宣言するには <methodname>setAliases</methodname>
            メソッドを使用します。引数は連想配列で、
            先ほど宣言したフラグがキー、そしてそのフラグのエイリアスが値となります。
            ここで指定したエイリアスが、既存のエイリアスにマージされます。
            言い換えると、もともと定義されていたエイリアスもそのまま有効であるということです。
        </para>
        <para>
            エイリアスは一度しか宣言できません。既存のエイリアスを再定義しようとすると
            <classname>Zend_Console_Getopt_Exception</classname> がスローされます。
        </para>
        <example id="zend.console.getopt.configuration.addaliases.example">
            <title>setAliases() の使用法</title>
            <programlisting language="php"><![CDATA[
$opts = new Zend_Console_Getopt('abp:');
$opts->setAliases(
    array(
        'a' => 'apple',
        'a' => 'apfel',
        'p' => 'pear'
    )
);
]]></programlisting>
        </example>
        <para>
            上の例では
            <command>-a</command>、<command>--apple</command> および
            <command>--apfel</command> をお互いエイリアス指定した後で、
            <command>-p</command> と <command>--pear</command>
            もエイリアスとしています。
        </para>
        <para>
            オプションを短い構文で宣言した場合、エイリアスを定義するには
            <methodname>setAliases()</methodname> メソッドが唯一の手段となります。
        </para>
    </sect2>

    <sect2 id="zend.console.getopt.configuration.addargs">
        <title>引数リストの追加</title>
        <para>
            デフォルトでは、<classname>Zend_Console_Getopt</classname> は
            <varname>$_SERVER['argv']</varname> の配列を使用して
            コマンドライン引数をパースします。
            コンストラクタの二番目の引数として、引数を含む別の配列を指定することもできます。
            さらに、もっと別の引数を追加するには
            <methodname>addArguments()</methodname> メソッドを使用し、
            既存の引数配列を置き換えるには <methodname>setArguments()</methodname>
            メソッドを使用します。どちらの場合についても、
            これらのメソッドのパラメータは単純な文字列の配列となります。
            <methodname>addArguments()</methodname> は現在の引数にその配列を追加し、
            <methodname>setArguments()</methodname> は現在の引数をその配列で置き換えます。
        </para>
        <example id="zend.console.getopt.configuration.addargs.example">
            <title>addArguments() および setArguments() の使用法</title>
            <programlisting language="php"><![CDATA[
// デフォルトでは、コンストラクタは $_SERVER['argv'] を使用します
$opts = new Zend_Console_Getopt('abp:');

// 既存の引数に配列を追加します
$opts->addArguments(array('-a', '-p', 'p_parameter', 'non_option_arg'));

// 新しい配列で既存の引数を置き換えます
$opts->setArguments(array('-a', '-p', 'p_parameter', 'non_option_arg'));
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.console.getopt.configuration.config">
        <title>設定の追加</title>
        <para>
            <classname>Zend_Console_Getopt</classname> コンストラクタの
            三番目の引数は、設定オプションの配列です。
            これは、返り値となるオブジェクトのインスタンスの挙動を設定するものです。
            設定オプションを指定するために <methodname>setOptions()</methodname>
            メソッドを指定することもできます。あるいは、
            オプションを個別に設定するには
            <methodname>setOption()</methodname> メソッドを使用します。
        </para>
        <note>
            <title>"オプション" という用語について</title>
            <para>
                ここでいう "オプション" は、
                <classname>Zend_Console_Getopt</classname> クラスの設定に使用するもののことを指しています。
                オプションという言葉の意味自体は、Zend Framework
                のその他の部分で使用している意味と同じです。
                <classname>Zend_Console_Getopt</classname> がパースする
                コマンドラインオプションのことではありません。
            </para>
        </note>
        <para>
            現在サポートしているオプションには、
            クラス定数が定義されています。
            オプションとそれに対応する定数 (およびリテラル値)
            の一覧を以下にまとめます。
        </para>
        <itemizedlist>
            <listitem>
                <para>
                    <constant>Zend_Console_Getopt::CONFIG_DASHDASH</constant> ("dashDash")
                    を <constant>TRUE</constant> にすると、フラグの終了を表す特殊フラグ <command>--</command>
                    を有効にします。ダブルダッシュの後に続くコマンドライン引数は、
                    たとえダッシュで始まっていてもオプションとはみなされません。
                    この設定オプションは、デフォルトで <constant>TRUE</constant> となっています。
                </para>
            </listitem>
            <listitem>
                <para>
                    <constant>Zend_Console_Getopt::CONFIG_IGNORECASE</constant> ("ignoreCase")
                    を <constant>TRUE</constant> にすると、
                    大文字小文字が違うだけのフラグをお互いエイリアスとして扱います。
                    つまり、<command>-a</command> と
                    <command>-A</command> は同じフラグとみなされます。
                    この設定オプションは、デフォルトでは <constant>FALSE</constant> となっています。
                </para>
            </listitem>
            <listitem>
                <para>
                    <constant>Zend_Console_Getopt::CONFIG_RULEMODE</constant>
                    ("ruleMode") には <constant>Zend_Console_Getopt::MODE_ZEND</constant>
                    ("zend") あるいは <constant>Zend_Console_Getopt::MODE_GNU</constant>
                    ("gnu")  のいずれかを指定します。
                    独自の構文を使用するためにクラスを拡張する場合を除き、
                    このオプションを使用する必要はありません。
                    <classname>Zend_Console_Getopt</classname>
                    でサポートされている二つのモードは明確です。
                    文字列を指定した場合は <constant>MODE_GNU</constant>、
                    それ以外の場合は <constant>MODE_ZEND</constant> とみなします。
                    もしクラスを拡張して別の構文形式を追加した場合は、
                    そのモードをこのオプションで指定する必要があります。
                </para>
            </listitem>
        </itemizedlist>
        <para>
            将来は、さらに多くの設定オプションがこのクラスに追加される予定です。
        </para>
        <para>
            <methodname>setOption()</methodname>
            メソッドに渡す引数は、設定オプション名とその値のふたつです。
        </para>
        <example id="zend.console.getopt.configuration.config.example.setoption">
            <title>setOption() の使用法</title>
            <programlisting language="php"><![CDATA[
$opts = new Zend_Console_Getopt('abp:');
$opts->setOption('ignoreCase', true);
]]></programlisting>
        </example>
        <para>
            <methodname>setOptions()</methodname> メソッドに渡す引数は連想配列です。
            そのキーが設定オプション名、そして値として設定値を指定します。
            これは、クラスのコンストラクタで使用するフォーマットでもあります。
            指定した設定項目が既存の設定にマージされるので、
            すべてのオプションを指定する必要はありません。
        </para>
        <example id="zend.console.getopt.configuration.config.example.setoptions">
            <title>setOptions() の使用法</title>
            <programlisting language="php"><![CDATA[
$opts = new Zend_Console_Getopt('abp:');
$opts->setOptions(
    array(
        'ignoreCase' => true,
        'dashDash'   => false
    )
);
]]></programlisting>
        </example>
    </sect2>

</sect1>