NAME

HTML::Mason::Parser - Mason Component Parser

SYNOPSIS

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

DESCRIPTION

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

PARAMETERS FOR new() CONSTRUCTOR

allow_globals

List of variable names, complete with prefix ($@%), that you intend to use as globals in components. Normally 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.

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.

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

You will have to explicitly import the mc_* commands from HTML::Mason::Commands into your package. Ideally you will put this in your 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); }

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

source_refer_predicate

Reference to a subroutine that decides whether a given component should be compiled with 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.

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 subroutines. Default is true.

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.

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 ($comp_root, $data_dir, [@paths, $verbose, $predicate, $dir_create_mode, $update_reload_file])

make traverses a tree of components, compiles any out-of-date components into object files, and reports errors. All parameters listed above are passed as name/value pairs; the first two are required.

$comp_root and $data_dir contain the Mason component root and data directory respectively.

@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 components compiled and directories created. True by default.

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

$dir_create_mode contains the permissions mode for creating new directories, by default 0775.

$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 mc_ commands
    
    my $p = new HTML::Mason::Parser;
    $p->allow_globals(qw($r));       # allow Apache $r global
    $p->make (comp_root=>'/usr/home/swartz/web/comps',
              data_dir=>'/usr/home/swartz/web/mason');

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

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

The method returns 1 on success and 0 if there was an error. error is an optional scalar reference filled with any parsing or compilation errors that occur. Alternatively, if the 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.

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";

AUTHOR

Jonathan Swartz, swartz@transbay.net

SEE ALSO

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