NAME

       Text::MicroMason::Filters - Add Output Filters like "|h" and "|u"

SYNOPSIS

       Instead of using this class directly, pass its name to be mixed in:

           use Text::MicroMason;
           my $mason = Text::MicroMason->new( -Filters );

       Use the standard compile and execute methods to parse and evalute templates:

         print $mason->compile( text=>$template )->( @%args );
         print $mason->execute( text=>$template, @args );

       Enables filtering of template expressions using HTML::Mason's conventions:

           <%args> $name </%args>
           Welcome, <% $name |h %>!
           <a href="more.masn?name=<% $name |u %>">Click for More</a>

       You can set a default filter and override it with the "n" flag:

           my $mason = Text::MicroMason->new( -Filters, default_filters => 'h' );

           <%args> $name </%args>
           Welcome, <% $name %>!
           <a href="more.masn?name=<% $name |nu %>">Click for More</a>

       You can define additional filters and stack them:

           my $mason = Text::MicroMason->new( -Filters );
           $mason->filter_functions( myfilter => \&function );
           $mason->filter_functions( uc => sub { return uc( shift ) } );

           <%args> $name </%args>
           Welcome, <% $name |uc,myfilter %>!

DESCRIPTION

       This module enables the filtering of expressions before they are output, using HTML::Mason's "|hun"
       syntax.

       If you have HTML::Entities and URI::Escape available they are loaded to provide the default "h" and "u"
       filters. If those modules can not be loaded, no error message is produced but any subsequent use of them
       will fail.

       Attempted use of an unknown filter name will croak with a message stating "No definition for a filter
       named 'h'".

   Public Methods
       filter_functions
           Gets and sets values from the hash mapping filter flags to functions.

           If called with no arguments, returns a hash of all available filter flags and functions:

             %functions = $mason->filter_functions();

           If  called  with a filter flag returns the associated function, or if provided with a reference to an
           array of flag names returns a list of the functions:

             $function  = $mason->filter_functions( $flag );
             @functions = $mason->filter_functions( \@flags );

           If called with one or more pairs of filter flags and associated functions, adds  them  to  the  hash.
           (Any filter that might have existed with the same flag name is overwritten.)

             $mason->filter_functions( $flag => $function, ... );

   Supported Attributes
       default_filters
           Optional  comma-separated  string  of  filter  flags  to  be applied to all output expressions unless
           overridden by the "n" flag.

   Private Methods
       assemble()
           This method goes through the lexed template tokens looking for uses of filter flags,  which  it  then
           rewrites as appropriate method calls before passing the tokens on to the superclass.

       parse_filters
           Parses  one  or  more strings containing any number of filter flags and returns a list of flags to be
           used.

             @flags = $mason->parse_filters( @filter_strings );

           Flags should be separated by commas, except that the commas may be omitted when using  a  combination
           of  single-letter  flags. Flags are applied from left to right. Any use of the "n" flag wipes out all
           flags defined to the left of it.

       get_filter_functions
           Accepts filter flags or function references and returns a list of the corresponding  functions.  Dies
           if an unknown filter flag is used.

             @functions = $mason->get_filter_functions( @flags_or_functions );

       filter
           Applies one or more filters to the provided content string.

             $result = $mason->filter( @flags_or_functions, $content );

SEE ALSO

       For an overview of this templating framework, see Text::MicroMason.

       This is a mixin class intended for use with Text::MicroMason::HTMLMason.

       For     distribution,     installation,    support,    copyright    and    license    information,    see
       Text::MicroMason::Docs::ReadMe.

perl v5.14.2                                       2008-01-02                           MicroMason::Filters(3pm)