<HTML>
<HEAD>
<TITLE>HTML::Mason::Parser - Mason Component Parser
</TITLE>
</HEAD>
<BODY>
<!-- INDEX BEGIN -->
<UL>
<LI><A HREF="#name">NAME</A>
<LI><A HREF="#synopsis">SYNOPSIS</A>
<LI><A HREF="#description">DESCRIPTION</A>
<LI><A HREF="#parameters_for_new_constructor">PARAMETERS FOR new() CONSTRUCTOR </A>
<LI><A HREF="#accessor_methods">ACCESSOR METHODS</A>
<LI><A HREF="#other_methods">OTHER METHODS</A>
<LI><A HREF="#author">AUTHOR</A>
<LI><A HREF="#see_also">SEE ALSO</A>
</UL>
<!-- INDEX END -->
<HR>
<P>
<H1><A NAME="name">NAME
</A></H1>
HTML::Mason::Parser - Mason Component Parser
<P>
<P>
<HR>
<H1><A NAME="synopsis">SYNOPSIS
</A></H1>
<PRE> my $p = new HTML::Mason::Parser (...params...);
</PRE>
<P>
<P>
<HR>
<H1><A NAME="description">DESCRIPTION
</A></H1>
A Parser object translates components into Perl subroutines. Parsers are
typically embedded within (and used by) Interp objects.
<P>
<P>
<HR>
<H1><A NAME="parameters_for_new_constructor">PARAMETERS FOR new() CONSTRUCTOR
</A></H1>
These parameters affect the way that components are translated 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 <A HREF="././Admin.html#object_files">Object files</A>.
<P>
<DL>
<DT><STRONG><A NAME="item_allow_globals">allow_globals
</A></STRONG><DD>
List of variable names, complete with prefix (<CODE>$@%</CODE>), that you intend to use as globals in components. Normally global
variables are forbidden by <CODE>strict</CODE>, but any variable mentioned in this list is granted a reprieve via a ``use
vars'' statement. For example:
<P>
<PRE> allow_globals => [qw($DBH %session)]
</PRE>
<P>
In a mod_perl environment, <CODE>$r</CODE> (the request object) is automatically added to this list.
<P>
<DT><STRONG><A NAME="item_default_escape_flags">default_escape_flags
</A></STRONG><DD>
Escape flags to apply to all <% %> expressions by default. The
current valid flags are
<P>
<PRE> h - escape for HTML ('<' => '&lt;', etc.)
u - escape for URL (':' => '%3A', etc.)
</PRE>
<P>
The developer can override default escape flags on a per-expression basis;
see <A HREF="././Devel.html#escaping_expressions">escaping_expressions</A>.
<P>
<DT><STRONG><A NAME="item_ignore_warnings_expr">ignore_warnings_expr
</A></STRONG><DD>
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:
<P>
<PRE> ignore_warnings_expr =>
'Global symbol.*requires explicit package'
</PRE>
<P>
If undef, all warnings are heeded; if '.', all warnings are ignored.
<P>
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.
<P>
<DT><STRONG><A NAME="item_in_package">in_package
</A></STRONG><DD>
Indicates the name of the package you wish your components to run in. This
way different applications or virtual hosts can be run in different name
spaces. Default is <CODE>HTML::Mason::Commands</CODE>.
<P>
<DT><STRONG><A NAME="item_postamble">postamble
</A></STRONG><DD>
A piece of Perl code to insert at the end of every compiled subroutine.
Blank by default. See <A HREF="./Parser.html#item_preamble">preamble</A>.
<P>
<DT><STRONG><A NAME="item_postprocess">postprocess
</A></STRONG><DD>
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.
<P>
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 <A HREF="./Parser.html#item_preprocess">preprocess</A>.
<P>
<DT><STRONG><A NAME="item_preamble">preamble
</A></STRONG><DD>
A piece of Perl code to insert at the beginning of every compiled
subroutine. Blank by default, but ApacheHandler adds the line
<P>
<PRE> use vars qw($r);
</PRE>
<P>
to suppress strict warnings about uses of global <CODE>$r</CODE> (the
Apache request object). See <A HREF="./Parser.html#item_postamble">postamble</A>.
<P>
<DT><STRONG><A NAME="item_preprocess">preprocess
</A></STRONG><DD>
Sub reference that is called to preprocess each component 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
in-place. This is one way to extend the HTML::Mason syntax with new tags,
etc. See <A HREF="./Parser.html#item_postprocess">postprocess</A>.
<P>
<DT><STRONG><A NAME="item_taint_check">taint_check
</A></STRONG><DD>
This flag allows Mason to work when taint checking is on (e.g.
PerlTaintCheck or <CODE>-T</CODE> 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.
<P>
<DT><STRONG><A NAME="item_use_strict">use_strict
</A></STRONG><DD>
Indicates whether to use strict in compiled subroutines. Default is true.
<P>
</DL>
<P>
<HR>
<H1><A NAME="accessor_methods">ACCESSOR METHODS
</A></H1>
Most of the above properties have standard accessor methods of the same
name: no arguments retrieves the value, and one argument sets it. For
example:
<P>
<PRE> my $parser = new HTML::Mason::Parser;
my $strictmode = $parser->use_strict;
$parser->use_strict(1);
</PRE>
<P>
The only exception is <A HREF="./Parser.html#item_allow_globals">allow_globals</A>, which works a bit differently.
<P>
<P>
<HR>
<H1><A NAME="other_methods">OTHER METHODS
</A></H1>
<DL>
<DT><STRONG><A NAME="item_allow_globals_varnames_">allow_globals (varnames)
</A></STRONG><DD>
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.
<P>
<a name="item_make_component">
<DT><STRONG><A NAME="item_make_component_script_sc">make_component ([script=>..., script_file=>..., error=>...])
</A></STRONG><DD>
This method compiles a component source script into an Component object.
The source may be passed in as a string in
<EM>script</EM>, or as a filename in <EM>script_file</EM>.
<P>
Returns the new Component object on success, or undef if an error occurred. <EM>error</EM> is an optional scalar reference filled with the error message.
<P>
Example of usage:
<P>
<PRE> # Make a component
my $comp = $parser->make_component
(script=>'<%perl>my $name = "World";</%perl>Hello <% $name %>!',
error => \my $error)
or die "error while compiling component: $error";
</PRE>
<P>
<PRE> # Call it from inside another component
$m->comp($comp);
</PRE>
<P>
<a name="item_make_dirs">
<DT><STRONG><A NAME="item_make_dirs_comp_root_data_">make_dirs (comp_root=>..., data_dir=>..., [paths=>[...],
verbose=>0|1, predicate=>sub {...}, dir_create_mode=>...,
update_reload_file=>0|1])
</A></STRONG><DD>
make_dirs traverses a tree of components, compiles any out-of-date
components into object files, and reports errors.
<P>
<EM>comp_root</EM> and <EM>data_dir</EM> contain the Mason component root and data directory respectively. These are
required.
<P>
<EM>paths</EM> is a reference to a list of component paths to make recursively. By
default, makes '/' (the entire component tree).
<P>
<EM>verbose</EM> is a flag indicating whether to report components compiled and directories
created. True by default.
<P>
<EM>predicate</EM> is a subroutine that takes one argument, the component source file, and
returns true or false indicating whether or not to try to compile it. By
default <EM>predicate</EM> ignores all filenames ending with ``~''.
<P>
<EM>dir_create_mode</EM> contains the permissions mode for creating new directories, by default
0775.
<P>
<EM>update_reload_file</EM> is a flag indicating whether to update a reload file in the data directory
as components are recompiled. False by default.
<P>
Example of usage:
<P>
<PRE> #!/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/mason');
</PRE>
<P>
</DL>
<P>
<HR>
<H1><A NAME="author">AUTHOR
</A></H1>
Jonathan Swartz, <A HREF="MAILTO:swartz@pobox.com">swartz@pobox.com</A>
<P>
<P>
<HR>
<H1><A NAME="see_also">SEE ALSO
</A></H1>
<A HREF="././Mason.html#">HTML::Mason</A>,
<A HREF="././Interp.html#">HTML::Mason::Interp</A>,
<A HREF="././ApacheHandler.html#">HTML::Mason::ApacheHandler</A>,
<A HREF="././Admin.html#">HTML::Mason::Admin</A>
<P>
</DL>
</BODY>
</HTML>