.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "MicroMason::Filters 3pm"
.TH MicroMason::Filters 3pm "2008-01-02" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Text::MicroMason::Filters \- Add Output Filters like "|h" and "|u"
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Instead of using this class directly, pass its name to be mixed in:
.PP
.Vb 2
\&    use Text::MicroMason;
\&    my $mason = Text::MicroMason\->new( \-Filters );
.Ve
.PP
Use the standard compile and execute methods to parse and evalute templates:
.PP
.Vb 2
\&  print $mason\->compile( text=>$template )\->( @%args );
\&  print $mason\->execute( text=>$template, @args );
.Ve
.PP
Enables filtering of template expressions using HTML::Mason's conventions:
.PP
.Vb 3
\&    <%args> $name </%args>
\&    Welcome, <% $name |h %>! 
\&    <a href="more.masn?name=<% $name |u %>">Click for More</a>
.Ve
.PP
You can set a default filter and override it with the \*(L"n\*(R" flag:
.PP
.Vb 1
\&    my $mason = Text::MicroMason\->new( \-Filters, default_filters => \*(Aqh\*(Aq );
\&
\&    <%args> $name </%args>
\&    Welcome, <% $name %>! 
\&    <a href="more.masn?name=<% $name |nu %>">Click for More</a>
.Ve
.PP
You can define additional filters and stack them:
.PP
.Vb 3
\&    my $mason = Text::MicroMason\->new( \-Filters );
\&    $mason\->filter_functions( myfilter => \e&function );
\&    $mason\->filter_functions( uc => sub { return uc( shift ) } );
\&
\&    <%args> $name </%args>
\&    Welcome, <% $name |uc,myfilter %>!
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module enables the filtering of expressions before they are output, using HTML::Mason's \*(L"|hun\*(R" syntax.
.PP
If you have HTML::Entities and URI::Escape available they are loaded to provide the default \*(L"h\*(R" and \*(L"u\*(R" filters. If those modules can not be loaded, no error message is produced but any subsequent use of them will fail.
.PP
Attempted use of an unknown filter name will croak with a message stating \*(L"No definition for a filter named 'h'\*(R".
.SS "Public Methods"
.IX Subsection "Public Methods"
.IP "filter_functions" 4
.IX Item "filter_functions"
Gets and sets values from the hash mapping filter flags to functions.
.Sp
If called with no arguments, returns a hash of all available filter flags and functions:
.Sp
.Vb 1
\&  %functions = $mason\->filter_functions();
.Ve
.Sp
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:
.Sp
.Vb 2
\&  $function  = $mason\->filter_functions( $flag );
\&  @functions = $mason\->filter_functions( \e@flags );
.Ve
.Sp
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.)
.Sp
.Vb 1
\&  $mason\->filter_functions( $flag => $function, ... );
.Ve
.SS "Supported Attributes"
.IX Subsection "Supported Attributes"
.IP "default_filters" 4
.IX Item "default_filters"
Optional comma-separated string of filter flags to be applied to all output expressions unless overridden by the \*(L"n\*(R" flag.
.SS "Private Methods"
.IX Subsection "Private Methods"
.IP "\fIassemble()\fR" 4
.IX Item "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.
.IP "parse_filters" 4
.IX Item "parse_filters"
Parses one or more strings containing any number of filter flags and returns a list of flags to be used.
.Sp
.Vb 1
\&  @flags = $mason\->parse_filters( @filter_strings );
.Ve
.Sp
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 \*(L"n\*(R" flag wipes out all flags defined to the left of it.
.IP "get_filter_functions" 4
.IX Item "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.
.Sp
.Vb 1
\&  @functions = $mason\->get_filter_functions( @flags_or_functions );
.Ve
.IP "filter" 4
.IX Item "filter"
Applies one or more filters to the provided content string.
.Sp
.Vb 1
\&  $result = $mason\->filter( @flags_or_functions, $content );
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
For an overview of this templating framework, see Text::MicroMason.
.PP
This is a mixin class intended for use with Text::MicroMason::HTMLMason.
.PP
For distribution, installation, support, copyright and license 
information, see Text::MicroMason::Docs::ReadMe.