Text::...Filters(3pm)

💖 Text::...Filters(3pm) 💖

okay so bestie, this page came out of the User Contributed Perl Documentation pile, and it's literally the glow-up guide for output filters. pull up a chair, grab a boba, and let's get into it 🧋✨

---

✨ NAME ✨

Text::MicroMason::Filters — adds output filters like |h and |u. that's it, that's the whole vibe. 💅

---

🌸 SYNOPSIS 🌸

ngl, you do not use this class directly. instead you pass its name so it gets mixed in, like a lil friendship bracelet for your mason object:

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

then you just use the standard compile and execute methods to parse and evaluate templates, same as always:

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

this is what actually turns on filtering of template expressions, using syntax that's basically the same as what HTML::Mason v1 had:

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

you can also set default filters, and then shut them off with the n flag whenever you feel like it:

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>

and if you'd rather MicroMason always override the default filters instead of combining them? say less:

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

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

lastly, the main character move: you can define your own filters and stack them up like accessories 🔥

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 💅

so this module lets expressions get filtered before they're output, using syntax similar to the stuff available in HTML::Mason v1. periodt.

a few filter functions come standard with Text::MicroMason:

• if HTML::Entities is available, the h filter is set up to do HTML encoding.
• if URI::Escape is available, the u filter is set up to provide URI escaping.
• if those modules can't be loaded, no error message is produced — the corresponding filter just... isn't available. 🙈 silent treatment fr.

the p filter escapes non-ascii characters using Perl backslash notation to make them printable. it's retained for backwards compatibility, but it is not recommended because it may destroy Unicode or other non-ascii byte streams. lowkey a menace, highkey deprecated-coded.

use filter_functions() to define custom filter functions and associate them with filter names.

and if you try to use a filter name that doesn't exist? it will croak at you with a message stating No definition for a filter named 'h'. 💀

when you're specifying default_filters() or using filters inside a MicroMason interpolation, there are two ways to specify multiple filters. you can only use one of these techniques in a single filter specification, but default filters and inline filters can be specified differently.

1. up to 5 single character filters can be combined without delimiters:

<% $name |hu %> Apply the "h" and "u" filters in that order.

2. any number of filter names of any length can be combined with commas and/or spaces:

<% $name |u,js uc , h %> Apply the "u", "js", "uc", and "h" filters in that order.

and if the n filter is specified, all previously specified filters (including default filters) get skipped. iconic lil reset button 🎀

<% $name |u,h,uc,n,js %> Apply the "js" filter only.
<% $name |nu %> Skip default filters and apply the "u" filter.

---

👑 Public Methods

filter_functions

gets and sets values from the hash that maps filter flags to functions.

call it with no arguments and it hands you a hash of all available filter flags and functions:

%functions = $mason->filter_functions();

call it with a filter flag and you get the associated function back. or, if you hand it a reference to an array of flag names, you get a list of the functions:

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

and if you call it with one or more pairs of filter flags plus their associated functions, it adds them to the hash. heads up: any filter that might have existed with the same flag name is overwritten. so like, don't be messy about it 💅

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

---

🎀 Supported Attributes

default_filters

optional comma-separated string of filter flags that get applied to all output expressions, unless they're overridden by the n flag.

default_policy

optional. valid values are combine and override; default is combine. this attribute says what happens when both default_filters and inline filters are provided at the same time.

• if default_policy is combine (the default), then both default filters and inline filters get applied, in that order.
• if default_policy is override, default filters are only applied when no inline filters are specified.

combine is the default for backwards compatibility purposes, but new uses of the module probably want to use override instead. glow up, bestie ✨

---

🧚 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. very behind-the-scenes, very stage crew at the concert 🫶

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 you're using a combination of single-letter flags. flags are applied from left to right. and any use of the n flag wipes out all flags defined to the left of it. gone. deleted. not coming back 😭

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. no chill whatsoever.

@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, go read 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.

---

and that's the whole page, bestie!! this beauty shipped as part of perl v5.36.0, dated 2023-08-10 — the Text::...Filters(3pm) era, iykyk 🎀💜 go forth and filter responsibly ✨