<<

NAME

MT::Builder - Parser and interpreter for MT templates

SYNOPSIS

    use MT::Builder;
    use MT::Template::Context;

    my $build = MT::Builder->new;
    my $ctx = MT::Template::Context->new;

    my $tokens = $build->compile($ctx, '<$MTVersion$>')
        or die $build->errstr;
    defined(my $out = $build->build($ctx, $tokens))
        or die $build->errstr;

DESCRIPTION

MT::Builder provides the parser and interpreter for taking a template body and turning it into a generated output page. An MT::Builder object knows how to parse a string of text into tokens, then take those tokens and build a scalar string representing the output of the page. It does not, however, know anything about the types of tags that it encounters; it hands off this work to the MT::Template::Context object, which can look up a tag and determine whether it's valid, whether it's a container or substitution tag, etc.

All MT::Builder knows is the basic structure of a Movable Type tag, and how to break up a string into pieces: plain text pieces interspersed with tag callouts. It then knows how to take a list of these tokens/pieces and build a completed page, using the same MT::Template::Context object to actually fill in the values for the Movable Type tags.

USAGE

MT::Builder->new

Constructs and returns a new parser/interpreter object.

$build->compile($ctx, $string)

Given an MT::Template::Context object $ctx, breaks up the scalar string $string into tokens and returns the list of tokens as a reference to an array. Returns undef on compilation failure.

$build->build($ctx, \@tokens [, \%cond ])

Given an MT::Template::Context object $ctx, turns a list of tokens \@tokens and generates an output page. Returns the output page on success, undef on failure. Note that the empty string ('') and the number zero (0) are both valid return values for this method, so you should check specifically for an undefined value when checking for errors.

The optional argument \%cond specifies a list of conditions under which the tokens will be interpreted. If provided, \%cond should be a reference to a hash, where the keys are MT tag names (without the leading MT), and the values are boolean flags specifying whether to include the tag; a true value means that the tag should be included in the final output, a false value that it should not. This is useful when a template includes conditional container tags (eg <MTEntryIfExtended>), and you wish to influence the inclusion of these container tags. For example, if a template contains the container

    <MTEntryIfExtended>
    <$MTEntryMore$>
    </MTEntryIfExtended>

and you wish to exclude this conditional, you could call build like this:

    my $out = $build->build($ctx, $tokens, { EntryIfExtended => 0 });

$build->syntree2str(\@tokens)

Internal debugging routine to dump a set of template tokens. Returns a readable string of contents of the $tokens parameter.

ERROR HANDLING

On an error, the above methods return undef, and the error message can be obtained by calling the method errstr on the object. For example:

    defined(my $out = $build->build($ctx, $tokens))
        or die $build->errstr;

AUTHOR & COPYRIGHTS

Please see the MT manpage for author, copyright, and license information.

<<