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

    <para>
        <classname>Zend_Filter_Inflector</classname> is a general purpose tool for
        rules-based inflection of strings to a given target.
    </para>

    <para>
        As an example, you may find you need to transform MixedCase or camelCasedWords into a
        path; for readability, OS policies, or other reasons, you also need to
        lower case this, and you want to separate the words using a dash ('-').
        An inflector can do this for you.
    </para>

    <para>
        <classname>Zend_Filter_Inflector</classname> implements
        <classname>Zend_Filter_Interface</classname>; you perform inflection by calling
        <code>filter()</code> on the object instance.
    </para>

    <example id="zend.filter.inflector.camel_case_example">
        <title>Transforming MixedCase and camelCaseText to another format</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>Operation</title>

        <para>
            An inflector requires a <emphasis>target</emphasis> and one or more
            <emphasis>rules</emphasis>. A target is basically a string that
            defines placeholders for variables you wish to substitute. These are
            specified by prefixing with a ':': <code>:script</code>.
        </para>

        <para>
            When calling <code>filter()</code>, you then pass in an array of
            key/value pairs corresponding to the variables in the target.
        </para>

        <para>
            Each variable in the target can have zero or more rules associated
            with them. Rules may be either <emphasis>static</emphasis> or refer to a
            <classname>Zend_Filter</classname> class. Static rules will replace with the
            text provided. Otherwise, a class matching the rule provided will be
            used to inflect the text. Classes are typically specified using a
            short name indicating the filter name stripped of any common prefix.
        </para>

        <para>
            As an example, you can use any <classname>Zend_Filter</classname> concrete
            implementations; however, instead of referring to them as
            'Zend_Filter_Alpha' or 'Zend_Filter_StringToLower', you'd specify
            only 'Alpha' or 'StringToLower'.
        </para>
    </sect2>

     <sect2 id="zend.filter.inflector.paths">
        <title>Setting Paths To Alternate Filters</title>

        <para>
            <classname>Zend_Filter_Inflector</classname> uses
            <classname>Zend_Loader_PluginLoader</classname> to manage loading filters to
            use with inflection. By default, any filter prefixed with
            <classname>Zend_Filter</classname> will be available. To access filters with
            that prefix but which occur deeper in the hierarchy, such as the
            various Word filters, simply strip off the Zend_Filter prefix:
        </para>

        <programlisting language="php"><![CDATA[
// use Zend_Filter_Word_CamelCaseToDash as a rule
$inflector->addRules(array('script' => 'Word_CamelCaseToDash'));
]]></programlisting>

        <para>
            To set alternate paths, <classname>Zend_Filter_Inflector</classname> has a
            utility method that proxies to the plugin loader,
            <code>addFilterPrefixPath()</code>:
        </para>

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

        <para>
            Alternatively, you can retrieve the plugin loader from the
            inflector, and interact with it directly:
        </para>

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

        <para>
            For more options on modifying the paths to filters, please see <link
                linkend="zend.loader.pluginloader">the PluginLoader
                documentation</link>.
        </para>
    </sect2>

    <sect2 id="zend.filter.inflector.targets">
        <title>Setting the Inflector Target</title>

        <para>
            The inflector target is a string with some placeholders for
            variables. Placeholders take the form of an identifier, a colon
            (':') by default, followed by a variable name: ':script', ':path',
            etc. The <code>filter()</code> method looks for the identifier
            followed by the variable name being replaced.
        </para>

        <para>
            You can change the identifier using the
            <code>setTargetReplacementIdentifier()</code> method, or passing it
            as the third argument to the constructor:
        </para>

        <programlisting language="php"><![CDATA[
// Via constructor:
$inflector = new Zend_Filter_Inflector('#foo/#bar.#sfx', null, '#');

// Via accessor:
$inflector->setTargetReplacementIdentifier('#');
]]></programlisting>

        <para>
            Typically, you will set the target via the constructor. However, you
            may want to re-set the target later (for instance, to modify the
            default inflector in core components, such as the
            <code>ViewRenderer</code> or <classname>Zend_Layout</classname>).
            <code>setTarget()</code> can be used for this purpose:
        </para>

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

        <para>
            Additionally, you may wish to have a class member for your class
            that you can use to keep the inflector target updated -- without
            needing to directly update the target each time (thus saving on
            method calls). <code>setTargetReference()</code> allows you to do
            this:
        </para>

        <programlisting language="php"><![CDATA[
class Foo
{
    /**
     * @var string Inflector target
     */
    protected $_target = 'foo/:bar/:baz.:suffix';

    /**
     * Constructor
     * @return void
     */
    public function __construct()
    {
        $this->_inflector = new Zend_Filter_Inflector();
        $this->_inflector->setTargetReference($this->_target);
    }

    /**
     * Set target; updates target in inflector
     *
     * @param  string $target
     * @return Foo
     */
    public function setTarget($target)
    {
        $this->_target = $target;
        return $this;
    }
}
]]></programlisting>
    </sect2>

    <sect2 id="zend.filter.inflector.rules">
        <title>Inflection Rules</title>

        <para>
            As mentioned in the introduction, there are two types of rules:
            static and filter-based.
        </para>

        <note>
            <para>
                It is important to note that regardless of the method in which you add
                rules to the inflector, either one-by-one, or all-at-once; the order is very
                important. More specific names, or names that might contain other rule names,
                must be added before least specific names. For example, assuming the two rule
                names 'moduleDir' and 'module', the 'moduleDir' rule should appear before module
                since 'module' is contained within 'moduleDir'. If 'module' were added before
                'moduleDir', 'module' will match part of 'moduleDir' and process it leaving 'Dir'
                inside of the target uninflected.
            </para>
        </note>

        <sect3 id="zend.filter.inflector.rules.static">
            <title>Static Rules</title>

            <para>
                Static rules do simple string substitution; use them when you
                have a segment in the target that will typically be static, but
                which you want to allow the developer to modify. Use the
                <code>setStaticRule()</code> method to set or modify the rule:
            </para>

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

