Introduction

NAME

An introduction to the Wigwam Perl module.

Introduction

Wigwam is a template processing system which has primarily served as a pet project over the past several years. It's posted here with the hope that some of the ideas put to use in Wigwam might find their way into other projects, or inspire new ideas.

Synopsis

  use strict;
  use Text::Wigwam;
  my $template = Text::Wigwam->new( text => join( '', <DATA> ) )
    or die $Text::Wigwam::ERROR;
  my ($err, $txt) = $template->execute(
    {
        greeting => 'Hello',
        entity => 'World'
    }
  );
  die $err if $err;
  print $txt;   # Hello, World.
  # Now we re-use the same template with different parameters.
  # This time we invoke the execute method using scalar context, which implies
  # that we want Wigwam to die if an error is encountered.
  $txt = $template->execute(
    {
        greeting => 'Welcome',
        entity => 'Fred'
    }
  );
  print $txt;   # Welcome, Fred.
  __DATA__
  [!! #parameters < greeting entity > !!]
  [!! greeting !!], [!! entity !!].

Extensibility

Wigwam's functionality can be extended in a number of ways, but the most unique is user-coded directives.

  [!! #join '; ' ( 1 2 3 4 5 ) !!]

The supporting Perl code for the #join directive is listed below.

  package Text::Wigwam::Directives;     # Directive tree base
  sub _proto_join { [ SCALAR, ARRAY ] } # Prototype
  sub _join {                           # Handler
    my ($Api) = @_;
    join( $Api->get_arg, @{$Api->get_arg} )
  }

The information provided in the prototype ensures that the handler will receive the expected data type for each of its arguments, thereby minimizing the amount of code required in the handler, and reducing the likelihood of runtime errors.

Reusability

Directives are stored in Perl library files under the guise of Wigwam plug-ins and modules. This allows them to be easily reused in other templates.

Wigwam templates are also reusable, as they can be called by other templates and simply executed, or stored in a variable where they can then be executed multiple times with varying parameters.

Configurability

Each template may contain its own configuration tag which is processed prior to template execution. It can be used to specify parsing options, debugging features, template characteristics (such as redefining tag delimiters), or to load plug-ins & modules. It may also be used to define default settings for, or impose restrictions upon, subsequently invoked templates.

Directive tree

The directive tree is a name space hierarchy into which directives can be loaded, defined, or imported. Directives may be organized into various branches of the directive tree (nested name spaces) and accessed from within templates either explicitly, or indirectly by way of an ordered path mechanism. Templates can also be restricted to specific branches, thereby limiting the functions available to them. This allows Wigwam to simultaneously provide template environments with varying degrees of functionality ranging from strict variable interpolation, to turing-complete scripting languages.

Data handling

Wigwam employs simple notational conventions which can be used in templates to either explicitly or indirectly reference data elements that are stored within arbitrary complex data structures made up of nested arrays and hashes.

Debugger

Wigwam's debugger displays runtime errors, debug information, and warnings in context within a beautified redraw of the relevant templates.

Flexibility

Templates can be written interchanging text blocks with code blocks, or omitting them altogether - whichever the user feels is more appropriate for the task at hand.

 [!!
     /* Iterate over a text block, denoted by !!> and <!! */
     #foreach num (  1 2 3 4 5 ) !!>
       [!! num !!]
     <!!
     /* Iterate over a code block, denoted by the braces */
     #foreach num ( 1 2 3 4 5 ) { num }
     /* Iterate over a single token, the 'num' variable */
     #foreach num ( 1 2 3 4 5 ) num
  !!]

Uses

Wigwam can be used virtually anywhere you want to intermingle text with data.

Documentation

The Wigwam package contains full documentation in Perl's POD format, and is constantly updated as Wigwam develops. We recommend that you start with the basics

Development

Wigwam is no longer under active development. Its OO-interface and embedded parsing options tag implementation could use some rethinking, but other than that, it's a pretty solid token parser.

Feedback

We can be reached at the following address:

DJOHNSTON, <djohnston@cpan.org>