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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 20765 -->
   4 <sect1 id="zend.console.getopt.configuration">
   5     <title>Zend_Console_Getopt の設定</title>
   6
   7     <sect2 id="zend.console.getopt.configuration.addrules">
   8         <title>オプションの規則の追加</title>
   9         <para>
  10             <classname>Zend_Console_Getopt</classname> のコンストラクタで指定するもの以外にも、
  11             追加でオプションの規則を指定できます。その際には
  12             <methodname>addRules()</methodname> メソッドを使用します。
  13             <methodname>addRules()</methodname> に渡す引数は、コンストラクタの最初の引数と同じです。
  14             短い形式のオプション指定を表す文字列、
  15             あるいは長い形式のオプション指定を表す連想配列となります。
  16             オプションを指定する構文の詳細は、
  17             <link linkend="zend.console.getopt.rules">Getopt
  18             の規則の宣言</link>を参照ください。
  19         </para>
  20         <example id="zend.console.getopt.configuration.addrules.example">
  21             <title>addRules() の使用法</title>
  22             <programlisting language="php"><![CDATA[
  23 $opts = new Zend_Console_Getopt('abp:');
  24 $opts->addRules(
  25   array(
  26     'verbose|v' => '詳細な出力を表示する'
  27   )
  28 );
  29 ]]></programlisting>
  30         </example>
  31         <para>
  32             上の例は、<command>--verbose</command> というオプションと
  33             そのエイリアス <command>-v</command> を
  34             コンストラクタで定義したオプションに追加しています。
  35             <classname>Zend_Console_Getopt</classname> のインスタンスには、
  36             短い形式のオプションと長い形式のオプションが共存可能であることに注意しましょう。
  37         </para>
  38     </sect2>
  39
  40     <sect2 id="zend.console.getopt.configuration.addhelp">
  41         <title>ヘルプメッセージの追加</title>
  42         <para>
  43             長い形式のオプション規則を宣言する際に指定するヘルプ文字列に加え、
  44             <methodname>setHelp()</methodname> メソッドでもヘルプ文字列を規則と関連付けることができます。
  45             <methodname>setHelp()</methodname> メソッドの引数は連想配列で、
  46             キーがフラグ名、値が対応するヘルプ文字列となります。
  47         </para>
  48         <example id="zend.console.getopt.configuration.addhelp.example">
  49             <title>setHelp() の使用法</title>
  50             <programlisting language="php"><![CDATA[
  51 $opts = new Zend_Console_Getopt('abp:');
  52 $opts->setHelp(
  53     array(
  54         'a' => 'リンゴです。パラメータは不要です。',
  55         'b' => 'バナナです。整数パラメータが必須です。',
  56         'p' => '洋ナシです。オプションで文字列パラメータを指定します。'
  57     )
  58 );
  59 ]]></programlisting>
  60         </example>
  61         <para>
  62             エイリアスつきでオプションを宣言した場合は、
  63             どのエイリアスでも連想配列のキーに使用できます。
  64         </para>
  65         <para>
  66             オプションを短い構文で宣言した場合、ヘルプ文字列を設定するには
  67             <methodname>setHelp()</methodname> メソッドが唯一の手段となります。
  68         </para>
  69     </sect2>
  70
  71     <sect2 id="zend.console.getopt.configuration.addaliases">
  72         <title>オプションのエイリアスの追加</title>
  73         <para>
  74             オプションのエイリアスを宣言するには <methodname>setAliases</methodname>
  75             メソッドを使用します。引数は連想配列で、
  76             先ほど宣言したフラグがキー、そしてそのフラグのエイリアスが値となります。
  77             ここで指定したエイリアスが、既存のエイリアスにマージされます。
  78             言い換えると、もともと定義されていたエイリアスもそのまま有効であるということです。
  79         </para>
  80         <para>
  81             エイリアスは一度しか宣言できません。既存のエイリアスを再定義しようとすると
  82             <classname>Zend_Console_Getopt_Exception</classname> がスローされます。
  83         </para>
  84         <example id="zend.console.getopt.configuration.addaliases.example">
  85             <title>setAliases() の使用法</title>
  86             <programlisting language="php"><![CDATA[
  87 $opts = new Zend_Console_Getopt('abp:');
  88 $opts->setAliases(
  89     array(
  90         'a' => 'apple',
  91         'a' => 'apfel',
  92         'p' => 'pear'
  93     )
  94 );
  95 ]]></programlisting>
  96         </example>
  97         <para>
  98             上の例では
  99             <command>-a</command>、<command>--apple</command> および
 100             <command>--apfel</command> をお互いエイリアス指定した後で、
 101             <command>-p</command> と <command>--pear</command>
 102             もエイリアスとしています。
 103         </para>
 104         <para>
 105             オプションを短い構文で宣言した場合、エイリアスを定義するには
 106             <methodname>setAliases()</methodname> メソッドが唯一の手段となります。
 107         </para>
 108     </sect2>
 109
 110     <sect2 id="zend.console.getopt.configuration.addargs">
 111         <title>引数リストの追加</title>
 112         <para>
 113             デフォルトでは、<classname>Zend_Console_Getopt</classname> は
 114             <varname>$_SERVER['argv']</varname> の配列を使用して
 115             コマンドライン引数をパースします。
 116             コンストラクタの二番目の引数として、引数を含む別の配列を指定することもできます。
 117             さらに、もっと別の引数を追加するには
 118             <methodname>addArguments()</methodname> メソッドを使用し、
 119             既存の引数配列を置き換えるには <methodname>setArguments()</methodname>
 120             メソッドを使用します。どちらの場合についても、
 121             これらのメソッドのパラメータは単純な文字列の配列となります。
 122             <methodname>addArguments()</methodname> は現在の引数にその配列を追加し、
 123             <methodname>setArguments()</methodname> は現在の引数をその配列で置き換えます。
 124         </para>
 125         <example id="zend.console.getopt.configuration.addargs.example">
 126             <title>addArguments() および setArguments() の使用法</title>
 127             <programlisting language="php"><![CDATA[
 128 // デフォルトでは、コンストラクタは $_SERVER['argv'] を使用します
 129 $opts = new Zend_Console_Getopt('abp:');
 130
 131 // 既存の引数に配列を追加します
 132 $opts->addArguments(array('-a', '-p', 'p_parameter', 'non_option_arg'));
 133
 134 // 新しい配列で既存の引数を置き換えます
 135 $opts->setArguments(array('-a', '-p', 'p_parameter', 'non_option_arg'));
 136 ]]></programlisting>
 137         </example>
 138     </sect2>
 139
 140     <sect2 id="zend.console.getopt.configuration.config">
 141         <title>設定の追加</title>
 142         <para>
 143             <classname>Zend_Console_Getopt</classname> コンストラクタの
 144             三番目の引数は、設定オプションの配列です。
 145             これは、返り値となるオブジェクトのインスタンスの挙動を設定するものです。
 146             設定オプションを指定するために <methodname>setOptions()</methodname>
 147             メソッドを指定することもできます。あるいは、
 148             オプションを個別に設定するには
 149             <methodname>setOption()</methodname> メソッドを使用します。
 150         </para>
 151         <note>
 152             <title>"オプション" という用語について</title>
 153             <para>
 154                 ここでいう "オプション" は、
 155                 <classname>Zend_Console_Getopt</classname> クラスの設定に使用するもののことを指しています。
 156                 オプションという言葉の意味自体は、Zend Framework
 157                 のその他の部分で使用している意味と同じです。
 158                 <classname>Zend_Console_Getopt</classname> がパースする
 159                 コマンドラインオプションのことではありません。
 160             </para>
 161         </note>
 162         <para>
 163             現在サポートしているオプションには、
 164             クラス定数が定義されています。
 165             オプションとそれに対応する定数 (およびリテラル値)
 166             の一覧を以下にまとめます。
 167         </para>
 168         <itemizedlist>
 169             <listitem>
 170                 <para>
 171                     <constant>Zend_Console_Getopt::CONFIG_DASHDASH</constant> ("dashDash")
 172                     を <constant>TRUE</constant> にすると、フラグの終了を表す特殊フラグ <command>--</command>
 173                     を有効にします。ダブルダッシュの後に続くコマンドライン引数は、
 174                     たとえダッシュで始まっていてもオプションとはみなされません。
 175                     この設定オプションは、デフォルトで <constant>TRUE</constant> となっています。
 176                 </para>
 177             </listitem>
 178             <listitem>
 179                 <para>
 180                     <constant>Zend_Console_Getopt::CONFIG_IGNORECASE</constant> ("ignoreCase")
 181                     を <constant>TRUE</constant> にすると、
 182                     大文字小文字が違うだけのフラグをお互いエイリアスとして扱います。
 183                     つまり、<command>-a</command> と
 184                     <command>-A</command> は同じフラグとみなされます。
 185                     この設定オプションは、デフォルトでは <constant>FALSE</constant> となっています。
 186                 </para>
 187             </listitem>
 188             <listitem>
 189                 <para>
 190                     <constant>Zend_Console_Getopt::CONFIG_RULEMODE</constant>
 191                     ("ruleMode") には <constant>Zend_Console_Getopt::MODE_ZEND</constant>
 192                     ("zend") あるいは <constant>Zend_Console_Getopt::MODE_GNU</constant>
 193                     ("gnu")  のいずれかを指定します。
 194                     独自の構文を使用するためにクラスを拡張する場合を除き、
 195                     このオプションを使用する必要はありません。
 196                     <classname>Zend_Console_Getopt</classname>
 197                     でサポートされている二つのモードは明確です。
 198                     文字列を指定した場合は <constant>MODE_GNU</constant>、
 199                     それ以外の場合は <constant>MODE_ZEND</constant> とみなします。
 200                     もしクラスを拡張して別の構文形式を追加した場合は、
 201                     そのモードをこのオプションで指定する必要があります。
 202                 </para>
 203             </listitem>
 204         </itemizedlist>
 205         <para>
 206             将来は、さらに多くの設定オプションがこのクラスに追加される予定です。
 207         </para>
 208         <para>
 209             <methodname>setOption()</methodname>
 210             メソッドに渡す引数は、設定オプション名とその値のふたつです。
 211         </para>
 212         <example id="zend.console.getopt.configuration.config.example.setoption">
 213             <title>setOption() の使用法</title>
 214             <programlisting language="php"><![CDATA[
 215 $opts = new Zend_Console_Getopt('abp:');
 216 $opts->setOption('ignoreCase', true);
 217 ]]></programlisting>
 218         </example>
 219         <para>
 220             <methodname>setOptions()</methodname> メソッドに渡す引数は連想配列です。
 221             そのキーが設定オプション名、そして値として設定値を指定します。
 222             これは、クラスのコンストラクタで使用するフォーマットでもあります。
 223             指定した設定項目が既存の設定にマージされるので、
 224             すべてのオプションを指定する必要はありません。
 225         </para>
 226         <example id="zend.console.getopt.configuration.config.example.setoptions">
 227             <title>setOptions() の使用法</title>
 228             <programlisting language="php"><![CDATA[
 229 $opts = new Zend_Console_Getopt('abp:');
 230 $opts->setOptions(
 231     array(
 232         'ignoreCase' => true,
 233         'dashDash'   => false
 234     )
 235 );
 236 ]]></programlisting>
 237         </example>
 238     </sect2>
 239
 240 </sect1>