=head1 NAME

HTML::Mason::Parser - Mason Component Parser

=head1 SYNOPSIS

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

=head1 DESCRIPTION

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

=head1 PARAMETERS FOR new() CONSTRUCTOR	

=over

=item allow_globals

List of variable names, complete with prefix (C<$@%>), that you intend
to use as globals in components.  Normally global variables are
forbidden by C<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, C<$r> (the request object) is automatically
added to this list.

=item 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'

Undefined by default, meaning that all warnings are fatal. 

=item in_package

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 C<HTML::Mason::Commands>.

You will have to explicitly import the mc_* commands from C<HTML::Mason::Commands>
into your package. Ideally you will put this in your C<handler.pl>:

    { package MyPackage;
    use HTML::Mason::Commands; }

This will bring in all of the mc_ commands. If you want to save some
space on imported symbols, specify just the commands you want:

    { package MyPackage;
    use HTML::Mason::Commands qw(mc_comp mc_file mc_cache); }

=item postamble

A piece of Perl code to insert at the end of every
compiled subroutine. Blank by default. See L<Parser/preamble>.

=item 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 L<Parser/preprocess>.

=item 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 L<Parser/postamble>.

=item preprocess

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 L<Parser/postprocess>.

=item source_refer_predicate

Reference to a subroutine that decides whether a given component
should be compiled with L<Admin/source references>. The subroutine
takes two arguments: first, the total number of characters in the
component source; second, the number of characters devoted to plain
text. For example, this component:

	% my $noun = "World";
	Hello, <% $noun %>!
	How are ya?

Has 51 total bytes, 19 of which are plain text. This allows you to
adjust the trade-off between the memory savings of source references
and the performance advantage of in-line plain text. For example, to
choose only components with at least 50% plain text:

    source_refer_predicate =>
        sub { return $_[1] / $_[0] >= 0.5 }

The current default is

    sub { return $_[1] >= 500 }

i.e. any component with at least 500 characters. This is an
experimental setting and may change.

=item taint_check

This flag allows Mason to work when taint checking is on
(e.g. PerlTaintCheck or C<-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.

=item use_strict

Indicates whether to use strict in compiled subroutines.
Default is true.

=back

=head1 ACCESSOR METHODS

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:

    my $parser = new HTML::Mason::Parser;
    my $strictmode = $parser->use_strict;
    $parser->use_strict(1);

The only exception is L<Parser/allow_globals>, which works a bit differently.

=head1 OTHER METHODS

=over

=item 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.

=for html <a name="item_parse">

=item parse ([$script, $script_file, \$result_code, \$result_text, \$pure_text_flag, \$error, $wrap_errors, $save_to])

This method performs the main function of Parser: it compiles a
component into a Perl subroutine.

The component may be passed in as a string in I<script>, or as a
filename in I<script_file>.

The subroutine can be output in three ways. I<result_text> is an
optional scalar reference; if specified, it is filled with a Perl
script that, when evaluated, returns the new
subroutine. I<result_code> is an optional code reference filled with
the new subroutine itself.  I<save_to> is an optional filename for an
object file.

The method returns 1 on success and 0 if there was an error.  I<error>
is an optional scalar reference filled with any parsing or compilation
errors that occur.  Alternatively, if the I<wrap_errors> flag is set
to true, then any errors that occur are simply wrapped up to be
displayed by the subroutine -- in this case the method always
"succeeds" and returns 1.

I<pure_text_flag> is an optional scalar reference filled with a flag
indicating whether the component was pure text (free of Mason syntax).

Here's an example that creates an object file from a component source
file:

    $parser->parse(script_file => '/usr/www/docs/template',
                    save_to => '/usr/www/data/obj/template',
                    error => \$error)
         or die "error while compiling component: $error";

=back

=head1 AUTHOR

Jonathan Swartz, swartz@transbay.net

=head1 SEE ALSO

L<HTML::Mason>,
L<HTML::Mason::Interp>,
L<HTML::Mason::ApacheHandler>,
L<HTML::Mason::Admin>

=cut
