Text::...::Base(3pm)

💖 Text::MicroMason::Base — bestie, it's the Abstract Template Compiler 💖

okay so this is the manual page for Text::...::Base(3pm), living its best life under User Contributed Perl Documentation. Sit down, grab a strawberry drink 🍓, and let's get into it — because this module is genuinely iconic and you're gonna want to know it.

---

✨ NAME ✨

Text::MicroMason::Base — Abstract Template Compiler. That's the whole vibe. It's the base class, the blueprint, the mother of the whole squad. 🫶

---

🌸 SYNOPSIS 🌸

First thing's first: create a MicroMason object so it can interpret your templates:

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

Then use the execute method to parse and evaluate a template in one go:

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

Or — and this is the slay move — compile it into a subroutine and evaluate it over and over again:

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

And if your templates live in files, you can run them directly or pull them into other templates:

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

periodt. 💅

---

🦋 DESCRIPTION 🦋

Text::MicroMason::Base is an abstract superclass — meaning it's the parent-energy class that hands down a parser and an execution environment for an extensible templating system. It's giving main character, but it's the kind of main character who lets the whole cast shine. ✨

👑 Public Methods

• new() — creates a new Text::MicroMason object with mixins and attributes.

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

Here's the tea: arguments that start with a dash get added as mixin classes. Every other argument gets tossed into the hash of attributes. Easy.

• compile() — parses the template you hand it and converts it into a brand-new Perl subroutine. 🧚

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

• execute() — returns the results your template produced, given whatever arguments you passed in.

$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 );

🌈 Attributes

Attributes can be set in a call to new(), and then locally overridden in a call to compile(). Mix and match, bestie.

• output_sub — an optional reference to a subroutine that gets called with each piece of template output. Heads up: if this is enabled, template subroutines will return an empty string. (yes, really, that's the deal.)

🔒 Private Methods

These are the internal methods that make the public interface above actually work. Subclasses and mixins are allowed to override them — they're private but they're not, like, gatekept. 🙈

• class() — creates a subclass of this package that also inherits from the other classes named. Provided by Class::MixinFactory::HasAFactory.

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

• create() — creates a new instance with the provided key-value pairs.

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

To get the functionality of one of the supported mixin classes, use the class method to generate the mixed class before calling create() — which is exactly what new() does. iykyk.

• defaults() — this class method gets called by new() to provide key-value pairs that get included in the new instance.
• prepare() — called by compile(). It allows for single-use attributes and gives mixins a hook to do their thing.

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

The prepare method is the hook for mixins to normalize or resolve the template source type and value arguments in all sorts of ways, before the template gets 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. Which means: the $m object that's visible to a template may not be the same as the MicroMason object on which compile() was originally called. 😭

Heads up, bestie: this clone-on-prepare behavior is subject to change in future releases. Don't build your whole personality on it.

• interpret — called by compile(). The interpret method then calls the read(), lex(), and assemble() methods. It's a whole relay race. 🏃♀️

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

• read — called by interpret(). It calls one of the read_* methods below.

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

• read_text — called by read() when the template source type is "text". This method just... returns the value of the text string passed to it. Simple, no notes. 💜

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

• read_file — called by read() when the template source type is "file". It reads and returns the contents of the named file.

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

• read_handle — called by read() when the template source type is "handle". It reads and returns the contents of the filehandle passed to it.

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

• lex — called by interpret(). Parses the source text and returns a list of pairs of token types and values. It loops through repeated calls to lex_token().

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

• 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 it can't parse any further due to an error.

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

Abstract method — it must be implemented by subclasses. No skipping this one, fr fr.

• assemble — called by interpret(). Assembles the parsed token series into the source code for the equivalent Perl subroutine. 🔥

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

• 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, plus where other standard elements should go. Those other elements also show up in the assembler hash. Very organized of it.

• eval_sub — called by compile(). It compiles the Perl source code for a template using eval(), and returns a code reference.

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

• croak_msg — called when a fatal exception has occurred. 😵 (we don't love when this one shows up, but it's there for you.)
• NEXT — enhanced superclass method dispatch, for use inside mixin class methods. It lets mixin classes redispatch to other classes in the inheritance tree without themselves inheriting from anything. Provided by Class::MixinFactory::NEXT. That's the iconique move right there. 👑

🌟 Private Functions

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

$special_characters_escaped = _printable( $source_string );

---

🎀 EXTENDING 🎀

You can add functionality to this module by creating subclasses or mixin classes. Yes, you. Go off.

To create a subclass, just inherit from the base class or from some dynamically-assembled class. To create your own mixin classes that can be combined with other mixin features, go examine the operation of the class() and NEXT() methods. That's where the magic lives. ✨

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's passed the template source value, and it 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. It 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 by creating a method with a corresponding name prefixed by "assemble_". It's passed the token value or contents, and it should return a new token pair that's 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 ever calling execute.

---

🌈 SEE ALSO 🌈

• For an overview of this whole templating framework, go see Text::MicroMason.
• For distribution, installation, support, copyright and license information, go see Text::MicroMason::Docs::ReadMe.

---

and that's the whole page, bestie 💖 no cap, you're now lowkey an expert on the abstract template compiler.

this was perl v5.36.0, dated 2023-08-10 — sending you off with all the love, mwah 💅✨