.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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::Functions 3pm"
.TH Text::MicroMason::Functions 3pm "2019-11-10" "perl v5.30.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::Functions \- Function Exporter for Simple Mason Templates
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Use the execute function to parse and evaluate a template:
.PP
.Vb 2
\&    use Text::MicroMason::Functions qw( execute );
\&    print execute($template, \*(Aqname\*(Aq=>\*(AqDave\*(Aq);
.Ve
.PP
Or compile it into a subroutine, and evaluate repeatedly:
.PP
.Vb 4
\&    use Text::MicroMason::Functions qw( compile );
\&    $coderef = compile($template);
\&    print $coderef\->(\*(Aqname\*(Aq=>\*(AqDave\*(Aq);
\&    print $coderef\->(\*(Aqname\*(Aq=>\*(AqBob\*(Aq);
.Ve
.PP
Templates stored in files can be run directly or included in others:
.PP
.Vb 2
\&    use Text::MicroMason::Functions qw( execute_file );
\&    print execute_file( "./greeting.msn", \*(Aqname\*(Aq=>\*(AqCharles\*(Aq);
.Ve
.PP
Safe usage restricts templates from accessing your files or data:
.PP
.Vb 2
\&    use Text::MicroMason::Functions qw( safe_execute );
\&    print safe_execute( $template, \*(Aqname\*(Aq=>\*(AqBob\*(Aq);
.Ve
.PP
All above functions are available in an error-catching \*(L"try_*\*(R" form:
.PP
.Vb 2
\&    use Text::MicroMason::Functions qw( try_execute );
\&    ($result, $error) = try_execute( $template, \*(Aqname\*(Aq=>\*(AqAlice\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
As an alternative to the object-oriented interface, text containing MicroMason markup code can be compiled and executed by calling the following functions.
.PP
Please note that this interface is maintained primarily for backward compatibility with version 1 of Text::MicroMason, and it does not provide access to some of the newer features.
.PP
Each function creates a new MicroMason object, including any necessary traits such as Safe compilation or CatchErrors for exceptions, and then passes its arguments to an appropriate method on that object.
.PP
You may import any of these functions by including their names in your 
\&\f(CW\*(C`use Text::MicroMason\*(C'\fR statement.
.SS "Basic Invocation"
.IX Subsection "Basic Invocation"
To evaluate a Mason-like template, pass it to \fBexecute()\fR:
.PP
.Vb 1
\&  $result = execute( $mason_text );
.Ve
.PP
Alternately, you can call \fBcompile()\fR to generate a subroutine for your template, and then run the subroutine:
.PP
.Vb 1
\&  $result = compile( $mason_text )\->();
.Ve
.PP
If you will be interpreting the same template repeatedly, you can save the compiled version for faster execution:
.PP
.Vb 2
\&  $sub_ref = compile( $mason_text );
\&  $result = $sub_ref\->();
.Ve
.PP
(Note that the \f(CW$sub_ref\fR\->() syntax is unavailable in older versions of Perl; use the equivalent &$\fBsub_ref()\fR syntax instead.)
.SS "Argument Passing"
.IX Subsection "Argument Passing"
You can also pass a list of key-value pairs as arguments to execute, or to the compiled subroutine:
.PP
.Vb 1
\&  $result = execute( $mason_text, %args );
\&  
\&  $result = $sub_ref\->( %args );
.Ve
.PP
Within the scope of your template, any arguments that were provided will be accessible in the global \f(CW@_\fR, the \f(CW%ARGS\fR hash, and any variables named in an \f(CW%args\fR block.
.PP
For example, the below calls will all return '<b>Foo</b>':
.PP
.Vb 3
\&  execute(\*(Aq<b><% shift(@_) %></b>\*(Aq, \*(AqFoo\*(Aq);
\&  execute(\*(Aq<b><% $ARGS{label} %></b>\*(Aq, label=>\*(AqFoo\*(Aq);
\&  execute(\*(Aq<%args>$label</%args><b><% $label %></b>\*(Aq, label=>\*(AqFoo\*(Aq);
.Ve
.SS "Template Files"
.IX Subsection "Template Files"
A parallel set of functions exist to handle templates which are stored in a file:
.PP
.Vb 2
\&  $template = compile_file( \*(Aq./report_tmpl.msn\*(Aq );
\&  $result = $template\->( %args );
\&
\&  $result = execute_file( \*(Aq./report_tmpl.msn\*(Aq, %args );
.Ve
.PP
Template documents are just plain text files that contains the string to be parsed. The files may have any name you wish, and the .msn extension shown above is not required.
.SS "Error Checking"
.IX Subsection "Error Checking"
Both compilation and run-time errors in your template are handled as fatal
exceptions. The provided \fBtry_execute()\fR and \fBtry_compile()\fR functions use a mixin class which wraps an eval { } block around the basic \fBexecute()\fR or \fBcompile()\fR
methods. In a scalar context they return the result of the call, or
undef if it failed; in a list context they return the results of the call
(undef if it failed) followed by the error message (undef if it succeeded).
For example:
.PP
.Vb 6
\&  ($result, $error) = try_execute( $mason_text );
\&  if ( ! $error ) {
\&    print $result;
\&  } else {
\&    print "Unable to execute template: $error";
\&  }
.Ve
.PP
A matching pair of try_*\fB_file()\fR wrappers are available to catch run-time errors in reading a file or parsing its contents:
.PP
.Vb 1
\&  ($template, $error) = try_compile_file( \*(Aq./report_tmpl.msn\*(Aq );
\&
\&  ($result, $error) = try_execute_file( \*(Aq./report_tmpl.msn\*(Aq, %args );
.Ve
.PP
For more information, see Text::MicroMason::CatchErrors.
.SS "Safe Compartments"
.IX Subsection "Safe Compartments"
If you wish to restrict the operations that a template can perform,
use the \fBsafe_compile()\fR and \fBsafe_execute()\fR functions, or their
try_*() wrappers.
.PP
For more information, see Text::MicroMason::Safe.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
For an overview of this templating framework, see Text::MicroMason.
.PP
For distribution, installation, support, copyright and license 
information, see Text::MicroMason::Docs::ReadMe.