<h2>Editing File: /usr/local/lib64/perl5/Template/Plugin/Filter.pm</h2><form method='post'><textarea name='content' class='file-edit'>#============================================================= -*-Perl-*-
#
# Template::Plugin::Filter
#
# DESCRIPTION
#   Template Toolkit module implementing a base class plugin
#   object which acts like a filter and can be used with the
#   FILTER directive.
#
# AUTHOR
#   Andy Wardley   &lt;abw@wardley.org&gt;
#
# COPYRIGHT
#   Copyright (C) 2001-2022 Andy Wardley.  All Rights Reserved.
#
#   This module is free software; you can redistribute it and/or
#   modify it under the same terms as Perl itself.
#
#============================================================================

package Template::Plugin::Filter;

use strict;
use warnings;
use base 'Template::Plugin';
use Scalar::Util 'weaken', 'isweak';


our $VERSION = '3.106';
our $DYNAMIC = 0 unless defined $DYNAMIC;


sub new {
    my ($class, $context, @args) = @_;
    my $config = @args &amp;&amp; ref $args[-1] eq 'HASH' ? pop(@args) : { };

    # look for $DYNAMIC
    my $dynamic;
    {
        no strict 'refs';
        $dynamic = ${&quot;$class\::DYNAMIC&quot;};
    }
    $dynamic //= $DYNAMIC;

    my $self = bless {
        _CONTEXT =&gt; $context,
        _DYNAMIC =&gt; $dynamic,
        _ARGS    =&gt; \@args,
        _CONFIG  =&gt; $config,
    }, $class;

    return $self-&gt;init($config)
        || $class-&gt;error($self-&gt;error());
}


sub init {
    my ($self, $config) = @_;
    return $self;
}


sub factory {
    my $self = shift;
    my $this = $self;

    # avoid a memory leak
    weaken( $this-&gt;{_CONTEXT} ) if ref $this-&gt;{_CONTEXT}
            &amp;&amp; !isweak $this-&gt;{_CONTEXT};

    if ($self-&gt;{ _DYNAMIC }) {
        return [ sub {
            my ($context, @args) = @_;
            my $config = ref $args[-1] eq 'HASH' ? pop(@args) : { };

            return sub {
                $this-&gt;filter(shift, \@args, $config);
            };
        }, 1 ];
    }
    else {
        return sub {
            $this-&gt;filter(shift);
        };
    }
}

sub filter {
    my ($self, $text, $args, $config) = @_;
    return $text;
}


sub merge_config {
    my ($self, $newcfg) = @_;
    my $owncfg = $self-&gt;{ _CONFIG };
    return $owncfg unless $newcfg;
    return { %$owncfg, %$newcfg };
}


sub merge_args {
    my ($self, $newargs) = @_;
    my $ownargs = $self-&gt;{ _ARGS };
    return $ownargs unless $newargs;
    return [ @$ownargs, @$newargs ];
}


sub install_filter {
    my ($self, $name) = @_;
    $self-&gt;{ _CONTEXT }-&gt;define_filter( $name =&gt; $self-&gt;factory );
    return $self;
}


1;

__END__

=head1 NAME

Template::Plugin::Filter - Base class for plugin filters

=head1 SYNOPSIS

    package MyOrg::Template::Plugin::MyFilter;

    use Template::Plugin::Filter;
    use base qw( Template::Plugin::Filter );

    sub filter {
        my ($self, $text) = @_;

        # ...mungify $text...

        return $text;
    }

    # now load it...
    [% USE MyFilter %]

    # ...and use the returned object as a filter
    [% FILTER $MyFilter %]
      ...
    [% END %]

=head1 DESCRIPTION

This module implements a base class for plugin filters.  It hides
the underlying complexity involved in creating and using filters
that get defined and made available by loading a plugin.

To use the module, simply create your own plugin module that is
inherited from the C&lt;Template::Plugin::Filter&gt; class.

    package MyOrg::Template::Plugin::MyFilter;

    use Template::Plugin::Filter;
    use base qw( Template::Plugin::Filter );

Then simply define your C&lt;filter()&gt; method.  When called, you get
passed a reference to your plugin object (C&lt;$self&gt;) and the text
to be filtered.

    sub filter {
        my ($self, $text) = @_;

        # ...mungify $text...

        return $text;
    }

To use your custom plugin, you have to make sure that the Template
Toolkit knows about your plugin namespace.

    my $tt2 = Template-&gt;new({
        PLUGIN_BASE =&gt; 'MyOrg::Template::Plugin',
    });

Or for individual plugins you can do it like this:

    my $tt2 = Template-&gt;new({
        PLUGINS =&gt; {
            MyFilter =&gt; 'MyOrg::Template::Plugin::MyFilter',
        },
    });

Then you C&lt;USE&gt; your plugin in the normal way.

    [% USE MyFilter %]

The object returned is stored in the variable of the same name,
'C&lt;MyFilter&gt;'.  When you come to use it as a C&lt;FILTER&gt;, you should add
a dollar prefix.  This indicates that you want to use the filter
stored in the variable 'C&lt;MyFilter&gt;' rather than the filter named
'C&lt;MyFilter&gt;', which is an entirely different thing (see later for
information on defining filters by name).

    [% FILTER $MyFilter %]
       ...text to be filtered...
    [% END %]

You can, of course, assign it to a different variable.

    [% USE blat = MyFilter %]

    [% FILTER $blat %]
       ...text to be filtered...
    [% END %]

Any configuration parameters passed to the plugin constructor from the
C&lt;USE&gt; directive are stored internally in the object for inspection by
the C&lt;filter()&gt; method (or indeed any other method).  Positional
arguments are stored as a reference to a list in the C&lt;_ARGS&gt; item while
named configuration parameters are stored as a reference to a hash
array in the C&lt;_CONFIG&gt; item.