// change it later:
$inflector->setStaticRule('suffix', 'php');
]]></programlisting>

            <para>
                Much like the target itself, you can also bind a static rule to
                a reference, allowing you to update a single variable instead of
                require a method call; this is often useful when your class uses
                an inflector internally, and you don't want your users to need
                to fetch the inflector in order to update it. The
                <code>setStaticRuleReference()</code> method is used to
                accomplish this:
            </para>

            <programlisting language="php"><![CDATA[
class Foo
{
    /**
     * @var string Suffix
     */
    protected $_suffix = 'phtml';

    /**
     * Constructor
     * @return void
     */
    public function __construct()
    {
        $this->_inflector = new Zend_Filter_Inflector(':script.:suffix');
        $this->_inflector->setStaticRuleReference('suffix', $this->_suffix);
    }

    /**
     * Set suffix; updates suffix static rule in inflector
     *
     * @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 Rules</title>

            <para>
                <classname>Zend_Filter</classname> filters may be used as inflector rules
                as well. Just like static rules, these are bound to a target
                variable; unlike static rules, you may define multiple filters
                to use when inflecting. These filters are processed in order, so
                be careful to register them in an order that makes sense for the
                data you receive.
            </para>

            <para>
                Rules may be added using <code>setFilterRule()</code> (which
                overwrites any previous rules for that variable) or
                <code>addFilterRule()</code> (which appends the new rule to any
                existing rule for that variable). Filters are specified in one
                of the following ways:
            </para>

            <itemizedlist>
                <listitem><para>
                        <emphasis>String</emphasis>. The string may be a filter
                        class name, or a class name segment minus any prefix set
                        in the inflector's plugin loader (by default, minus the
                        'Zend_Filter' prefix).
                </para></listitem>

                <listitem><para>
                        <emphasis>Filter object</emphasis>. Any object instance
                        implementing <classname>Zend_Filter_Interface</classname> may be
                        passed as a filter.
                </para></listitem>

                <listitem><para>
                        <emphasis>Array</emphasis>. An array of one or more
                        strings or filter objects as defined above.
                </para></listitem>
            </itemizedlist>

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

// Set rule to use Zend_Filter_Word_CamelCaseToDash filter
$inflector->setFilterRule('script', 'Word_CamelCaseToDash');

// Add rule to lowercase string
$inflector->addFilterRule('script', new Zend_Filter_StringToLower());

// Set rules en-masse
$inflector->setFilterRule('script', array(
    'Word_CamelCaseToDash',
    new Zend_Filter_StringToLower()
));
]]></programlisting>
        </sect3>

        <sect3 id="zend.filter.inflector.rules.multiple">
            <title>Setting Many Rules At Once</title>

            <para>
                Typically, it's easier to set many rules at once than to
                configure a single variable and its inflection rules at a time.
                <classname>Zend_Filter_Inflector</classname>'s <code>addRules()</code> and
                <code>setRules()</code> method allow this.
            </para>

            <para>
                Each method takes an array of variable/rule pairs, where the
                rule may be whatever the type of rule accepts (string, filter
                object, or array). Variable names accept a special notation to
                allow setting static rules and filter rules, according to the
                following notation:
            </para>

            <itemizedlist>
                <listitem><para>
                        <emphasis>':' prefix</emphasis>: filter rules.
                </para></listitem>

                <listitem><para>
                        <emphasis>No prefix</emphasis>: static rule.
                </para></listitem>
            </itemizedlist>

            <example id="zend.filter.inflector.rules.multiple.example">
                <title>Setting Multiple Rules at Once</title>

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

    // Static rule:
    'suffix'      => 'phtml'
));
]]></programlisting>
            </example>
        </sect3>
    </sect2>

    <sect2 id="zend.filter.inflector.utility">
        <title>Utility Methods</title>

        <para>
            <classname>Zend_Filter_Inflector</classname> has a number of utility methods
            for retrieving and setting the plugin loader, manipulating and
            retrieving rules, and controlling if and when exceptions are thrown.
        </para>

        <itemizedlist>
            <listitem><para>
                    <code>setPluginLoader()</code> can be used when you have
                    configured your own plugin loader and wish to use it with
                    <classname>Zend_Filter_Inflector</classname>;
                    <code>getPluginLoader()</code> retrieves the currently set
                    one.
            </para></listitem>

            <listitem><para>
                    <code>setThrowTargetExceptionsOn()</code> can be used to
                    control whether or not <code>filter()</code> throws an
                    exception when a given replacement identifier passed to it
                    is not found in the target. By default, no exceptions are
                    thrown. <code>isThrowTargetExceptionsOn()</code> will tell
                    you what the current value is.
            </para></listitem>

            <listitem><para>
                    <code>getRules($spec = null)</code> can be used to retrieve all
                    registered rules for all variables, or just the rules for a
                    single variable.
            </para></listitem>

            <listitem><para>
                    <code>getRule($spec, $index)</code> fetches a single rule
                    for a given variable; this can be useful for fetching a
                    specific filter rule for a variable that has a filter chain.
                    <code>$index</code> must be passed.
            </para></listitem>

            <listitem><para>
                    <code>clearRules()</code> will clear all currently
                    registered rules.
            </para></listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.filter.inflector.config">
        <title>Using Zend_Config with Zend_Filter_Inflector</title>

        <para>
            You can use <classname>Zend_Config</classname> to set rules, filter prefix
            paths, and other object state in your inflectors, either by passing
            a <classname>Zend_Config</classname> object to the constructor or
            <code>setConfig()</code>. The following settings may be specified:
        </para>

        <itemizedlist>
            <listitem><para>
                    <code>target</code> specifies the inflection target.
            </para></listitem>

            <listitem><para>
                    <code>filterPrefixPath</code> specifies one or more filter
                    prefix/path pairs for use with the inflector.
            </para></listitem>

            <listitem><para>
                    <code>throwTargetExceptionsOn</code> should be a boolean
                    indicating whether or not to throw exceptions when a
                    replacement identifier is still present after inflection.
            </para></listitem>

            <listitem><para>
                    <code>targetReplacementIdentifier</code> specifies the
                    character to use when identifying replacement variables in
                    the target string.
            </para></listitem>

            <listitem><para>
                    <code>rules</code> specifies an array of inflection rules;
                    it should consist of keys that specify either values or
                    arrays of values, consistent with <code>addRules()</code>.
            </para></listitem>
        </itemizedlist>

        <example id="zend.filter.inflector.config.example">
            <title>Using Zend_Config with Zend_Filter_Inflector</title>

            <programlisting language="php"><![CDATA[
// With the constructor:
$config    = new Zend_Config($options);
$inflector = new Zend_Filter_Inflector($config);

// Or with setConfig():
$inflector = new Zend_Filter_Inflector();
$inflector->setConfig($config);
]]></programlisting>
        </example>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->
