NAME

Text::Forge - ERB/PHP/ASP-style templating for Perl

SYNOPSIS

  use Text::Forge;
  my $forge = Text::Forge->new;

  # template in external file
  print $forge->run('/tmp/mytemplate');

  # inline template (scalar reference)
  print $forge->run(\"<h1>Hello, World! <%= scalar localtime %></h1>");

DESCRIPTION

Text::Forge is a simple templating system that allows you to embed Perl within plain text files. The syntax is very similar to other popular systems like ERB, ASP, and PHP.

Template Syntax

Templates are normal text files except for a few special tags:

  <% Perl code; nothing output %>
  <%= Perl expression; result is HTML encoded and output %>
  <%$ Perl expression; result is output (no encoding) %>
  <%? Perl expression; result is URL escaped and output %> 
  <%# Comment; entire block ignored %>

All blocks are evaluated within the same lexical scope (so my variables declared in one block are visible in subsequent blocks).

If a block is followed by a newline and you want to suppress it, add a minus to the close tag:

  <% ... -%>

Generating Templates

To generate a template, you need to instantiate a Text::Forge object and tell it the template file to use:

  my $tf = Text::Forge->new;
  print $tf->run('my_template');

Every template has access to a $forge object that provides some helpful methods and can be used to pass around context. Really, the $forge object is nothing more than a reference to the Text::Forge object being used to construct the template itself.

You can include a template within another template using the include() method. Here's how we might include a header in our main template.

  <% $forge->include('header') %>

Templates are really just Perl subroutines, so you can pass values into them and they can pass values back.

  <% my $rv = $forge->include('header', title => 'foo', meta => 'blurgle' ) %>

You can generate a template from a scalar (instead of an external file) by passing a reference to it.

  my $tf = Text::Forge->new;
  $tf->send(\"Hello Word <%= scalar localtime %>");

Caching

By default, templates are compiled, cached in memory, and are only recompiled if they change on disk. You can control this through the constructor:

  my $forge->new(cache => 2)

Valid cache values are:

  0 - always recompile
  1 - recompile if modified
  2 - never recompile

Search Paths

If a relative path is passed to the run() method, it is searched for within a list of paths. You can adjust the search paths through the search_paths() class method:

  Text::Forge->search_paths('.', '/tmp');

By default, the search path is just the current directory, '.'

Error Handling

Exceptions are raised on error. We take pains to make sure the line numbers reported in errors and warnings match the line numbers in the templates themselves.

Other Constructor Options

  # Automatically trim trailing newlines from all blocks.
  my $forge = Text::Forge->new(trim => 1);

  # Interpolate variables outside template blocks (treats the
  # whole template as a double quoted string). Not recommended.
  my $forge = Text::Forge->new(interpolate => 1);

AUTHOR

Copyright 1999-2007, Maurice Aubrey <maurice@hevanet.com>. All rights reserved.

This module is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

cpanm Text::Forge

perl -MCPAN -e shell
install Text::Forge