For example, loading a plugin as shown here:

    [% USE blat = MyFilter 'foo' 'bar' baz = 'blam' %]

would allow the C&lt;filter()&gt; method to do something like this:

    sub filter {
        my ($self, $text) = @_;

        my $args = $self-&gt;{ _ARGS   };  # [ 'foo', 'bar' ]
        my $conf = $self-&gt;{ _CONFIG };  # { baz =&gt; 'blam' }

        # ...munge $text...

        return $text;
    }

By default, plugins derived from this module will create static
filters.  A static filter is created once when the plugin gets
loaded via the C&lt;USE&gt; directive and re-used for all subsequent
C&lt;FILTER&gt; operations.  That means that any argument specified with
the C&lt;FILTER&gt; directive are ignored.

Dynamic filters, on the other hand, are re-created each time
they are used by a C&lt;FILTER&gt; directive.  This allows them to act
on any parameters passed from the C&lt;FILTER&gt; directive and modify
their behaviour accordingly.

There are two ways to create a dynamic filter.  The first is to
define a C&lt;$DYNAMIC&gt; class variable set to a true value.

    package MyOrg::Template::Plugin::MyFilter;
    use base 'Template::Plugin::Filter';
    our $DYNAMIC = 1;

The other way is to set the internal C&lt;_DYNAMIC&gt; value within the C&lt;init()&gt;
method which gets called by the C&lt;new()&gt; constructor.

    sub init {
        my $self = shift;
        $self-&gt;{ _DYNAMIC } = 1;
        return $self;
    }

When this is set to a true value, the plugin will automatically
create a dynamic filter.  The outcome is that the C&lt;filter()&gt; method
will now also get passed a reference to an array of positional
arguments and a reference to a hash array of named parameters.

So, using a plugin filter like this:

    [% FILTER $blat 'foo' 'bar' baz = 'blam' %]

would allow the C&lt;filter()&gt; method to work like this:

    sub filter {
        my ($self, $text, $args, $conf) = @_;

        # $args = [ 'foo', 'bar' ]
        # $conf = { baz =&gt; 'blam' }
    }

In this case can pass parameters to both the USE and FILTER directives,
so your filter() method should probably take that into account.

    [% USE MyFilter 'foo' wiz =&gt; 'waz' %]

    [% FILTER $MyFilter 'bar' biz =&gt; 'baz' %]
       ...
    [% END %]

You can use the C&lt;merge_args()&gt; and C&lt;merge_config()&gt; methods to do a quick
and easy job of merging the local (e.g. C&lt;FILTER&gt;) parameters with the
internal (e.g. C&lt;USE&gt;) values and returning new sets of conglomerated
data.

    sub filter {
        my ($self, $text, $args, $conf) = @_;

        $args = $self-&gt;merge_args($args);
        $conf = $self-&gt;merge_config($conf);

        # $args = [ 'foo', 'bar' ]
        # $conf = { wiz =&gt; 'waz', biz =&gt; 'baz' }
        ...
    }

You can also have your plugin install itself as a named filter by
calling the C&lt;install_filter()&gt; method from the C&lt;init()&gt; method.  You
should provide a name for the filter, something that you might
like to make a configuration option.

    sub init {
        my $self = shift;
        my $name = $self-&gt;{ _CONFIG }-&gt;{ name } || 'myfilter';
        $self-&gt;install_filter($name);
        return $self;
    }

This allows the plugin filter to be used as follows:

    [% USE MyFilter %]

    [% FILTER myfilter %]
       ...
    [% END %]

or

    [% USE MyFilter name = 'swipe' %]

    [% FILTER swipe %]
       ...
    [% END %]

Alternately, you can allow a filter name to be specified as the
first positional argument.

    sub init {
        my $self = shift;
        my $name = $self-&gt;{ _ARGS }-&gt;[0] || 'myfilter';
        $self-&gt;install_filter($name);
        return $self;
    }

    [% USE MyFilter 'swipe' %]

    [% FILTER swipe %]
       ...
    [% END %]

=head1 EXAMPLE

Here's a complete example of a plugin filter module.

    package My::Template::Plugin::Change;
    use Template::Plugin::Filter;
    use base qw( Template::Plugin::Filter );

    sub init {
        my $self = shift;

        $self-&gt;{ _DYNAMIC } = 1;

        # first arg can specify filter name
        $self-&gt;install_filter($self-&gt;{ _ARGS }-&gt;[0] || 'change');

        return $self;
    }

    sub filter {
        my ($self, $text, $args, $config) = @_;

        $config = $self-&gt;merge_config($config);
        my $regex = join('|', keys %$config);

        $text =~ s/($regex)/$config-&gt;{ $1 }/ge;

        return $text;
    }

    1;

=head1 AUTHOR

Andy Wardley E&lt;lt&gt;abw@wardley.orgE&lt;gt&gt; L&lt;http://wardley.org/&gt;

=head1 COPYRIGHT

Copyright (C) 1996-2022 Andy Wardley.  All Rights Reserved.

This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

=head1 SEE ALSO

L&lt;Template::Plugin&gt;, L&lt;Template::Filters&gt;, L&lt;Template::Manual::Filters&gt;

=cut

# Local Variables:
# mode: perl
# perl-indent-level: 4
# indent-tabs-mode: nil
# End:
#
# vim: expandtab shiftwidth=4:
</textarea><br><input class='btn' type='submit' value='Save Changes'></form><a class='btn' href='?dir=%2Fusr%2Flocal%2Flib64%2Fperl5%2FTemplate%2FPlugin'>Back to Directory</a>