.\" 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::Safe 3pm"
.TH Text::MicroMason::Safe 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::Safe \- Compile all Templates in a Safe Compartment
.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( \-Safe );
.Ve
.PP
Use the standard compile and execute methods to parse and evaluate templates:
.PP
.Vb 2
\&  print $mason\->compile( text=>$template )\->( @%args );
\&  print $mason\->execute( text=>$template, @args );
.Ve
.PP
Safe usage restricts templates from accessing your files or data:
.PP
.Vb 1
\&  print $mason\->execute( text=>"<% qx! cat /etc/passwd ! %>" ); # dies
\&
\&  print $mason\->execute( text=>"The time is <% time() %>." ); # dies
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This package adds support for Safe compartments to MicroMason, allowing 
you to  restrict the operations that a template can perform.
.PP
By default, these safe calls prevent the code in a template from performing
any system activity or accessing any of your other Perl code.  Violations
may result in either compile-time or run-time errors, so make sure you
are using an eval block or the CatchErrors trait to catch exceptions.
.PP
.Vb 2
\&  use Text::MicroMason;
\&  my $mason = Text::MicroMason\->new( \-Safe );
\&
\&  $result = eval { $mason\->execute( text => $template ) };
.Ve
.PP
\&\fBCaution:\fR Although this appears to provide a significant amount of security for untrusted templates, please take this with a grain of salt. A bug in either this module or in the core Safe module could allow a clever attacker to defeat the protection. At least one bug in the Safe module has been found and fixed in years past, and there could be others.
.SS "Supported Attributes"
.IX Subsection "Supported Attributes"
.IP "safe" 4
.IX Item "safe"
Optional reference to a Safe compartment. If you do not provide this, one
is generated for you.
.Sp
To enable some operations or share variables or functions with the template
code, create a Safe compartment and configure it before passing it in as
the value of the \*(L"safe\*(R" attribute:
.Sp
.Vb 3
\&  $safe = Safe\->new();
\&  $safe\->permit(\*(Aqtime\*(Aq);
\&  $safe\->share(\*(Aq$foo\*(Aq);
\&
\&  $mason = Text::MicroMason\->new( \-Safe, safe => $safe );
\&
\&  $result = eval { $mason\->execute( text => $template ) };
.Ve
.IP "safe_methods" 4
.IX Item "safe_methods"
\&\fB\s-1IMPORTANT NOTE:\s0\fR The \f(CW\*(C`safe_methods\*(C'\fR parameter is deprecated and will
be removed in future versions of Text::MicroMason (unless a Safe and
future-proof implementation can be found).  If you use this parameter,
you will receive a warning via carp:
.Sp
\&\*(L"* \s-1WARNING:\s0 safe_methods is deprecated; please see the pod\*(R"
.Sp
This parameter works correctly with sufficiently old versions of the
Safe module (prior to the release of perl 5.12.1), but modern versions
of Safe make it impossible for a Safe compartment to run any code
outside the compartment.  Even with the object shared within the Safe
compartment, there is currently no known way to call methods on it
without defining the whole class within the compartment (which isn't
safe).
.Sp
If anyone has an appropriately safe solution that will allow
\&\f(CW\*(C`safe_methods\*(C'\fR to work, please submit a patch to the module maintainer.
Also see t/32\-safe.t for tests related to \f(CW\*(C`safe_methods\*(C'\fR that are
currently being skipped.
.Sp
The following pod is provided for legacy purposes only.  It is
strongly recommended that you do not use this method.  It is no longer
allowed to call methods from within a \*(L"Safe\*(R" template, because it
isn't actually safe.
.Sp
A space-separated string of methods names to be supported by the Safe::Facade.
.Sp
To control which Mason methods are available within the template, pass a
\&\f(CW\*(C`safe_methods\*(C'\fR argument to \fBnew()\fR followed by the method names in a 
space-separated string.
.Sp
For example, to allow templates to include other templates, using \f(CW$m\fR\->execute
or the \*(L"<& file &>\*(R" include syntax, you would need to allow the execute
method. We'll also load the TemplateDir mixin with strict_root on to prevent
inclusion of templates from outside the current directory.
.Sp
.Vb 3
\&  # safe_methods is DEPRECATED, please see above
\&  $mason = Text::MicroMason\->new( \-Safe, safe_methods => \*(Aqexecute\*(Aq, 
\&                                  \-TemplateDir, strict_root => 1 );
.Ve
.Sp
If you're combining this with the Filters mixin, you'll also need to allow
calls to the filter method; to allow multiple methods, join their names
with spaces:
.Sp
.Vb 4
\&  # safe_methods is DEPRECATED, please see above
\&  $mason = Text::MicroMason\->new( \-Safe, safe_methods => \*(Aqexecute filter\*(Aq, 
\&                                  \-TemplateDir, strict_root => 1,
\&                                  \-Filters );
.Ve
.SS "Private Methods"
.IX Subsection "Private Methods"
.IP "\fBeval_sub()\fR" 4
.IX Item "eval_sub()"
Instead of the \fBeval()\fR used by the base class, this calls \fBreval()\fR on a Safe
compartment.
.IP "\fBsafe_compartment()\fR" 4
.IX Item "safe_compartment()"
Returns the Safe compartment passed by the user or generates a new one.
.IP "\fBsafe_facade()\fR" 4
.IX Item "safe_facade()"
Generates an instance of the Safe::Facade equipped with only the methods
listed in the safe_methods attribute.
.SS "Private Safe::Facade class"
.IX Subsection "Private Safe::Facade class"
Code compiled in a Safe compartment only has access to a limited version of
the template compiler in the \f(CW$m\fR variable, and can not make changes to the
attributes of the real MicroMason object. This limited object is an instance
of the Text::MicroMason::Safe::Facade class and can only perform certain
pre-defined methods.
.IP "\fBnew()\fR" 4
.IX Item "new()"
Creates a new hash-based instance mapping method names to subroutine
references.
.IP "\fBfacade_method()\fR" 4
.IX Item "facade_method()"
Calls a named method by looking up the corresponding subroutine and calling
it.
.IP "\s-1\fBAUTOLOAD\s0()\fR" 4
.IX Item "AUTOLOAD()"
Generates wrapper methods that call the \fBfacade_method()\fR for any lowercase
method name.
.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::Base.
.PP
For distribution, installation, support, copyright and license 
information, see Text::MicroMason::Docs::ReadMe.