Text::...MLMason(3pm)

📦

version 2.23 · 3 versions

2.23 · debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
2.23 · ubuntu jammy
2.23 · debian bookworm

, in debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

Text::...MLMason(3pm) — User Contributed Perl Documentation, part 1 of 2, bestie 💖 no cap, this one's long so we're splitting it. Buckle up, the vibe is immaculate and the facts are staying exactly where they are. 🎀

✨ NAME ✨

Text::MicroMason::HTMLMason — Simple Compiler for Mason-style Templating 🦋

🌸 SYNOPSIS 🌸

okay so first you create a MicroMason object to interpret the templates:

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

Then you use the standard compile and execute methods to parse and evaluate templates:

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

Mason syntax provides several ways to mix Perl into a text template — it's giving versatility, periodt:

<%args>
  $name
</%args>

% if ( $name eq 'Dave' ) {
  I'm sorry <% $name %>, I'm afraid I can't do that right now.
% } else {
  <%perl>
    my $hour = (localtime)[2];
    my $daypart = ( $hour > 11 ) ? 'afternoon' : 'morning';
  </%perl>
  Good <% $daypart %>, <% $name %>!
% }

<& "includes/standard_footer.msn" &>

<%doc>
  Here's a private developr comment describing this template.
</%doc>

💅 DESCRIPTION 💅

The Text::MicroMason::HTMLMason class provides lexer and assembler methods that allow Text::MicroMason to handle most elements of HTML::Mason's template syntax. Lowkey iconic of it. 💜

🌈 Compatibility with HTML::Mason 🌈

HTML::Mason is a full-featured application server toolkit with many fatures, of which only the templating functionality is emulated. (Yes, the original says "fatures" — we keep it real, typos and all, because every detail matters bestie. 😭)

The following sets of HTML::Mason features are supported by Text::MicroMason:

Template interpolation with <% expr %> ✨
Literal Perl lines with leading % 🔥
Named %args, %perl, %once, %init, %cleanup, and %doc blocks 👑
The $m mason object, although with many fewer methods 💀
Expression filtering with |h and |u (via -Filter mixin) 🦋

The following sets of HTML::Mason features are not supported by Text::MicroMason:

No %attr, %flag, %shared, %method, or %def blocks. 🙈
No shared files like autohandler and dhandler. 🚫
No $r request object. No mod_perl integration or configuration capability. 😤

Contributed patches to add these features of HTML::Mason would be welcomed by the author. Possible implementations are described in Text::MicroMason::ToDo. 🫶

🔒 Private Methods 🔒

The following internal methods are used to implement the syntax described below. They're the behind-the-scenes main characters, iykyk. 💅

lex_token

( $type, $value ) = $mason->lex_token();

Supports HTML::Mason's markup syntax.

Attempts to parse a token from the template text stored in the global $_ and returns a token type and value. Returns an empty list if unable to parse further due to an error. No cap, that's the whole vibe. ✨

assembler_rules()

Returns a hash of text elements used for Perl subroutine assembly. Used by assemble().

Supports HTML::Mason's named blocks of Perl code and documentation: %once, %init, %cleanup, and %doc. 🎀

assemble_args

Called by assemble(), this method provides support for Mason's <%args> blocks. 🦋

TEMPLATE SYNTAX ✨

okay bestie, here's the vibe. Mason-style templating looks like this, lifted straight from HTML::Mason:

% my $noun = 'World';
Hello <% $noun %>!
How are ya?

and when Text::MicroMason interprets that same template, it produces the exact same output HTML::Mason would:

Hello World!
How are ya?

Text::MicroMason::HTMLMason supports a syntax that's mostly a subset of the one HTML::Mason uses. iykyk 💅

Template Markup 🎀

these are all the markup types you'll find in template pages:

literal_text — anything that isn't specifically parsed by one of the rules below gets interpreted as literal text. no notes, no cap.
<% perl_expr %> — a Perl expression to be interpolated into the result.

like, this template text will return a scheduled greeting:

Good <% (localtime)[2]>11 ? 'afternoon' : 'morning' %>.

the block can span multiple lines and it's scoped inside a do block, so it can contain multiple Perl statements and it does not need to end with a semicolon.

Good <% my $h = (localtime)[2]; $h > 11 ? 'afternoon'
                                        : 'morning'  %>.

% perl_code — lines that begin with the % character, with no leading whitespace, can contain arbitrary Perl code that gets executed when the template hits that portion. their result is not interpolated into the output.

e.g. this template text will return a scheduled greeting:

% my $daypart = (localtime)[2]>11 ? 'afternoon' : 'morning';
Good <% $daypart %>.

the line can contain one or more statements. this code is not placed in its own block scope, so it should typically end with a semicolon; it can still open a spanning block scope that gets closed by a later perl block.

e.g. this template text returns one of two different messages each time it's interpreted:

% if ( int rand 2 ) {
  Hello World!
% } else {
  Goodbye Cruel World!
% }

it also lets you quickly comment out sections of a template by prefacing each line with "% #".

this is equivalent to a <%perl>...</%perl> block.

<& template_filename, arguments &> — includes the results of a separate file containing MicroMason code, compiling it and executing it with any arguments passed after the filename.

e.g. we could drop this template text into a separate file:

Good <% $ARGS{hour} >11 ? 'afternoon' : 'morning' %>.

assuming that file was named greeting.msn, its results could be embedded within the output of another script like so:

<& "greeting.msn", hour => (localtime)[2] &>

