NAME

Text::TemplateLite::Renderer - A rendering-management class for Text::TemplateLite

VERSION

Version 0.01

SYNOPSIS

    my $tpl = Text::TemplateLite->new->set(q{<<$var>>});
    print $tpl->render({ var => 'hello' })->result;

    # Setting execution limits before rendering:
    my $rndr = $tpl->new_renderer
      ->limit(step_length => 1000)
      ->limit(total_steps => 1000)
      ->render;

    # Checking for incomplete results after rendering:
    croak "Template rendering exceeded resource limits"
      if $rndr->exceeded_limits;

DESCRIPTION

This is the rendering companion class for Text::TemplateLite. It manages template variables and resource usage when rendering a template.

USER METHODS

This section describes methods for normal usage.

new( )

This creates and returns a new renderer instance. The renderer must be associated with a template (see "template($template)") before rendering.

reset( )

This resets the renderer between consecutive renderings. It clears any previous result and associated usage statistics and exceeded-limit information (but not the limits themselves). It returns the rendering object.

template( )

template($template)

The first form returns the current template engine instance (a Text::TemplateLite).

The second form sets the current template engine instance to $template and returns the rendering object. This is called automatically by "new_renderer( )" in Text::TemplateLite.

limit($type)

limit($type, $limit)

The first form returns the current limit for the specified type.

The second form sets a limit and returns the rendering object. A numeric limit sets a specific limit; undef removes the limit.

The limit types supported in this version are:

step_length

This is the maximum length (in characters) allowed to be returned as the result of any step (or sequence of steps) in the template execution.

For example, given:

    ??($condition, $some$variables, $default)

The substitutions of $condition and $default, the concatenation of $some and $variables, and the return value from function ?? will each be truncated to a length of step_length (and step_length will be marked exceeded) if necessary.

total_steps

This is the maximum number of steps that may be executed in the template code (and across all templates if external template calls are involved).

Template execution will stop (and total_steps will be exceeded) after this many steps.

render(\%variables)

This method renders the associated template with the specified variables and returns the rendering object (not the result; see "result( )").

Beware! The hashref of variables is subject to modification during rendering!

exceeded_limits( )

exceeded_limits(@limits)

The first form returns a list of names of any exceeded limits.

The second form adds the specified limits to the list of exceeded limits, stops rendering, and returns the template engine object.

See "limit($type, $limit)" for types.

result( )

This method returns the most recent rendering result, or undef if there isn't one.

stop( )

This sets the stop flag (visible in "info( )"), causing template execution to terminate further processing. It returns the rendering object.

info( )

This returns the most recent rendering's execution information as a hash. The template engine currently returns the following usage (but library functions could potentially add metrics for specific calls):

stop

This is true if execution stopped before the end of the template (e.g. because total_steps was exceeded).

total_steps

This is the total number of steps that were executed (including any recorded by external template calls).

undef_calls

This is the number of calls to undefined functions or external templates during rendering.

vars( )

This method returns the hash of current template variables.

AUTHOR METHODS

This section describes methods generally only used by library function authors.

execute_each($list)

This method is a short-cut to call the template engine's execute_each method.

execute_sequence($code)

This method is a short-cut to call the template engine's execute_sequence method.

last_renderer( )

This method returns the most recent external template renderer. This information is only retained until the current rendering has completed or the next external template call, whichever happens first.

ENGINE METHODS

These methods are used by the template engine. You should probably not be calling them directly.

step( )

step($step)

The first form checks that it is OK to perform another step (based on the total_steps limit) in template execution. If so, it increments the step usage and returns true. Otherwise it returns false.

The second form sets the step usage to the specified step number if it is higher than the current value and returns the rendering object.

render_external($template, \%vars)

Render an external template, communicating resource usage in and out.

The external renderer is returned.

cpanm Text::TemplateLite

perl -MCPAN -e shell
install Text::TemplateLite