NAME
Blatte - text macro/markup/template language
SYNOPSIS
use Blatte;
use Blatte::Builtins ':all';
my $perl = &Blatte::Parse('...some Blatte program ...');
if (defined($perl)) {
my $result = eval $perl;
if (defined($result)) {
&Blatte::traverse($result, \&callback);
} elsif ($@) {
...handle execution error...
}
} else {
...handle parsing error...
}
DESCRIPTION
Blatte is a very powerful text markup and transformation
language with a very simple syntax. A Blatte document can be
translated into a Perl program that, when executed, produces a
transformed version of the input document.
This module itself contains some utility functions for handling
Blatte documents, described below in the FUNCTIONS section.
However, writers of Blatte-based software will generally be more
interested in other associated modules. See in particular the
Blatte::Compiler manpage (for processing files full of Blatte
code) and the Blatte::Builtins manpage (for a description of the
Blatte language's intrinsic functions).
Most casual end users will probably be interested in Blatte's
ability to serve as a higher-level language for writing web
pages. This requires the additional CPAN package Blatte::HTML.
Most of the remainder of this document describes the syntax and
semantics of the Blatte language.
THE BLATTE LANGUAGE
Blatte has three metacharacters: \ { }. These are used to
represent lists, variables, syntactic forms, function calls,
string literals, comments, and a "forget-whitespace" operator
explained below.
Everything else in a Blatte document is either whitespace or is
divided into "words," also explained below.
To include a literal metacharacter, precede it with backslash:
\\, \{, and \}.
All Blatte expressions correspond to equivalent Perl
expressions. When a Blatte document is parsed, its Blatte
expressions are converted to Perl, which may then be evaluated.
Here is a quick rundown of Blatte expression types.
\VAR
This is a variable reference. The identifier following the \
must begin with a letter, and may be followed by letters,
digits, or underscore.
This corresponds to the Perl scalar variable $var. All
values in Blatte are Perl scalars.
{\define \VAR EXPR}
This defines a new variable \VAR to contain the value of the
Blatte expression EXPR.
This corresponds to the Perl sequence
use vars '$var';
$var = EXPR;
(where EXPR has been transformed to its Perl equivalent).
{\set! \VAR EXPR}
This sets the existing variable \VAR to the value of the
Blatte expression EXPR.
This corresponds to the Perl expression
$VAR = EXPR
{\if TEST THEN ELSE1 ELSE2 ...}
This evaluates TEST. If the result is true, it evaluates and
returns THEN; otherwise it evaluates the ELSEs and returns
the value of the last one.
All Blatte values are true except for 0 and the empty string
(as in Perl) and the empty Blatte list, {} (which
corresponds to the Perl array reference []).
Perl equivalent:
if (TEST) {
THEN;
} else {
ELSE1;
ELSE2;
...
}
{\and EXPR1 EXPR2 ...}
Evaluates each EXPR in turn, stopping if one yields a false
value. Returns the value of the last EXPR it evaluates.
Perl equivalent:
EXPR1 && EXPR2 && ...
{\or EXPR1 EXPR2 ...}
Evaluates each EXPR in turn, stopping if one yields a true
value. Returns the true value if there is one, falsehood
otherwise.
Perl equivalent:
EXPR1 || EXPR2 || ...
{\cond {TEST1 THEN1a THEN1b ...} {TEST2 THEN2a THEN2b ...} ...}
Evaluates each TEST in turn. If one yields a true value,
evaluates the corresponding THENs in sequence and returns
the value of the last one.
Perl equivalent:
if (TEST1) {
THEN1a;
THEN1b;
...
} elsif (TEST2) {
THEN2a;
THEN2b;
...
} ...
{\while TEST EXPR1 EXPR2 ...}
Evaluates TEST. If it's true, evaluates EXPR1 through EXPRn
and starts again.
Perl correspondence:
while (TEST) {
EXPR1;
EXPR2;
...
}
{\lambda {PARAM1 PARAM2 ...} EXPR1 EXPR2 ...}
Creates an anonymous subroutine. When the subroutine is
invoked, its arguments will be assigned to the parameters
PARAM1, PARAM2, etc., and the EXPRs evaluated in the
resulting context. The value will be the value of the last
EXPR.
Each PARAM is one of the following:
\VAR An ordinary variable reference. This creates a *positional
parameter*.
\=VAR This is a *named parameter*.
\&VAR This is a *rest parameter*. There may be at most one of
these.
See below for how to invoke Blatte subroutines, and how
argument parsing proceeds.
Perl equivalent:
sub {
...(argument parsing)...
EXPR1;
EXPR2;
...
}
{\define {\NAME PARAM1 PARAM2 ...} EXPR1 EXPR2 ...}
Defines a subroutine and assigns it to the variable \NAME.
This is shorthand for
{\define \NAME {\lambda {PARAM1 PARAM2 ...} EXPR1 EXPR2 ...}}
{\let {{\VAR1 VAL1} {\VAR2 VAL2} ...} EXPR1 EXPR2 ...}
Evaluates the VALs, then assigns them to the vars, then
evaluates the EXPRs in the resulting context, returning the
value of the last one.
Perl equivalence:
{
my($VAR1, $VAR2, ...) = (VAL1, VAL2, ...);
EXPR1;
EXPR2;
...
}
{\let* {{\VAR1 VAL1} {\VAR2 VAL2} ...} EXPR1 EXPR2 ...}
Like \let, but each VAL is assigned to its \VAR as soon as
it's computed, so later VALs can refer to earlier \VARs.
Perl equivalence:
{
my $VAR1 = VAL1;
my $VAR2 = VAL2;
...
EXPR1;
EXPR2;
...
}
{\letrec {{\VAR1 VAL1} {\VAR2 VAL2} ...} EXPR1 EXPR2 ...}
Like \let and \let*, but evaluates all the VALs in a context
where the VARs have been declared but not yet assigned. This
allows them to refer to one another by reference.
Perl equivalence:
{
my($VAR1, $VAR2, ...);
($VAR1, $VAR2, ...) = (VAL1, VAL2, ...);
EXPR1;
EXPR2;
...
}
{EXPR1 EXPR2 ... EXPRn}
A sequence of one or more expressions enclosed in curly
braces that isn't one of the expression types listed above
is either a function call or a plain list.
If the value of EXPR1 is a Blatte subroutine, it is a
function call, and the values of EXPR2 through EXPRn are
passed as arguments. In this case it corresponds to the
following Perl:
&{EXPR1}({ ...named parameter hash... }, ...other arguments...)
See below for an explanation of Blatte subroutine argument
parsing.
If EXPR1 isn't a Blatte subroutine, then
{EXPR1 EXPR2 ... EXPRn}
is a plain list whose elements are the values of EXPR1
through EXPRn. Blatte lists correspond to Perl array
references:
[EXPR1, EXPR2, ..., EXPRn]
\"...\"
This is a Blatte string. Strings may contain any characters,
including whitespace. \ must be escaped like this: \\. Note,
however, that " is *not* escaped.
WORD
Anything that contains no whitespace, isn't one of the above
expression types, and escapes any instances of Blatte's
three metacharacters, is a word.
In addition to the expression types above, there are two
additional pieces of Blatte syntax:
\; This introduces a comment, which continues to the end of the
line.
\/ This is the "forget-whitespace" operator. It cancels any
whitespace immediately preceding it. See the section on
Whitespace handling below.
Argument parsing for function calls
As mentioned above, Blatte subroutines (a.k.a. functions) have
three kinds of parameters: positional, named, and rest.
When calling a Blatte function, named parameters can be given
values by writing
\NAME=EXPR
where \NAME is the parameter (which was given as \=NAME in the
function definition).
All remaining arguments in the function call are assigned to
positional parameters in the order in which they were declared.
If there aren't enough positional parameters, then all the
remaining arguments are collected in a Blatte list and assigned
to the rest parameter.
When a Blatte function call is translated to Perl, the named
parameter assignments are collected together in an anonymous
HASH reference, which is passed as the first argument to the
Perl subroutine corresponding to the Blatte function. (All
Blatte functions are Perl subroutines that accept this anonymous
HASH reference of named parameters as a first argument.) All
remaining Blatte arguments are passed in sequence to the Perl
subroutine.
Inside the Perl subroutine, arguments are unpacked as follows:
named parameters are extracted from the HASH reference and
assigned to correspondingly named Perl variables; Perl variables
for the positional parameters get the next N arguments from @_;
and the remainder of @_ is turned into an ARRAY reference (a
Blatte list) and assigned to the Perl variable denoting the rest
parameter.
Example:
{\define {\fn \=n1 \=n2 \a \b \&r}
...do stuff...}
becomes:
$fn = sub {
my($_named, $a, $b) = splice(@_, 0, 3);
my $n1 = $_named->{n1};
my $n2 = $_named->{n2};
my $r = \@_;
...do stuff...
};
and the function call
{\fn \n2=17 This is an example.}
becomes:
&$fn({n2 => 17}, 'This', 'is', 'an', 'example.')
which means $n1 will be undef, $n2 will be 17, $a will be
'This', $b will be 'is', and $r will be ['an', 'example'].
(Almost. This example ignores Blatte's whitespace handling,
which is explained below.)
Whitespace handling
Before recognizing a Blatte expression, the Blatte parser skips
over a (possibly empty) sequence of whitespace. This whitespace
is preserved; then, when the parser is finished, the result is
wrapped in a Blatte::Ws object, or a "whitespace wrapper,"
containing the preserved whitespace and the parsed expression.
In this way, the whitespace preceding each expression is carried
along with the expression itself. When Blatte expressions are
parsed, evaluated, and rendered normally (see flatten() below),
the output preserves the same whitespace found in the input.
FUNCTIONS
Parse(INPUT)
Parses the first Blatte expression in INPUT using the
default parser. The result is converted to a string of Perl
code and returned.
(If you don't use the default parser, it's possible to
change Blatte's syntax, to obtain the intermediate parse
tree before conversion to Perl, and more. See the
Blatte::Parser(3) manpage.)
INPUT is either a string containing Blatte code, or a
reference to such a string. If it's a reference, then after
a successful parse, the matched expression will be removed
from the beginning of the referenced string.
traverse(OBJ, CALLBACK, [WS])
Walks the data structure OBJ. If OBJ is an ARRAY reference,
its elements are recursively traversed. If OBJ is a
whitespace wrapper, its contents are recursively traversed.
Otherwise, CALLBACK (a Perl CODE reference) is invoked on WS
and OBJ. WS is a string of whitespace, possibly empty.
CALLBACK should return truth if it uses its whitespace
argument and falsehood if it doesn't (meaning that
traverse() should reuse the whitespace value in subsequent
calls, if necessary). "Uses" usually means that the
whitespace is copied to some sort of output.
This function supplies the logic that causes outer
whitespace wrappers to take precedence over inner ones.
flatten(OBJ, [WS])
Renders OBJ as a string, with optional leading whitespace WS
(which takes precedence over any outermost whitespace
wrapper that might be present).
This function is written in terms of traverse().
wrapws(WS, OBJ)
Creates a new whitespace wrapper whose whitespace string is
WS and whose nested object is OBJ.
unwrapws(OBJ)
Unwraps as many layers of whitespace wrapper from OBJ as
necessary to reach a non-wrapper object, then returns that.
wsof(OBJ)
This returns the whitespace string, possibly empty,
associated with OBJ. Note that
wsof(wrapws(X, Y))
is always X, however
unwrapws(wrapws(X, Y))
is Y only when Y is not itself a whitespace wrapper.
true(OBJ)
Returns the Blatte truth value of OBJ (after whitespace-
unwrapping, see above). As in Perl, 0 and the empty string
are false, but so is an empty Blatte list (that is, a Perl
ARRAY ref with zero elements); all other values are true.
quote(STRING)
Quote STRING using Blatte syntax so that it can be read back
as a Blatte string literal.
PEDIGREE
Blatte is a successor to an earlier language called Latte. The B
is for "better" -- better because, whereas Latte's runtime
facilities were fairly limited, Blatte's are effectively
unlimited, since Blatte has the full power of Perl at its
disposal. The implementation is also much faster and simpler
than that of Latte. Latte users should beware that, despite
being substantially similar, the Blatte language has
siginificant differences from Latte.
The design of the Blatte language was strongly influenced by
Scheme, and was guided by these principles:
* The syntax should be simple, terse, and unobtrusive.
* There should be as few metacharacters as possible (contrast
TeX), so as to have minimum impact on mostly textual Blatte
documents.
* The language should be fully general, not a half-hearted macro
system that makes many computations impossible.
* The correspondence between the source language (Blatte) and the
target language (Perl) should be simple and direct.
DEDICATION
Blatte is dedicated to the memory of Julie Epelboim, 1964-2001.
Not that she ever would have used it. This was a woman who
preferred to write *raw Postscript code* rather than use a page
layout program. The tragedy of having lost her is dwarfed by the
good fortune of having known her.
SEE ALSO
the Blatte::Compiler(3) manpage, the Blatte::Builtins(3)
manpage, the Blatte::Parser(3) manpage, the Blatte::Ws(3)
manpage.