<%name> ... </%name> — a named block holds a span of text. the name at the start and the end must match, and must be one of the supported block names.

depending on the name, it performs one of the behaviors described in "Named Blocks".

Named Blocks 👑

these named block types are supported:

<%perl> perl_code </%perl> — blocks surrounded by %perl tags can contain arbitrary Perl code. their result is not interpolated into the result.

these blocks can span multiple lines in your template file. e.g. the template below initializes a Perl variable inside a %perl block, then interpolates the result into a message.

<%perl>
  my $count = join '', map "$_... ", ( 1 .. 9 );
</%perl>
Here are some numbers: <% $count %>

the code can contain one or more statements. it is not placed in its own block scope, so it should typically end with a semicolon; it can still open a spanning block scope closed by a later perl block.

e.g. when the template text below is evaluated it will return a sequence of digits:

Here are some numbers:
<%perl>
  foreach my $digit ( 1 .. 9 ) {
</%perl>
    <% $digit %>...
<%perl>
  }
</%perl>

if the block is immediately followed by a line break, that break is discarded. these blocks are not whitespace sensitive, so the template could be squished into a single line if you wanted.

<%args> variable => default </%args> — defines a collection of variables to be initialized from named arguments passed to the subroutine. arguments are separated by one or more newlines, and may optionally be followed by a default value. if no default value is provided, the argument is required and the subroutine will croak if it isn't provided. 😭

e.g. adding the following block to a template initializes three named variables, and will fail if no a => '...' argument pair is passed:

<%args>
  $a
  @b => qw( foo bar baz )
  %c => ()
</%args>

all the arguments are available as lexically scoped (my) variables in the rest of the component. default expressions are evaluated in top-to-bottom order, and one expression may reference an earlier one.

only valid Perl variable names may be used in <%args> sections. parameters with non-valid variable names cannot be pre-declared and must be fetched manually out of the %ARGS hash.

<%init> perl_code </%init> — similar to a %perl block, except the code is moved up to the start of the subroutine. this lets a template's initialization code live at the end of the file instead of forcing it to be at the top.

e.g. this template text returns a scheduled greeting:

Good <% $daypart %>.
<%init>
  my $daypart = (localtime)[2]>11 ? 'afternoon' : 'morning';
</%init>

<%cleanup> perl_code </%cleanup> — similar to a %perl block, except the code is moved down to the end of the subroutine.
<%once> perl_code </%once> — similar to a %perl block, except the code is executed once, when the template is first compiled. (if a caller is using execute, this code will be run repeatedly, but if they call compile and then invoke the resulting subroutine multiple times, the %once code will only execute during the compilation step.)

this code does not have access to %ARGS and cannot generate output. it can be used to define constants, create persistent variables, or otherwise prepare the environment.

e.g. this template text returns an increasing number each time it's called:

<%once>
  my $counter = 1000;
</%once>
The count is <% ++ $counter %>.

<%doc> ... </%doc> — provides space for template developer documentation or comments which are not included in the output.
<%text> ... </%text> — produces literal text in the template output. can be used to surround text that contains other markup tags that should not be interpreted.

equivalent to un-marked-up text.

and now, plot twist: the following named block types are not supported by HTML::Mason, but they're supported here as a side-effect of the way the lexer and assembler are implemented. we love an accidental feature 💖

<%expr> ... </%expr> — a Perl expression to be interpolated into the result. the block can span multiple lines and is scoped inside a do block, so it can contain multiple Perl statements and it need not end with a semicolon.

equivalent to the <% ... %> markup syntax.

<%file> template_filename, arguments </%file> — includes the results of a separate file containing MicroMason code, compiling it and executing it with any arguments passed after the filename.

<%file> "greeting.msn", hour => (localtime)[2] </%file>

equivalent to the <& ... &> markup syntax.

TEMPLATE CODING TECHNIQUES 💅

Assembling Perl Source Code

when Text::MicroMason::Base assembles your lexed template into the equivalent Perl subroutine, all of the literal (non-Perl) pieces get converted to $_out->('text'); statements, and the interpolated expressions get converted to $_out->( do { expr } ); statements. code from %perl blocks and % lines is included exactly as-is.

your code is eval'd in the Text::MicroMason::Commands package. the use strict; pragma is enabled by default to simplify debugging. bestie, that pragma is your friend, fr fr.

Internal Sub-templates

you can create sub-templates within your template text by defining them as anonymous subroutines and then calling them repeatedly. e.g. this template concatenates the results of the draw_item sub-template for each of three items:

<h1>We've Got Items!</h1>

% my $draw_item = sub {
  <p><b><% $_[0] %></b>:<br>
    <a href="/more?item=<% $_[0] %>">See more about <% $_[0] %>.</p>
% };

<%perl>
  foreach my $item ( qw( Foo Bar Baz ) ) {
    $draw_item->( $item );
  }
</%perl>

Returning Text from Perl Blocks

to append to the result from within Perl code, call $_out->(text). (the $_out->() syntax is unavailable in older versions of Perl; use the equivalent &$_out() syntax instead.)

e.g. the template text below returns '123456789' when it's evaluated:

<%perl>
  foreach my $digit ( 1 .. 9 ) {
    $_out->( $digit )
  }
</%perl>

you can also directly manipulate the value @OUT, which contains the accumulating result. iconic.

e.g. the template text below returns an altered version of its message if a true value for 'minor' is passed as an argument when the template is executed:

This is a funny joke.
% if ( $ARGS{minor} ) { foreach ( @OUT ) { tr[a-z][n-za-m] } }