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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24249 -->
<sect1 id="zend.console.getopt.fetching">
    <title>オプションおよび引数の取得</title>
    <para>
        <classname>Zend_Console_Getopt</classname> オブジェクトでオプションを宣言し、
        コマンドラインあるいは配列から引数を受け取ったら、
        このオブジェクトを使用して、ユーザがプログラムを起動した際に
        指定したオプションを取得できます。
        このクラスはマジックメソッドを実装しているので、
        オプションの名前を指定して問い合わせることができます。
    </para>
    <para>
        実際にデータをパースするのは、<classname>Zend_Console_Getopt</classname>
        に対する最初の問い合わせを行ったときです。
        つまり、パースを行う前にいくつかのメソッドで
        オプションや引数、ヘルプ文字列や設定項目を変更することができるということです。
    </para>

    <sect2 id="zend.console.getopt.fetching.exceptions">
        <title>Getopt の例外処理</title>
        <para>
            ユーザがコマンドラインで無効な引数を指定すると、
            パース関数は <classname>Zend_Console_Getopt_Exception</classname>
            をスローします。この例外を、アプリケーションのコードで処理する必要があります。
            <methodname>parse()</methodname> メソッドを使用して、オブジェクトに引数をパースさせます。
            <emphasis>try</emphasis> ブロック内で <methodname>parse()</methodname>
            を実行できるので、便利です。
            パースに成功すると、それ以降で再度例外がスローされることはありません。
            スローされた例外オブジェクトで、独自のメソッド <methodname>getUsageMessage()</methodname>
            が使用できます。これは、宣言されているすべてのオプションについての
            使用法を説明した文字列を返します。
        </para>
        <example id="zend.console.getopt.fetching.exceptions.example">
            <title>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>
            例外が発生するのは、次のような場合です。
        </para>
        <itemizedlist>
            <listitem>
                <para>
                    指定したオプションが認識できない場合。
                </para>
            </listitem>
            <listitem>
                <para>
                    パラメータが必要なオプションで、パラメータが指定されていない場合。
                </para>
            </listitem>
            <listitem>
                <para>
                    オプションのパラメータの型が不正な場合。
                    たとえば整数型を要求するオプションで非数値文字列が渡された場合など。
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.console.getopt.fetching.byname">
        <title>名前によるオプションの取得</title>
        <para>
            <methodname>getOption()</methodname> メソッドを使用すると、
            オプションの値を問い合わせることができます。
            そのオプションがパラメータを持っている場合は、
            このメソッドはパラメータの値を返します。
            パラメータを持っていないオプションでユーザがパラメータを指定した場合は、
            このメソッドは <constant>TRUE</constant> を返します。
            それ以外の場合は、このメソッドは <constant>NULL</constant> を返します。
        </para>
        <example id="zend.console.getopt.fetching.byname.example.setoption">
            <title>getOption() の使用法</title>
            <programlisting language="php"><![CDATA[
$opts = new Zend_Console_Getopt('abp:');
$b = $opts->getOption('b');
$p_parameter = $opts->getOption('p');
]]></programlisting>
        </example>
        <para>
            あるいは、マジックメソッド <methodname>__get()</methodname> を使用して、
            まるでクラスのメンバ変数であるかのようにオプションの値を取得することもできます。
            また、マジックメソッド <methodname>__isset()</methodname> も実装しています。
        </para>
        <example id="zend.console.getopt.fetching.byname.example.magic">
            <title>マジックメソッド __get() および __isset() の使用例</title>
            <programlisting language="php"><![CDATA[
$opts = new Zend_Console_Getopt('abp:');
if (isset($opts->b)) {
    echo "オプション b を取得しました。\n";
}
$p_parameter = $opts->p; // 設定されていない場合は null となります
]]></programlisting>
        </example>
        <para>
            オプションにエイリアスが指定されている場合は、
            上の方法でそのエイリアスを使用することもできます。
        </para>
    </sect2>

    <sect2 id="zend.console.getopt.fetching.reporting">
        <title>オプションの取得</title>
        <para>
            ユーザがコマンドラインで入力したオプションの全一覧を取得するには、
            いくつかの方法があります。
        </para>
        <itemizedlist>
            <listitem>
                <para>
                    文字列で取得: <methodname>toString()</methodname> メソッドを使用します。
                    オプションの内容が、空白で区切られた <command>flag=value</command>
                    形式の文字列で返されます。パラメータを持たないオプションの場合、
                    value の部分はリテラル文字列 "<constant>TRUE</constant>" となります。
                </para>
            </listitem>
            <listitem>
                <para>
                    配列で取得: <methodname>toArray()</methodname> メソッドを使用します。
                    オプションは、数値インデックスの配列で返されます。
                    配列の各要素の値は文字列で、フラグの後に
                    (もしあれば) パラメータが続きます。
                </para>
            </listitem>
            <listitem>
                <para>
                    <acronym>JSON</acronym> データを含む文字列として取得:
                    <methodname>toJson()</methodname> メソッドを使用します。
                </para>
            </listitem>
            <listitem>
                <para>
                    <acronym>XML</acronym> データを含む文字列として取得:
                    <methodname>toXml()</methodname> メソッドを使用します。
                </para>
            </listitem>
        </itemizedlist>
        <para>
            これらのすべての出力メソッドで、フラグ文字列として使用するのは
            エイリアスリストの先頭にあるものです。たとえば
            あるオプションのエイリアスが <command>verbose|v</command>
            のように宣言されていたとすると、最初の文字列である <command>verbose</command>
            をオプション名として使用します。
            オプションフラグ名には、先頭のダッシュは含みません。
        </para>
    </sect2>

    <sect2 id="zend.console.getopt.fetching.remainingargs">
        <title>非オプション引数の取得</title>
        <para>
            オプション引数およびそのパラメータをコマンドラインからパースした後も、
            まだ追加の引数が残っているかも知れません。これらの引数を取得するには
            <methodname>getRemainingArgs()</methodname> メソッドを使用します。このメソッドは、
            どのオプションにも属さない文字列の配列を返します。
        </para>
        <example id="zend.console.getopt.fetching.remainingargs.example">
            <title>getRemainingArgs() の使用法</title>
            <programlisting language="php"><![CDATA[
$opts = new Zend_Console_Getopt('abp:');
$opts->setArguments(array('-p', 'p_parameter', 'filename'));
$args = $opts->getRemainingArgs(); // array('filename') を返します
]]></programlisting>
        </example>
        <para>
            <classname>Zend_Console_Getopt</classname> は、<acronym>GNU</acronym>
            の慣習である「ダッシュふたつだけの引数があったら、
            オプションはそこで終わりとみなす」をサポートしています。
            その後に続く引数は、非オプション引数として扱わなければなりません。
            これは、オプションではない引数がダッシュで始まる場合などに有用です。
            たとえば "<command>rm -- -filename-with-dash</command>"
            のような場合です。
        </para>
    </sect2>

</sect1>