Text::MicroMason::Base3pm

Public Methods

new()

  $mason = Text::MicroMason::Base->new( -Mixin1, -Mixin2, %attribs );

Creates a new Text::MicroMason object with mixins and attributes.

Arguments beginning with a dash will be added as mixin classes. Other arguments are added to the hash of attributes.

compile()

  $code_ref = $mason->compile( text => $template, %options );
  $code_ref = $mason->compile( file => $filename, %options );

Parses the provided template and converts it into a new Perl subroutine.

execute()

  $result = $mason->execute( text => $template, @arguments );
  $result = $mason->execute( file => $filename, @arguments );
  $result = $mason->execute( code => $code_ref, @arguments );
  $result = $mason->execute( $type => $source, \%options, @arguments );

Returns the results produced by the template, given the provided arguments.

Attributes

Attributes can be set in a call to new() and locally overridden in a call to compile().

output_sub

Optional reference to a subroutine to call with each piece of template output. If this is enabled, template subroutines will return an empty string.

Private Methods

The following internal methods are used to implement the public interface described above, and may be overridden by subclasses and mixins.

class()

  $class = Text::MicroMason::Base->class( @Mixins );

Creates a subclass of this package that also inherits from the other classes named. Provided by Class::MixinFactory::HasAFactory.

create()

  $mason = $class->create( %options );
  $clone = $mason->create( %options );

Creates a new instance with the provided key value pairs.

To obtain the functionality of one of the supported mixin classes, use the class method to generate the mixed class before calling create(), as is done by new().

defaults()

This class method is called by new() to provide key-value pairs to be included in the new instance.

prepare()

  ($self, $src_type, $src_data) = $self->prepare($src_type, $src_data, %options)

Called by compile(), the prepare method allows for single-use attributes and provides a hook for mixin functionality.

The prepare method provides a hook for mixins to normalize or resolve the template source type and value arguments in various ways before the template is read using one of the read_type() methods.

It returns an object reference that may be a clone of the original mason object with various compile-time attributes applied. The cloning is a shallow copy performed by the create() method. This means that the $m object visible to a template may not be the same as the MicroMason object on which compile() was originally called.

Please note that this clone-on-prepare behavior is subject to change in future releases.

interpret

   $perl_code = $mason->interpret( $src_type, $src_data );

Called by compile(), the interpret method then calls the read(), lex(), and assemble() methods.

read

  $template = $mason->read( $src_type, $src_data );

Called by interpret(). Calls one of the below read_* methods.

read_text

  $template = $mason->read_text( $template );

Called by read() when the template source type is "text", this method simply returns the value of the text string passed to it.

read_file

  ( $contents, %path_info ) = $mason->read_file( $filename );

Called by read() when the template source type is "file", this method reads and returns the contents of the named file.

read_handle

  $template = $mason->read_handle( $filehandle );

Called by read() when the template source type is "handle", this method reads and returns the contents of the filehandle passed to it.

lex

  @token_pairs = $mason->lex( $template );

Called by interpret(). Parses the source text and returns a list of pairs of token types and values. Loops through repeated calls to lex_token().

lex_token

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

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.

Abstract method; must be implemented by subclasses.

assemble

  $perl_code = $mason->assemble( @tokens );

Called by interpret(). Assembles the parsed token series into the source code for the equivalent Perl subroutine.

assembler_rules()

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

The assembly template defines the types of blocks supported and the order they appear in, as well as where other standard elements should go. Those other elements also appear in the assembler hash.

eval_sub

  $code_ref = $mason->eval_sub( $perl_code );

Called by compile(). Compiles the Perl source code for a template using eval(), and returns a code reference.

croak_msg

Called when a fatal exception has occurred.

NEXT

Enhanced superclass method dispatch for use inside mixin class methods. Allows mixin classes to redispatch to other classes in the inheritance tree without themselves inheriting from anything. Provided by Class::MixinFactory::NEXT.

Private Functions

_printable

  $special_characters_escaped = _printable( $source_string );

Converts non-printable characters to readable form using the standard backslash notation, such as "\n" for newline.