.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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::Base 3pm"
.TH Text::MicroMason::Base 3pm "2023-08-10" "perl v5.36.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::Base \- Abstract Template Compiler
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Create a MicroMason object to interpret the templates:
.PP
.Vb 2
\&    use Text::MicroMason;
\&    my $mason = Text::MicroMason\->new();
.Ve
.PP
Use the execute method to parse and evaluate a template:
.PP
.Vb 1
\&    print $mason\->execute( text=>$template, \*(Aqname\*(Aq=>\*(AqDave\*(Aq );
.Ve
.PP
Or compile it into a subroutine, and evaluate repeatedly:
.PP
.Vb 3
\&    $coderef = $mason\->compile( text=>$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 1
\&    print $mason\->execute( file=>"./greeting.msn", \*(Aqname\*(Aq=>\*(AqCharles\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Text::MicroMason::Base is an abstract superclass that provides a parser 
and execution environment for an extensible templating system.
.SS "Public Methods"
.IX Subsection "Public Methods"
.IP "\fBnew()\fR" 4
.IX Item "new()"
.Vb 1
\&  $mason = Text::MicroMason::Base\->new( \-Mixin1, \-Mixin2, %attribs );
.Ve
.Sp
Creates a new Text::MicroMason object with mixins and attributes.
.Sp
Arguments beginning with a dash will be added as mixin classes.
Other arguments are added to the hash of attributes.
.IP "\fBcompile()\fR" 4
.IX Item "compile()"
.Vb 2
\&  $code_ref = $mason\->compile( text => $template, %options );
\&  $code_ref = $mason\->compile( file => $filename, %options );
.Ve
.Sp
Parses the provided template and converts it into a new Perl subroutine.
.IP "\fBexecute()\fR" 4
.IX Item "execute()"
.Vb 3
\&  $result = $mason\->execute( text => $template, @arguments );
\&  $result = $mason\->execute( file => $filename, @arguments );
\&  $result = $mason\->execute( code => $code_ref, @arguments );
\&
\&  $result = $mason\->execute( $type => $source, \e%options, @arguments );
.Ve
.Sp
Returns the results produced by the template, given the provided arguments.
.SS "Attributes"
.IX Subsection "Attributes"
Attributes can be set in a call to \fBnew()\fR and locally overridden in a call to \fBcompile()\fR.
.IP "output_sub" 4
.IX Item "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.
.SS "Private Methods"
.IX Subsection "Private Methods"
The following internal methods are used to implement the public interface described above, and may be overridden by subclasses and mixins.
.IP "\fBclass()\fR" 4
.IX Item "class()"
.Vb 1
\&  $class = Text::MicroMason::Base\->class( @Mixins );
.Ve
.Sp
Creates a subclass of this package that also inherits from the other classes named. Provided by Class::MixinFactory::HasAFactory.
.IP "\fBcreate()\fR" 4
.IX Item "create()"
.Vb 2
\&  $mason = $class\->create( %options );
\&  $clone = $mason\->create( %options );
.Ve
.Sp
Creates a new instance with the provided key value pairs.
.Sp
To obtain the functionality of one of the supported mixin classes, use the class method to generate the mixed class before calling \fBcreate()\fR, as is done by \fBnew()\fR.
.IP "\fBdefaults()\fR" 4
.IX Item "defaults()"
This class method is called by \fBnew()\fR to provide key-value pairs to be included in the new instance.
.IP "\fBprepare()\fR" 4
.IX Item "prepare()"
.Vb 1
\&  ($self, $src_type, $src_data) = $self\->prepare($src_type, $src_data, %options)
.Ve
.Sp
Called by \fBcompile()\fR, the prepare method allows for single-use attributes and provides a hook for mixin functionality.
.Sp
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 \fBread_type()\fR methods.
.Sp
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 \fBcreate()\fR method. This means that the \f(CW$m\fR object visible to a template may not be the same as the MicroMason object on which \fBcompile()\fR was originally called.
.Sp
Please note that this clone-on-prepare behavior is subject to change in future releases.
.IP "interpret" 4
.IX Item "interpret"
.Vb 1
\&   $perl_code = $mason\->interpret( $src_type, $src_data );
.Ve
.Sp
Called by \fBcompile()\fR, the interpret method then calls the \fBread()\fR, \fBlex()\fR, and \fBassemble()\fR methods.
.IP "read" 4
.IX Item "read"
.Vb 1
\&  $template = $mason\->read( $src_type, $src_data );
.Ve
.Sp
Called by \fBinterpret()\fR. Calls one of the below read_* methods.
.IP "read_text" 4
.IX Item "read_text"
.Vb 1
\&  $template = $mason\->read_text( $template );
.Ve
.Sp
Called by \fBread()\fR when the template source type is \*(L"text\*(R", this method simply returns the value of the text string passed to it.
.IP "read_file" 4
.IX Item "read_file"
.Vb 1
\&  ( $contents, %path_info ) = $mason\->read_file( $filename );
.Ve
.Sp
Called by \fBread()\fR when the template source type is \*(L"file\*(R", this method reads and returns the contents of the named file.
.IP "read_handle" 4
.IX Item "read_handle"
.Vb 1
\&  $template = $mason\->read_handle( $filehandle );
.Ve
.Sp
Called by \fBread()\fR when the template source type is \*(L"handle\*(R", this method reads and returns the contents of the filehandle passed to it.
.IP "lex" 4
.IX Item "lex"
.Vb 1
\&  @token_pairs = $mason\->lex( $template );
.Ve
.Sp
Called by \fBinterpret()\fR. Parses the source text and returns a list of pairs of token types and values. Loops through repeated calls to \fBlex_token()\fR.
.IP "lex_token" 4
.IX Item "lex_token"
.Vb 1
\&  ( $type, $value ) = $mason\->lex_token();
.Ve
.Sp
Attempts to parse a token from the template text stored in the global \f(CW$_\fR and returns a token type and value. Returns an empty list if unable to parse further due to an error.
.Sp
Abstract method; must be implemented by subclasses.
.IP "assemble" 4
.IX Item "assemble"
.Vb 1
\&  $perl_code = $mason\->assemble( @tokens );
.Ve
.Sp
Called by \fBinterpret()\fR. Assembles the parsed token series into the source code for the equivalent Perl subroutine.
.IP "\fBassembler_rules()\fR" 4
.IX Item "assembler_rules()"
Returns a hash of text elements used for Perl subroutine assembly. Used by \fBassemble()\fR.
.Sp
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.
.IP "eval_sub" 4
.IX Item "eval_sub"
.Vb 1
\&  $code_ref = $mason\->eval_sub( $perl_code );
.Ve
.Sp
Called by \fBcompile()\fR. Compiles the Perl source code for a template using \fBeval()\fR, and returns a code reference.
.IP "croak_msg" 4
.IX Item "croak_msg"
Called when a fatal exception has occurred.
.IP "\s-1NEXT\s0" 4
.IX Item "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.
.SS "Private Functions"
.IX Subsection "Private Functions"
.IP "_printable" 4
.IX Item "_printable"
.Vb 1
\&  $special_characters_escaped = _printable( $source_string );
.Ve
.Sp
Converts non-printable characters to readable form using the standard backslash notation, such as \*(L"\en\*(R" for newline.
.SH "EXTENDING"
.IX Header "EXTENDING"
You can add functionality to this module by creating subclasses or mixin classes.
.PP
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 \fBclass()\fR and \s-1\fBNEXT\s0()\fR methods.
.PP
Key areas for subclass writers are:
.IP "prepare" 4
.IX Item "prepare"
You can intercept and re-write template source arguments by overriding this method.
.IP "read_*" 4
.IX Item "read_*"
You can support a new template source type by creating a method with a corresponding name prefixed by \*(L"read_\*(R". It is passed the template source value and should return the raw text to be lexed.
.Sp
For example, if a subclass defined a method named read_from_db, callers could compile templates by calling \f(CW\*(C`\->compile( from_db => \*(Aqwelcome\-page\*(Aq )\*(C'\fR.
.IP "lex_token" 4
.IX Item "lex_token"
Replace this to parse a new template syntax. Is receives the text to be parsed in \f(CW$_\fR and should match from the current position to return the next token type and its contents.
.IP "assembler_rules" 4
.IX Item "assembler_rules"
The assembler data structure is used to construct the Perl subroutine for a parsed template.
.IP "assemble_*" 4
.IX Item "assemble_*"
You can support a new token type be creating a method with a corresponding name prefixed by \*(L"assemble_\*(R". It is passed the token value or contents, and should return a new token pair that is supported by the assembler template.
.Sp
For example, if a subclass defined a method named assemble_sqlquery, callers could compile templates that contained a \f(CW\*(C`<%sqlquery> ... </%sqlquery>\*(C'\fR block. The assemble_sqlquery method could return a \f(CW\*(C`perl => $statements\*(C'\fR pair with Perl code that performed some appropriate action.
.IP "compile" 4
.IX Item "compile"
You can wrap or cache the results of this method, which is the primary public interface.
.IP "execute" 4
.IX Item "execute"
You typically should not depend on overriding this method because callers can invoke the compiled subroutines directly without calling execute.
.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.