.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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 >0, 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
.\" ========================================================================
.\"
.IX Title "Text::MicroMason 3pm"
.TH Text::MicroMason 3pm "2023-08-10" "perl v5.36.0" "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 \- Simple and Extensible Templating
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Mason syntax provides several ways to mix Perl into a text template:
.PP
.Vb 12
\&    <%args>
\&      $name
\&    </%args>
\&    % if ( $name eq \*(AqDave\*(Aq ) {
\&      I\*(Aqm sorry <% $name %>, I\*(Aqm afraid I can\*(Aqt do that right now.
\&    % } else {
\&      <%perl>
\&        my $hour = (localtime)[2];
\&        my $daypart = ( $hour > 11 ) ? \*(Aqafternoon\*(Aq : \*(Aqmorning\*(Aq; 
\&      </%perl>
\&      Good <% $daypart %>, <% $name %>!
\&    % }
.Ve
.PP
Create a MicroMason object to interpret the templates:
.PP
.Vb 2
\&    use Text::MicroMason;
\&    $mason = Text::MicroMason\->new();
.Ve
.PP
Use the compile method to convert templates into a subroutines:
.PP
.Vb 2
\&    $coderef = $mason\->compile( text=>$template );
\&    print $coderef\->(\*(Aqname\*(Aq=>\*(AqAlice\*(Aq);
.Ve
.PP
Or use the execute method to parse and evaluate in one call:
.PP
.Vb 1
\&    print $mason\->execute( text=>$template, \*(Aqname\*(Aq=>\*(AqBob\*(Aq );
.Ve
.PP
Templates stored in files can be run directly or included in others:
.PP
.Vb 1
\&    print $mason\->execute( file=>"./greeting.msn", \*(Aqname\*(Aq=>\*(AqCharles\*(Aq);
.Ve
.PP
For additional features, select mixin classes to add to your MicroMason object:
.PP
.Vb 1
\&    $mason = Text::MicroMason\->new( qw( \-CatchErrors \-Safe \-Filters ) );
.Ve
.PP
You can import various functions if you prefer to avoid method calls:
.PP
.Vb 1
\&    use Text::MicroMason::Functions qw( compile execute );
\&
\&    print execute($template, \*(Aqname\*(Aq=>\*(AqDave\*(Aq);
\&
\&    $coderef = compile($template);
\&    print $coderef\->(\*(Aqname\*(Aq=>\*(AqBob\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Text::MicroMason interpolates blocks of Perl code embedded into text
strings.
.PP
Each MicroMason object acts as a \*(L"template compiler,\*(R" which converts
templates from text-with-embedded-code formats into ready-to-execute
Perl subroutines.
.SS "MicroMason Initialization"
.IX Subsection "MicroMason Initialization"
Use the \fBnew()\fR method to create a Text::MicroMason object with the
appropriate mixins and attributes.
.PP
.Vb 1
\&  $mason = Text::MicroMason\->new( %attribs );
.Ve
.PP
You may pass attributes as key-value pairs to the \fBnew()\fR method to save
various options for later use by the \fBcompile()\fR method.
.SS "Template Compilation"
.IX Subsection "Template Compilation"
To compile a text template, pass it to the \fBcompile()\fR method to produce a
new Perl subroutine to be returned as a code reference:
.PP
.Vb 1
\&  $code_ref = $mason\->compile( $type => $source, %attribs );
.Ve
.PP
Any attributes provided to \fBcompile()\fR will temporarily override the
persistent options defined by \fBnew()\fR, for that template only.
.PP
You can provide the template as a text string, a file name, or an open
file handle:
.PP
.Vb 5
\&  $code_ref = $mason\->compile( text => $template );
\&  $code_ref = $mason\->compile( text => \e$template );
\&  $code_ref = $mason\->compile( file => $filename );
\&  $code_ref = $mason\->compile( handle => $fh );
\&  $code_ref = $mason\->compile( handle => \e*FILE );
.Ve
.PP
Template files are just plain text files that contains the string to be
parsed. The files may have any name and extension you wish. The filename
specified can either be absolute or relative to the program's current
directory.
.SS "Template Execution"
.IX Subsection "Template Execution"
To execute the template and obtain the output, call a compiled function:
.PP
.Vb 1
\&  $result = $code_ref\->( @arguments );
.Ve
.PP
(Note that the \f(CW$code_ref\fR\->() syntax is unavailable in older versions of
Perl; use the equivalent &$\fBcode_ref()\fR syntax instead.)
.PP
As a shortcut, the execute method compiles and runs the template one time:
.PP
.Vb 2
\&  $result = $mason\->execute( $type => $source, @arguments );
\&  $result = $mason\->execute( $type => $source, \e%attribs, @arguments );
.Ve
.SS "Argument Passing"
.IX Subsection "Argument Passing"
You can pass arguments to a template subroutine using positional or
named arguments.
.PP
For positional arguments, pass the argument list and read from \f(CW@_\fR as usual:
.PP
.Vb 1
\&  $mason\->compile( text=>\*(AqHello <% shift(@_) %>.\*(Aq )\->( \*(AqDave\*(Aq );
.Ve
.PP
For named arguments, pass in a hash of key-value pairs to be made
accessible in an \f(CW%ARGS\fR hash within the template subroutine:
.PP
.Vb 1
\&  $mason\->compile( text=>\*(AqHello <% $ARGS{name} %>.\*(Aq )\->( name=>\*(AqDave\*(Aq );
.Ve
.PP
Additionally, you can use named arguments with the \f(CW%args\fR block syntax:
.PP
.Vb 1
\&  $mason\->compile( text=>\*(Aq<%args>$name</%args>Hello <% $name %>.\*(Aq )\->( name=>\*(AqDave\*(Aq );
.Ve
.SS "Mixin Selection"
.IX Subsection "Mixin Selection"
Arguments passed to \fBnew()\fR that begin with a dash will be added as mixin classes.
.PP
.Vb 1
\&  $mason = Text::MicroMason\->new( \-Mixin1, %attribs, \-Mixin2 );
.Ve
.PP
Every MicroMason object inherits from an abstract Base class and some
set of mixin classes. By combining mixins you can create subclasses with
the desired combination of features. See Text::MicroMason::Base for
documentation of the base class, including private methods and extension
mechanisms.
.PP
If you call the new method on Text::MicroMason, it automatically
includes the HTMLMason mixin, which provides the standard template
syntax. If you want to create an object without the default HTMLMason
functionality, call Text::MicroMason::Base\->\fBnew()\fR instead.
.PP
Some mixins define the syntax for a particular template format. You will
generally need to select one, and only one, of the mixins listed in
\&\*(L"\s-1TEMPLATE SYNTAXES\*(R"\s0.
.PP
Other mixins provide optional functionality. Those mixins may define
additional public methods, and may support or require values for various
additional attributes. For a list of such mixin classes, see \*(L"\s-1MIXIN
FEATURES\*(R"\s0.
.SH "TEMPLATE SYNTAXES"
.IX Header "TEMPLATE SYNTAXES"
Templates contain a mix of literal text to be output with some type of
markup syntax which specifies more complex behaviors.
.PP
The Text::MicroMason::HTMLMason mixin is selected by default. To enable
an alternative, pass its name to Text::MicroMason::Base\->new( \-
MixinName ).
.SS "HTMLMason"
.IX Subsection "HTMLMason"
The HTMLMason mixin provides lexer and assembler methods that handle
most elements of HTML::Mason's template syntax.
.PP
.Vb 2
\&  my $mason = Text::MicroMason::Base\->new( \-HTMLMason );
\&  my $output = $mason\->execute( text => $template, name => \*(AqBob\*(Aq );
\&
\&    <%args>
\&      $name => \*(AqGuest\*(Aq 
\&    </%args>
\&
\&    % if ( $name eq \*(AqDave\*(Aq ) {
\&      I\*(Aqm sorry <% $name %>, I\*(Aqm afraid I can\*(Aqt do that right now.
\&    % } else {
\&      <%perl>
\&        my $hour = (localtime)[2];
\&        my $daypart = ( $hour > 11 ) ? \*(Aqafternoon\*(Aq : \*(Aqmorning\*(Aq; 
\&      </%perl>
\&      Good <% $daypart %>, <% $name %>!
\&    % }
\&
\&    <& "includes/standard_footer.msn" &>
\&
\&    <%doc>
\&      Here\*(Aqs a private developr comment describing this template. 
\&    </%doc>
.Ve
.PP
For a definition of the template syntax, see Text::MicroMason::HTMLMason.
.SS "DoubleQuote"
.IX Subsection "DoubleQuote"
The DoubleQuote mixin uses Perl's double-quoting interpolation as a
minimalist syntax for templating.
.PP
.Vb 2
\&  my $mason = Text::MicroMason::Base\->new( \-DoubleQuote );
\&  my $output = $mason\->execute( text => $template, name => \*(AqBob\*(Aq );
\&
\&    ${ $::hour = (localtime)[2];
\&      $::daypart = ( $::hour > 11 ) ? \*(Aqafternoon\*(Aq : \*(Aqmorning\*(Aq; 
\&    \e\*(Aq\*(Aq }
\&    Good $::daypart, $ARGS{name}!
.Ve
.PP
For more information see Text::MicroMason::DoubleQuote.
.SS "Embperl"
.IX Subsection "Embperl"
The Embperl mixin support a template syntax similar to that used by the
HTML::Embperl module.
.PP
.Vb 2
\&  my $mason = Text::MicroMason::Base\->new( \-Embperl );
\&  my $output = $mason\->execute( text => $template, name => \*(AqBob\*(Aq );
\&
\&    [\- my $name = $ARGS{name}; \-]
\&    [$ if $name eq \*(AqDave\*(Aq $]
\&      I\*(Aqm sorry [+ $name +], I\*(Aqm afraid I can\*(Aqt do that right now.
\&    [$ else $]
\&      [\- 
\&        my $hour = (localtime)[2];
\&        my $daypart = ( $hour > 11 ) ? \*(Aqafternoon\*(Aq : \*(Aqmorning\*(Aq; 
\&      \-]
\&      Good [+ $daypart +], [+ $name +]!
\&    [$ endif $]
.Ve
.PP
For more information see Text::MicroMason::Embperl.
.SS "HTMLTemplate"
.IX Subsection "HTMLTemplate"
The HTMLTemplate mixin supports a syntax similar to that used by the
HTML::Template module.
.PP
.Vb 2
\&  my $mason = Text::MicroMason::Base\->new( \-HTMLTemplate );
\&  my $output = $mason\->execute( text => $template, name => \*(AqBob\*(Aq );
\&
\&    <TMPL_IF NAME="user_is_dave">
\&      I\*(Aqm sorry <TMPLVAR NAME="name">, I\*(Aqm afraid I can\*(Aqt do that right now.
\&    <TMPL_ELSE>
\&      <TMPL_IF NAME="daytime_is_morning">
\&        Good morning, <TMPLVAR NAME="name">!
\&      <TMPL_ELSE>
\&        Good afternoon, <TMPLVAR NAME="name">!
\&      </TMPL_IF>
\&    </TMPL_IF>
.Ve
.PP
For more information see Text::MicroMason::HTMLTemplate.
.SS "ServerPages"
.IX Subsection "ServerPages"
The ServerPages mixin supports a syntax similar to that used by the
Apache::ASP module.
.PP
.Vb 2
\&  my $mason = Text::MicroMason::Base\->new( \-ServerPages );
\&  my $output = $mason\->execute( text => $template, name => \*(AqBob\*(Aq );
\&
\&    <% my $name = $ARGS{name};
\&      if ( $name eq \*(AqDave\*(Aq ) {  %>
\&      I\*(Aqm sorry <%= $name %>, I\*(Aqm afraid I can\*(Aqt do that right now.
\&    <% } else { 
\&        my $hour = (localtime)[2];
\&        my $daypart = ( $hour > 11 ) ? \*(Aqafternoon\*(Aq : \*(Aqmorning\*(Aq; 
\&      %>
\&      Good <%= $daypart %>, <%= $name %>!
\&    <% } %>
.Ve
.PP
For more information see Text::MicroMason::ServerPages.
.SS "Sprintf"
.IX Subsection "Sprintf"
The Sprintf mixin uses Perl's sprintf formatting syntax for templating.
.PP
.Vb 2
\&  my $mason = Text::MicroMason::Base\->new( \-Sprintf );
\&  my $output = $mason\->execute( text => $template, \*(Aqmorning\*(Aq, \*(AqBob\*(Aq );
\&
\&    Good %s, %s!
.Ve
.PP
For more information see Text::MicroMason::Sprintf.
.SS "TextTemplate"
.IX Subsection "TextTemplate"
The TextTemplate mixin supports a syntax similar to that used by the
Text::Template module.
.PP
.Vb 2
\&  my $mason = Text::MicroMason::Base\->new( \-TextTemplate );
\&  my $output = $mason\->execute( text => $template, name => \*(AqBob\*(Aq );
\&
\&    { $hour = (localtime)[2];
\&      $daypart = ( $hour > 11 ) ? \*(Aqafternoon\*(Aq : \*(Aqmorning\*(Aq; 
\&    \*(Aq\*(Aq }
\&    Good { $daypart }, { $name }!
.Ve
.PP
For more information see Text::MicroMason::TextTemplate.
.SH "MIXIN FEATURES"
.IX Header "MIXIN FEATURES"
The following mixin classes can be layered on to your MicroMason object
to provide additional functionality.
.PP
To add a mixin's functionality, pass it's name with a dash to the \fBnew()\fR method:
.PP
.Vb 1
\&  $mason = Text::MicroMason\->new( \-CatchErrors, \-PostProcess );
.Ve
.SS "AllowGlobals"
.IX Subsection "AllowGlobals"
Enables access to a set of package variables to be shared with templates.
.PP
For details see Text::MicroMason::AllowGlobals.
.SS "CatchErrors"
.IX Subsection "CatchErrors"
Both compilation and run-time errors in your template are handled as
fatal exceptions. To prevent a template error from ending your program,
enclose it in an eval block:
.PP
.Vb 6
\&  my $result = eval { $mason\->execute( text => $template ) };
\&  if ( $@ ) {
\&    print "Unable to execute template: $@";
\&  } else {
\&    print $result;
\&  }
.Ve
.PP
To transparently add this functionality to your MicroMason object, see
Text::MicroMason::CatchErrors.
.SS "CompileCache"
.IX Subsection "CompileCache"
Calling execute repeatedly will be slower than compiling once and
calling the template function repeatedly, unless you enable
compilation caching.
.PP
For details see Text::MicroMason::CompileCache.
.SS "Debug"
.IX Subsection "Debug"
When trying to debug a template problem, it can be helpful to watch the
internal processes of template compilation. This mixin adds controllable
warning messages that show the intermediate parse information.
.PP
For details see Text::MicroMason::Debug.
.SS "LineNumbers"
.IX Subsection "LineNumbers"
Provide better line numbers when compilation fails, at the cost of
potentially slower compilation and execution.
.PP
For details see Text::MicroMason::LineNumbers.
.SS "ExecuteCache"
.IX Subsection "ExecuteCache"
Each time you execute the template all of the logic will be re\-
evaluated, unless you enable execution caching, which stores the output
of each template for each given set of arguments.
.PP
For details see Text::MicroMason::ExecuteCache.
.SS "Filters"
.IX Subsection "Filters"
HTML::Mason provides an expression filtering mechanism which is
typically used for applying \s-1HTML\s0 and \s-1URL\s0 escaping functions to output.
.PP
.Vb 1
\&  Text::MicroMason\->new(\-Filters)\->compile( text => $template );
\&
\&  <p> Hello <% $name |h %>!
.Ve
.PP
The Filters mixin provides this capability for Text::MicroMason
templates. To select it, add its name to your Mason initialization call:
.PP
.Vb 1
\&  my $mason = Text::MicroMason\->new( \-Filters );
.Ve
.PP
Output expressions may then be followed by \*(L"|h\*(R" or \*(L"|u\*(R" escapes; for
example this line would convert any ampersands in the output to the
equivalent \s-1HTML\s0 entity:
.PP
.Vb 1
\&  Welcome to <% $company_name |h %>
.Ve
.PP
For more information see Text::MicroMason::Filters.
.SS "PassVariables"
.IX Subsection "PassVariables"
Allows you to pass arguments to templates as variables instead of the
basic argument list.
.PP
For details see Text::MicroMason::PostProcess.
.SS "PostProcess"
.IX Subsection "PostProcess"
Allows you to specify one or more functions through which all template
output should be passed before it is returned.
.PP
For details see Text::MicroMason::PostProcess.
.SS "Safe"
.IX Subsection "Safe"
By default, the code embedded in a template has accss to all of the
capabilities of your Perl process, and could potentially perform
dangerous activities such as accessing or modifying files and starting
other programs.
.PP
If you need to execute untrusted templates, use the Safe module,
which can restrict the operations and data structures that template
code can access.
.PP
To add this functionality to your MicroMason object, see
Text::MicroMason::Safe.
.SS "TemplateDir"
.IX Subsection "TemplateDir"
The filenames passed to the \fBcompile()\fR or \fBexecute()\fR methods can be looked
up relative to a base directory path or the current template file.
.PP
To add this functionality to your MicroMason object, see
Text::MicroMason::TemplateDir.
.SS "TemplatePath"
.IX Subsection "TemplatePath"
The filenames passed to the \fBcompile()\fR or \fBexecute()\fR methods are looked up
relative to a list of multiple base directory paths, in order. It tries
as hard as possible to maintain compatibility with caching and <& &>
template includes.
.PP
To add this functionality to your MicroMason object, see
Text::MicroMason::TemplatePath.
.SH "OTHER INTERFACES"
.IX Header "OTHER INTERFACES"
.SS "Function Exporter"
.IX Subsection "Function Exporter"
Importable functions are provided for users who prefer a procedural interface.
.PP
The supported functions are listed in Text::MicroMason::Functions.
(For backwards compatibility, those functions can also be imported from
the main Text::MicroMason package.)
.SS "Template Frameworks"
.IX Subsection "Template Frameworks"
Adaptor modules are available to use MicroMason from within other frameworks. 
For more information, see Any::Template::Backend::Text::MicroMason and
Catalyst::View::MicroMason.
.SS "Inline"
.IX Subsection "Inline"
MicroMason templates can be embbeded within your source code using Inline. 
For more information, see Inline::Mason.
.SH "EXCEPTIONS"
.IX Header "EXCEPTIONS"
Text::MicroMason croaks on error, with an appropriate error string. Some
commonly occurring error messages are described below (where \f(CW%s\fR
indicates variable message text). See also the pod for each mixin class,
for additional exception strings that may be thrown.
.IP "\(bu" 4
MicroMason parsing halted at \f(CW%s\fR
.Sp
Indicates that the parser was unable to finish tokenising the source
text. Generally this means that there is a bug somewhere in the regular
expressions used by \fBlex()\fR.
.Sp
(If you encounter this error, please feel free to file a bug report or
send an example of the error to the author using the addresses below,
and I'll attempt to correct it in a future release.)
.IP "\(bu" 4
MicroMason compilation failed: \f(CW%s\fR
.Sp
The template was parsed successfully, but the Perl subroutine declaration
it was converted to failed to compile. This is generally a result of a
syntax error in one of the Perl expressions used within the template.
.IP "\(bu" 4
Error in template subroutine: \f(CW%s\fR
.Sp
Additional diagnostic for compilation errors, showing the text of the
subroutine which failed to compile.
.IP "\(bu" 4
Error in template file \f(CW%s\fR, interpreted as: \f(CW%s\fR
.Sp
Additional diagnostic for compilation errors in external files, showing
the filename and the text of the subroutine which failed to compile.
.IP "\(bu" 4
MicroMason execution failed: \f(CW%s\fR
.Sp
After parsing and compiling the template successfully, the subroutine was
run and caused a fatal exception, generally because that some Perl code
used within the template caused \fBdie()\fR to be called (or an equivalent
function like croak or confess).
.IP "\(bu" 4
MicroMason: filename is missing or empty
.Sp
One of the compile or execute methods was called with an empty or
undefined filename, or one of the compile_file or execute_file methods
was called with no arguments.
.IP "\(bu" 4
MicroMason can't read from \f(CW%s:\fR \f(CW%s\fR
.Sp
One of the compile_file or execute_file functions was called but we were
unable to read the requested file, because the file path is incorrect or
we have insufficient privileges to read that file.
.IP "\(bu" 4
[Reference / Object]
.Sp
If the code inside the template throws a reference or object while calling
\&\fBdie()\fR, MicroMason will re-throw the reference to the calling code.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
For distribution, installation, support, copyright and license 
information, see Text::MicroMason::Docs::ReadMe.