NAME
Text::MicroMason - Simplified HTML::Mason Templating
DESCRIPTION
Text::MicroMason interpolates blocks of Perl code embedded into text
strings, using the simplest features of HTML::Mason.
Here's an example of Mason-style templating, taken from the HTML::Mason
manpage:
% my $noun = 'World';
Hello <% $noun %>!
How are ya?
Interpreting this template with Text::MicroMason produces the same
output as it would in HTML::Mason:
Hello World!
How are ya?
MOTIVATION
The HTML::Mason module provides a useful syntax for dynamic template
interpretation (sometimes called embedded scripting): plain text (or
HTML) containing occasional chunks of Perl code whose results are
interpolated into the text when the template is "executed."
However, HTML::Mason also provides a full-featured web application
framework with mod_perl integration, a caching engine, and numerous
other functions, and there are times in which I'd like to use the
templating capability without configuring a full Mason installation.
Thus, the Text::MicroMason module was born: it supports the core aspects
of the HTML::Mason syntax ("<%...%>" expressions, "%...\n" and
"<%perl>..." blocks, "<& file &>" includes, "%ARGS" and
"$_out->()" ), and omits the features that are web specific (like
autohandlers) or are less widely used (like "<%method>" blocks).
You may well be thinking "yet another dynamic templating module?
Sheesh!" And you'd have a good point. There certainly are a variety of
templating toolkits on CPAN already; even restricting ourselves to those
which use Perl syntax for both interpolated expressions and flow control
(as opposed to "little languages") there's a fairly crowded field,
including Template::Toolkit, Template::Perl, Text::Template, and
Text::ScriptTemplate, as well as those that are part of full-blown web
application frameworks like Apache::ASP, ePerl, HTML::Embperl, and
HTML::Mason.
Nonetheless, I think this module occupies a useful niche: it provides a
reasonable subset of HTML::Mason syntax in a very light-weight fashion.
In comparison to the other modules listed, MicroMason aims to be fairly
lightweight, using one eval per parse, converting the template to an
cacheable unblessed subroutine ref, eschewing method calls, and
containing only 90 or so lines of Perl code.
COMPATIBILITY WITH HTML::MASON
See the HTML::Mason manpage for a much more full-featured version of the
capabilities provided by this module.
If you've already got HTML::Mason installed, configured, and loaded into
your process, you're probably better off using it rather than this
package. HTML::Mason's "$interp->make_component()" method allows you to
parse a text string without saving it to disk first.
Unsupported Features
The following sets of HTML::Mason features are not supported by
Text::MicroMason:
* No %attr, %shared, %method, %def, %init, or %args blocks.
* No |h or |u options to escape the result of interpolated
expressions.
* No $m Mason interpreter context.
* No $r request object
* No shared files like autohandler and dhandler.
* No mod_perl integration or configuration capability.
INSTALLATION
This module should work with any version of Perl 5, without platform
dependencies or additional modules beyond the core distribution.
Retrieve the current distribution from CPAN, or from:
http://www.evoscript.com/Text-MicroMason/
Download and unpack the distribution, and execute the standard "perl
Makefile.PL", "make test", "make install" sequence.
VERSION
This is version 1.05 of Text::MicroMason.
Distribution Summary
The CPAN DSLI entry reads:
Name DSLIP Description
-------------- ----- ---------------------------------------------
Text::
::MicroMason bdpfp Simplified HTML::Mason Templating
This module should be categorized under group 11, Text Processing
(although there's also an argument for placing it 15 Web/HTML, where
HTML::Mason appears).
Discussion and Support
Bug reports or general feedback would be welcomed by the author at
simonm@cavalletto.org.
CHANGES
2003-08-11
Adjusted regular expression based on parsing problems reported by
Philip King and Daniel J. Wright, related to newlines and EOF. Added
regression tests that fail under 1.04 but pass under 1.05 to ensure
these features keep working as expected.
Added non-printing-character escaping to parser failure and
debugging messages to better track future reports of
whitespace-related bugs.
Moved tests from test.pl into t/ subdirectory.
2002-06-23
Adjusted regular expression based on parsing problems reported by
Mark Hampton. Added file-include support with <& ... &> syntax.
Documentation tweaks. Adjusted version number to simpler 0.00
format. Released as Text-MicroMason-1.04.tar.gz.
2002-01-14
Documentation tweaks based on feedback from Pascal Barbedor. Updated
author's contact information.
2001-07-01
Documentation tweaks. Renamed from HTML::MicroMason to
Text::MicroMason. Released as Text-MicroMason-1.0.3.tar.gz.
2001-04-10
Munged interface for clarity. Added Safe support. Adjusted docs to
reflect feedback from mason-users. Released as
HTML-MicroMason-1.0.2.tar.gz.
2001-03-28
Parser tweakage; additional documentation. Added Exporter support.
Released as HTML-MicroMason-1.0.1.tar.gz.
2001-03-26
Added try_interpret; documented error messages.
2001-03-23
Extended documentation; added makefile, test script. Renamed
accumulator to $OUT to match Text::Template. Released as
HTML-MicroMason-1.0.0.tar.gz.
2001-03-22
Created.
TO DO
* Test compatibility against older versions of Perl and odder OS
platforms.
* Perhaps support <%init> ... , by treating it as a %perl
block at the begining of the string.
* Perhaps support <%args> $foo => default .
Perhaps warn if %args block exists but template called with odd
number of arguments.
CREDITS AND COPYRIGHT
Developed By
M. Simon Cavalletto, simonm@cavalletto.org
Evolution Softworks, www.evoscript.org
The Shoulders of Giants
Inspired by Jonathan Swartz's HTML::Mason.
Feedback and Suggestions
Thanks to:
Pascal Barbedor
Mark Hampton
Philip King
Daniel J. Wright
Copyright
Copyright 2002, 2003 Matthew Simon Cavalletto.
Portions copyright 2001 Evolution Online Systems, Inc.
License
You may use, modify, and distribute this software under the same terms
as Perl.