Text::MicroMason::Base - Abstract Template Compiler

       Text::MicroMason::Base is an abstract superclass that provides a parser and execution environment for an
       extensible templating system.

   PublicMethodsnew()
             $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.

   PrivateMethods
       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.

   PrivateFunctions
       _printable
             $special_characters_escaped = _printable( $source_string );

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

       You can add functionality to this module by creating subclasses or mixin classes.

       To create a subclass, just inherit from the base class or some  dynamically-assembled  class.  To  create
       your  own  mixin  classes  which  can be combined with other mixin features, examine the operation of the
       class() and NEXT() methods.

       Key areas for subclass writers are:

       prepare
           You can intercept and re-write template source arguments by overriding this method.

       read_*
           You can support a new template source type by creating a method with a corresponding name prefixed by
           "read_". It is passed the template source value and should return the raw text to be lexed.

           For example, if a subclass defined a method named read_from_db, callers could  compile  templates  by
           calling "->compile( from_db => 'welcome-page' )".

       lex_token
           Replace this to parse a new template syntax. Is receives the text to be parsed in $_ and should match
           from the current position to return the next token type and its contents.

       assembler_rules
           The assembler data structure is used to construct the Perl subroutine for a parsed template.

       assemble_*
           You  can  support  a  new  token  type  be  creating  a  method with a corresponding name prefixed by
           "assemble_". It is passed the token value or contents, and should return a new  token  pair  that  is
           supported by the assembler template.

           For  example, if a subclass defined a method named assemble_sqlquery, callers could compile templates
           that contained a "<%sqlquery> ... </%sqlquery>" block. The assemble_sqlquery method  could  return  a
           "perl => $statements" pair with Perl code that performed some appropriate action.

       compile
           You can wrap or cache the results of this method, which is the primary public interface.

       execute
           You  typically  should  not  depend on overriding this method because callers can invoke the compiled
           subroutines directly without calling execute.

       Text::MicroMason::Base - Abstract Template Compiler

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

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

perl v5.36.0                                       2023-08-10                        Text::MicroMason::Base(3pm)

       Create a MicroMason object to interpret the templates:

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

       Use the execute method to parse and evaluate a template:

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

       Or compile it into a subroutine, and evaluate repeatedly:

           $coderef = $mason->compile( text=>$template );
           print $coderef->('name'=>'Dave');
           print $coderef->('name'=>'Bob');

       Templates stored in files can be run directly or included in others:

           print $mason->execute( file=>"./greeting.msn", 'name'=>'Charles');