parser(3)

NAME

HTML::Mason::Parser - Mason Component Parser

SYNOPSIS

my $p = new HTML::Mason::Parser (...params...);

DESCRIPTION

A Parser object translates components into Perl subrou
tines. Parsers are typically embedded within (and used by)
Interp objects.

PARAMETERS FOR new() CONSTRUCTOR

These parameters affect the way that components are trans
lated into Perl code. If you change a Parser's options,
you must remove any previously created object files for
the changes to take effect. See also Admin/Object files.

allow_globals: List of variable names, complete with prefix ("$@%"),
that you intend to use as globals in components. Nor
mally global variables are forbidden by "strict", but
any variable mentioned in this list is granted a
reprieve via a "use vars" statement. For example:

allow_globals => [qw($DBH %session)]; In a mod_perl environment, "$r" (the request object)
is automatically added to this list.
default_escape_flags: Escape flags to apply to all <% %> expressions by
default. The current valid flags are

h - escape for HTML ('<' => '<', etc.)
u - escape for URL (':' => '%3A', etc.); The developer can override default escape flags on a
per-expression basis; see Devel/escaping_expressions.
ignore_warnings_expr: Regular expression indicating which warnings to ignore
when compiling subroutines. Any warning that is not
ignored will prevent the component from being compiled
and executed. For example:

ignore_warnings_expr =>
'Global symbol.*requires explicit package'
If undef, all warnings are heeded; if '.', all warn ings are ignored.
By default, this is set to 'Subroutine .* redefined'. This allows you to declare global subroutines inside <%once> sections and not receive an error when the component is reloaded.
in_package: Indicates the name of the package you wish your compo
nents to run in. This way different applications or
virtual hosts can be run in different name spaces.
Default is "HTML::Mason::Commands".
postamble: A piece of Perl code to insert at the end of every
compiled subroutine. Blank by default. See
Parser/preamble.
postprocess: Sub reference that is called to postprocess the code
and text portions of a compiled component, just before
it is assembled into its final subroutine form. The
sub is called with two parameters, a scalar reference
to the script and a string containing either "perl" or
"alpha" depending on whether the string is code or
text respectively. The sub is expected to process the
string in-place. It will be called multiple times,
once for each piece of code and text.; This is the ideal place to translate accents into HTML
entities. It could also be used to strip out comments
that you have in your HTML files that you don't want
the end user to see. See Parser/preprocess.
preamble: A piece of Perl code to insert at the beginning of
every compiled subroutine. Blank by default, but
ApacheHandler adds the line

use vars qw($r);; to suppress strict warnings about uses of global $r
(the Apache request object). See Parser/postamble.
preprocess: Sub reference that is called to preprocess each compo
nent before Parser does it's magic. The sub is called
with a single parameter, a scalar reference to the
script. The sub is expected to process the script inplace. This is one way to extend the HTML::Mason
syntax with new tags, etc. See Parser/postprocess.
taint_check: This flag allows Mason to work when taint checking is
on (e.g. PerlTaintCheck or "-T" flag). If true, Mason
will pass all component source and filenames through a
dummy regular expression match to untaint them. In the
future this option may become more sophisticated to
allow stricter checks. Default is false.
use_strict: Indicates whether to use strict in compiled subrou
tines. Default is true.

ACCESSOR METHODS

Most of the above properties have standard accessor meth ods of the same name: no arguments retrieves the value, and one argument sets it. For example:: my $parser = new HTML::Mason::Parser;
my $strictmode = $parser->use_strict;
$parser->use_strict(1);
The only exception is Parser/allow_globals, which works a bit differently.

OTHER METHODS

allow_globals (varnames): Called with no arguments, this returns the value of
allow_globals as a list. Called with one or more
variable names, it appends the names to the existing
list, removing duplicates if any.
make_component ([script=>..., script_file=>..., error=>...]): This method compiles a component source script into an
Component object. The source may be passed in as a
string in script, or as a filename in script_file.; Returns the new Component object on success, or undef
if an error occurred. error is an optional scalar ref
erence filled with the error message.; Example of usage:

# Make a component
my $comp = $parser->make_component
(script=>'<%perl>my $name =

"World";</%perl>Hello <% $name %>!',
error => $error)

or die "error while compiling component: $er

ror";

# Call it from inside another component
$m->comp($comp);
make_dirs (comp_root=>..., data_dir=>..., [paths=>[...], verbose=>0|1, predicate=>sub {...}, dir_create_mode=>..., update_reload_file=>0|1]): make_dirs traverses a tree of components, compiles any
out-of-date components into object files, and reports
errors.; comp_root and data_dir contain the Mason component root and data directory respectively. These are
required.; paths is a reference to a list of component paths to
make recursively. By default, makes '/' (the entire
component tree).; verbose is a flag indicating whether to report compo nents compiled and directories created. True by
default.; predicate is a subroutine that takes one argument, the component source file, and returns true or false indi
cating whether or not to try to compile it. By
default predicate ignores all filenames ending with "~".; dir_create_mode contains the permissions mode for cre ating new directories, by default 0775.; update_reload_file is a flag indicating whether to update a reload file in the data directory as compo
nents are recompiled. False by default.; Example of usage:

#!/usr/bin/perl
use HTML::Mason;
use HTML::Mason::ApacheHandler; # load explicitly

to bring in special $m-> commands

my $p = new HTML::Mason::Parser;
$p->allow_globals(qw($r)); # allow Apache $r

global
$p->make_dirs

(comp_root=>'/usr/home/swartz/web/comps',
data_dir=>'/usr/home/swartz/web/ma

son');

AUTHOR

Jonathan Swartz, swartz@pobox.com

docs.sk

comprehensive documentation repository

Most Viewed