<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 17172 -->
<sect1 id="zend.filter.inflector">
    <title>Zend_Filter_Inflector</title>

    <para>
        <classname>Zend_Filter_Inflector</classname>
        は、指定したターゲットに対して
        ルールにもとづいた文字列変換を行うための汎用的なツールです。
    </para>

    <para>
        たとえば、MixedCase あるいは camelCase 形式の単語をパス形式に変換したりするような作業を行います。
        読みやすさや OS のポリシーなどの理由で、小文字への変換を行ったりダッシュ
        ('-') で単語を区切ったりといったこともあるでしょう。
        インフレクタは、このような作業を行うことができます。
    </para>

    <para>
        <classname>Zend_Filter_Inflector</classname> は
        <classname>Zend_Filter_Interface</classname> を実装しています。
        インフレクションを実行するには、オブジェクトのインスタンスで
        <methodname>filter()</methodname> をコールします。
    </para>

    <example id="zend.filter.inflector.camel_case_example">
        <title>MixedCase あるいは camelCase のテキストを別形式に変換する</title>

        <programlisting language="php"><![CDATA[
$inflector = new Zend_Filter_Inflector('pages/:page.:suffix');
$inflector->setRules(array(
    ':page'  => array('Word_CamelCaseToDash', 'StringToLower'),
    'suffix' => 'html'
));

$string   = 'camelCasedWords';
$filtered = $inflector->filter(array('page' => $string));
// pages/camel-cased-words.html

$string   = 'this_is_not_camel_cased';
$filtered = $inflector->filter(array('page' => $string));
// pages/this_is_not_camel_cased.html
]]></programlisting>
    </example>

    <sect2 id="zend.filter.inflector.operation">
        <title>操作</title>

        <para>
            インフレクタには、ひとつの <emphasis>ターゲット</emphasis>
            とひとつあるいは複数の <emphasis>ルール</emphasis> が必要です。
            ターゲットは基本的に文字列であり、置き換えを行うプレースホルダを定義します。
            プレースホルダは、先頭に ':' をつけて <code>:script</code>
            のように定義します。
        </para>

        <para>
            <methodname>filter()</methodname> をコールするときに、
            ターゲット内の変数に対応する キー/値
            のペアを配列で渡します。
        </para>

        <para>
            ターゲット内の個々の変数に対して、ゼロ個以上のルールを関連づけることができます。
            ルールとして指定できるのは、<emphasis>静的な</emphasis> ルールか
            <classname>Zend_Filter</classname> クラスです。静的なルールは、
            指定されたテキストで置き換えを行います。
            それ以外の場合は、ルールで指定されたクラスを使用してテキストを変換します。
            クラスを指定する際には、共通のプレフィックスを除いた短いクラス名を使用します。
        </para>

        <para>
            たとえば <classname>Zend_Filter</classname> の具象実装クラスなら何でも使用可能です。
            しかし、これを使用する際には 'Zend_Filter_Alpha' あるいは 'Zend_Filter_StringToLower'
            とするのではなく単に 'Alpha' あるいは 'StringToLower'
            だけで指定するということです。
        </para>
    </sect2>

     <sect2 id="zend.filter.inflector.paths">
        <title>その他のフィルタ向けのパスの設定</title>

        <para>
            <classname>Zend_Filter_Inflector</classname> は、
            <classname>Zend_Loader_PluginLoader</classname>
            を使用してインフレクションに使用するフィルタの読み込みを行います。
            デフォルトでは、
            <classname>Zend_Filter</classname> で始まる任意のフィルタを使用できます。
            このプレフィックスで始まるけれどももっと深い階層にあるフィルタ、たとえば
            Word 系のフィルタなどを使用したい場合は、プレフィックス <classname>Zend_Filter</classname>
            を除いた名前を指定します。
        </para>

        <programlisting language="php"><![CDATA[
// ルールとして Zend_Filter_Word_CamelCaseToDash を使用します
$inflector->addRules(array('script' => 'Word_CamelCaseToDash'));
]]></programlisting>

        <para>
            別のパスを使用するには、プラグインローダへのプロキシとして
            <classname>Zend_Filter_Inflector</classname> のユーティリティメソッド
            <methodname>addFilterPrefixPath()</methodname> を使用します。
        </para>

        <programlisting language="php"><![CDATA[
$inflector->addFilterPrefixPath('My_Filter', 'My/Filter/');
]]></programlisting>

        <para>
            あるいは、プラグインローダをインフレクタから取得して、
            それを直接操作することもできます。
        </para>

        <programlisting language="php"><![CDATA[
$loader = $inflector->getPluginLoader();
$loader->addPrefixPath('My_Filter', 'My/Filter/');
]]></programlisting>

        <para>
            フィルタのパスを変更するための詳細なオプションは、<link
                linkend="zend.loader.pluginloader">PluginLoader
                のドキュメント</link> を参照ください。
        </para>
    </sect2>

    <sect2 id="zend.filter.inflector.targets">
        <title>インフレクタのターゲットの設定</title>

        <para>
            インフレクタのターゲットは、変数用のプレースホルダを含む文字列となります。
            プレースホルダは、先頭に識別子をつけて表します。
            デフォルトの識別子はコロン (':') です。
            そしてその後に変数名を続け、たとえば ':script' や ':path'
            のようになります。
            <methodname>filter()</methodname> メソッドは、識別子の後に続く変数を探して置換します。
        </para>

        <para>
            識別子を変更するには
            <methodname>setTargetReplacementIdentifier()</methodname> メソッドを使用するか、
            コンストラクタの 3 番目の引数で指定します。
        </para>

        <programlisting language="php"><![CDATA[
// コンストラクタ経由
$inflector = new Zend_Filter_Inflector('#foo/#bar.#sfx', null, '#');

// アクセサ経由
$inflector->setTargetReplacementIdentifier('#');
]]></programlisting>

        <para>
            普通はコンストラクタでターゲットを指定することになるでしょう。
            しかし、あとでターゲットを設定しなおしたくなることもあるかもしれません
            (たとえば、
            <code>ViewRenderer</code> や <classname>Zend_Layout</classname>
            といったコアコンポーネントのデフォルトのインフレクタを変更したい場合など)。
            この際に使用できるのが <methodname>setTarget()</methodname> です。
        </para>

        <programlisting language="php"><![CDATA[
$inflector = $layout->getInflector();
$inflector->setTarget('layouts/:script.phtml');
]]></programlisting>

        <para>
            さらに、クラスのメンバーを用意して
            インフレクタのターゲットを変更できるようにしたくなるかもしれません。
            毎回直接ターゲットを変更する必要がなくなる
            (メソッドコールを少なくできる) からです。
            そのためには <methodname>setTargetReference()</methodname> を使用します。
        </para>

        <programlisting language="php"><![CDATA[
class Foo
{
    /**
     * @var string インフレクタのターゲット
     */
    protected $_target = 'foo/:bar/:baz.:suffix';

    /**
     * コンストラクタ
     * @return void
     */
    public function __construct()
    {
        $this->_inflector = new Zend_Filter_Inflector();
        $this->_inflector->setTargetReference($this->_target);
    }

    /**
     * ターゲットを設定してインフレクタのターゲットを更新します
     *
     * @param  string $target
     * @return Foo
     */
    public function setTarget($target)
    {
        $this->_target = $target;
        return $this;
    }
}
]]></programlisting>
    </sect2>

    <sect2 id="zend.filter.inflector.rules">
        <title>インフレクションのルール</title>

        <para>
            先ほど説明したように、静的なルールとフィルタを使用したルールのふたつがあります。
        </para>

        <note>
            <para>
                インフレクタにメソッドを追加するときに
                ひとつずつ追加したとしても一度に追加したとしても、
                その順番が重要となることに注意しましょう。
                より細かい名前、あるいは他のルール名を含む名前などを先に追加するようにしなければなりません。
                たとえば、ふたつのフール 'moduleDir' と 'module'
                があった場合、'moduleDir' のほうが module より前になければなりません。
                というのも 'module' は 'moduleDir' の中に含まれるからです。
                'module' を 'moduleDir' より前に追加すると
                'module' が 'moduleDir' の一部にもマッチしてしまい、
                'Dir' の部分はインフレクションの対象から外れてしまいます。
            </para>
        </note>

        <sect3 id="zend.filter.inflector.rules.static">
            <title>静的なルール</title>

            <para>
                静的なルールは、単なる文字列の置換を行います。
                これは、ターゲットの中の、
                ほぼ固定であるが開発者が変更できるようにさせたい部分などに使用します。
                <methodname>setStaticRule()</methodname> メソッドを使用して、ルールの設定や変更を行います。
            </para>

            <programlisting language="php"><![CDATA[
$inflector = new Zend_Filter_Inflector(':script.:suffix');
$inflector->setStaticRule('suffix', 'phtml');

// あとで変更します
$inflector->setStaticRule('suffix', 'php');
]]></programlisting>

            <para>
                ターゲットと同様、静的ルールも参照で指定することができます。
                これにより、メソッドコールをせずに変数を更新するだけでルールを変更できるようになります。
                これは、クラスの中で内部的にインフレクタを使用している場合に便利です。
                ユーザにいちいちインフレクタを取得させる必要がなくなります。
                これを実現するために使用するのが
                <methodname>setStaticRuleReference()</methodname> メソッドです。
            </para>

            <programlisting language="php"><![CDATA[
class Foo
{
    /**
     * @var string サフィックス
     */
    protected $_suffix = 'phtml';

    /**
     * コンストラクタ
     * @return void
     */
    public function __construct()
    {
        $this->_inflector = new Zend_Filter_Inflector(':script.:suffix');
        $this->_inflector->setStaticRuleReference('suffix', $this->_suffix);
    }

    /**
     * サフィックスを設定し、インフレクタの静的ルールを更新します
     *
     * @param  string $suffix
     * @return Foo
     */
    public function setSuffix($suffix)
    {
        $this->_suffix = $suffix;
        return $this;
    }
}
]]></programlisting>
        </sect3>

        <sect3 id="zend.filter.inflector.rules.filters">
            <title>Filter Inflector ルール</title>

            <para>
                <classname>Zend_Filter</classname> のフィルタ群も、インフレクタのルールとして使用できます。
                静的なルールと同様、こちらもターゲットの変数にバインドされます。
                静的なルールとは異なり、複数のフィルタによるインフレクションを行うこともあります。
                これらのフィルタは順番に処理されるので、
                最終的にほしいデータを考慮してフィルタの登録順を決めるようにしましょう。
            </para>

            <para>
                ルールを追加するには、<methodname>setFilterRule()</methodname>
                (その変数に対する既存のルールをすべて上書きします) あるいは
                <methodname>addFilterRule()</methodname> (その変数に対する既存のルールを保持し、
                新たなルールを最後に追加します) を使用します。
                フィルタは、以下のいずれかの形式で指定します。
            </para>

            <itemizedlist>
                <listitem><para>
                        <emphasis>文字列</emphasis>。
                        フィルタのクラス名、あるいはクラス名からプレフィックス
                        (インフレクタのプラグインローダーで登録されたもの。
                        デフォルトは 'Zend_Filter')
                        を取り除いた部分となります。
                </para></listitem>

                <listitem><para>
                        <emphasis>Filter オブジェクト</emphasis>。
                        <classname>Zend_Filter_Interface</classname>
                        を実装した任意のオブジェクトのインスタンスをフィルタとして渡せます。
                </para></listitem>

                <listitem><para>
                        <emphasis>配列</emphasis>。
                        上で説明した文字列やフィルタオブジェクトを配列にしたものです。
                </para></listitem>
            </itemizedlist>

            <programlisting language="php"><![CDATA[
$inflector = new Zend_Filter_Inflector(':script.:suffix');

// ルールとして Zend_Filter_Word_CamelCaseToDash フィルタを使用するように設定します
$inflector->setFilterRule('script', 'Word_CamelCaseToDash');

// 文字列を小文字変換するルールを追加します
$inflector->addFilterRule('script', new Zend_Filter_StringToLower());

// 複数のルールを一括して指定します
$inflector->setFilterRule('script', array(
    'Word_CamelCaseToDash',
    new Zend_Filter_StringToLower()
));
]]></programlisting>
        </sect3>

        <sect3 id="zend.filter.inflector.rules.multiple">
            <title>多くのルールを一度に設定する</title>

            <para>
                一般に、各変数に対して個別にインフレクタルールを設定するよりも、
                一括してルールを設定できたほうが楽でしょう。
                <classname>Zend_Filter_Inflector</classname> の <methodname>addRules()</methodname>
                メソッドや <methodname>setRules()</methodname> メソッドを使用すると、
                一括設定することができます。
            </para>

            <para>
                それぞれのメソッドには、変数/ルール のペアの配列を指定します。
                ルールには、(文字列、フィルタオブジェクトあるいはその配列などの)
                いずれの形式でも指定できます。変数名には特別な記法を用い、
                それによって静的ルールとフィルタルールを切り替えます。
                使用する記法は次のとおりです。
            </para>

            <itemizedlist>
                <listitem><para>
                        <emphasis>':' プレフィックス</emphasis>: フィルタルール。
                </para></listitem>

                <listitem><para>
                        <emphasis>プレフィックスなし</emphasis>: 静的ルール。
                </para></listitem>
            </itemizedlist>

            <example id="zend.filter.inflector.rules.multiple.example">
                <title>複数のルールの一括設定</title>

                <programlisting language="php"><![CDATA[
// Could also use setRules() with this notation:
$inflector->addRules(array(
    // フィルタルール
    ':controller' => array('CamelCaseToUnderscore','StringToLower'),
    ':action'     => array('CamelCaseToUnderscore','StringToLower'),

    // 静的なルール
    'suffix'      => 'phtml'
));
]]></programlisting>
            </example>
        </sect3>
    </sect2>

    <sect2 id="zend.filter.inflector.utility">
        <title>ユーティリティメソッド</title>

        <para>
            <classname>Zend_Filter_Inflector</classname> のユーティリティメソッド群には、
            プラグインローダーの取得や設定、
            ルールの操作や取得、
            例外をスローするかどうかやその時期の設定といったことを行えるものがあります。
        </para>

        <itemizedlist>
            <listitem><para>
                    <methodname>setPluginLoader()</methodname> は、
                    独自のプラグインローダーを設定してそれを
                    <classname>Zend_Filter_Inflector</classname> で使いたい場合に使用します。
                    <methodname>getPluginLoader()</methodname> は、
                    現在設定されているプラグインローダーを取得します。
            </para></listitem>

            <listitem><para>
                    <methodname>setThrowTargetExceptionsOn()</methodname> は、
                    指定した置換識別子がターゲットで見つからなかった場合に
                    <methodname>filter()</methodname> が例外をスローするかどうかを設定します。
                    デフォルトでは、例外は一切スローされません。
                    <methodname>isThrowTargetExceptionsOn()</methodname> は、
                    現在の設定状態を返します。
            </para></listitem>

            <listitem><para>
                    <methodname>getRules($spec = null)</methodname> は、
                    すべての変数に登録されているすべてのルールを返します。
                    あるいは、指定した変数について登録されているルールだけを返します。
            </para></listitem>

            <listitem><para>
                    <methodname>getRule($spec, $index)</methodname> は、
                    指定した変数のひとつのルールを取得します。
                    これは、ある変数に対するルールを定義したフィルタチェインから
                    特定のフィルタを取り出したい場合に便利です。
                    <varname>$index</varname> は必須です。
            </para></listitem>

            <listitem><para>
                    <methodname>clearRules()</methodname> は、
                    現在登録されているルールをすべてクリアします。
            </para></listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.filter.inflector.config">
        <title>Zend_Filter_Inflector での Zend_Config の使用法</title>

        <para>
            <classname>Zend_Config</classname> を使用してルールを設定したり、
            フィルタのプレフィックスのパスやその他のインフレクタの状態を設定することができます。
            そのためには、<classname>Zend_Config</classname> オブジェクトをコンストラクタあるいは
            <methodname>setConfig()</methodname> に渡します。
            設定可能な項目は以下のとおりです。
        </para>

        <itemizedlist>
            <listitem><para>
                    <code>target</code> は、インフレクションのターゲットを指定します。
            </para></listitem>

            <listitem><para>
                    <code>filterPrefixPath</code> は、
                    インフレクタが使用するフィルタの プレフィックス/パス
                    のペアを指定します。
            </para></listitem>

            <listitem><para>
                    <code>throwTargetExceptionsOn</code> は、
                    インフレクション処理の後にまだ置換識別子が残っていた場合に
                    例外をスローするかどうかを boolean 値で指定します。
            </para></listitem>

            <listitem><para>
                    <code>targetReplacementIdentifier</code> は、
                    ターゲット文字列内で置換変数を表すために使用する文字を指定します。
            </para></listitem>

            <listitem><para>
                    <code>rules</code> は、インフレクションルールの配列を指定します。
                    値、あるいは値の配列をキーに指定し、
                    <methodname>addRules()</methodname> と同じ形式となります。
            </para></listitem>
        </itemizedlist>

        <example id="zend.filter.inflector.config.example">
            <title>Zend_Filter_Inflector での Zend_Config の使用法</title>

            <programlisting language="php"><![CDATA[
// コンストラクタで
$config    = new Zend_Config($options);
$inflector = new Zend_Filter_Inflector($config);

// あるいは setConfig() で
$inflector = new Zend_Filter_Inflector();
$inflector->setConfig($config);
]]></programlisting>
        </example>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->
