=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	

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 Admin/Object files.

=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 default_escape_flags

Escape flags to apply to all <% %> expressions by default. The current
valid flags are

    h - escape for HTML ('<' => '&lt;', etc.)
    u - escape for URL (':' => '%3A', etc.)

The developer can override default escape flags on a per-expression
basis; see Devel/escaping_expressions.

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

If undef, all warnings are heeded; if '.', all warnings 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.

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

=item postamble

A piece of Perl code to insert at the end of every
compiled subroutine. Blank by default. See 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 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 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 Parser/postprocess.

=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 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_make_component">

=item 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
I<script>, or as a filename in I<script_file>.

Returns the new Component object on success, or undef if an error
occurred. I<error> is an optional scalar reference 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 => \my $error)
      or die "error while compiling component: $error";

    # Call it from inside another component
    $m->comp($comp);

=for html <a name="item_make_dirs">

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

I<comp_root> and I<data_dir> contain the Mason component root and data
directory respectively. These are required.

I<paths> is a reference to a list of component paths to make
recursively. By default, makes '/' (the entire component tree).

I<verbose> is a flag indicating whether to report components compiled
and directories created. True by default.

I<predicate> 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 I<predicate> ignores all filenames
ending with "~".

I<dir_create_mode> contains the permissions mode for creating new
directories, by default 0775.

I<update_reload_file> is a flag indicating whether to update a reload
file in the data directory as components 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/mason');

=back

=head1 AUTHOR

Jonathan Swartz, swartz@pobox.com

=head1 SEE ALSO

HTML::Mason,
HTML::Mason::Interp,
HTML::Mason::ApacheHandler,
HTML::Mason::Admin

=cut
