NAME

Text::MicroMason::Safe - Compile all Templates in a Safe Compartment

SYNOPSIS

Instead of using this class directly, pass its name to be mixed in:

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

Use the execute method to parse and evalute a template:

  print $mason->execute( text=>$template, 'name'=>'Dave' );

Safe usage restricts templates from accessing your files or data:

  print $mason->execute( text=>"<% qx! cat /etc/passwd ! %>" ); # dies

  print $mason->execute( text=>"The time is <% time() %>." ); # dies

DESCRIPTION

This package adds support for Safe compartments to MicroMason, allowing you to restrict the operations that a template can perform.

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.

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

  $result = eval { $mason->execute( text => $template ) };

Supported Attributes

safe

Optional reference to a Safe compartment. If you do not provide this, one is generated for you.

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 "safe" attribute:

  $safe = Safe->new();
  $safe->permit('time');
  $safe->share('$foo');

  $mason = Text::MicroMason->new( -Safe, safe => $safe );

  $result = eval { $mason->execute( text => $template ) };

safe_methods

A space-separated string of methods names to be supported by the SafeFacade.

Code compiled in a Safe compartment only has access to a limited version of the the $m variable. This object is an instance of the Text::MicroMason::SafeFacade class and can only perform certain pre-defined methods.

To control which Mason methods are available, pass a safe_methods argument to new() followed by the method names in a space-separated string.

For example, to allow templates to include other templates, or use the "<& file &>" include syntax, you would need to allow the execute method:

  $mason = Text::MicroMason->new( -Safe, safe_methods => 'execute' );

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:

  $mason = Text::MicroMason->new( -Safe, safe_methods => 'execute filter' );

Private Methods

eval_sub()

Instead of the eval() used by the base class, this calls reval() on a Safe compartment.

safe_compartment()

Returns the Safe compartment passed by the user or generates a new one.

safe_facade()

Generates an instance of the SafeFacade equipped with only the methods listed in the safe_methods attribute.

Private SafeFacade class

new()

Creates a new hash-based instance mapping method names to subroutine references.

facade_method()

Calls a named method by looking up the corresponding subroutine and calling it.

AUTOLOAD()

Generates wrapper methods that call the facade_method() for any lowercase method name.

SEE ALSO

For an overview of this templating framework, see Text::MicroMason.

This is a mixin class intended for use with Text::MicroMason::Base.

For distribution, installation, support, copyright and license information, see Text::MicroMason::Docs::ReadMe.