HTML::Mason::Parser - Mason Component Parser

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

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.

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.

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.

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.

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.

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_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 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);

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 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 $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');

AUTHOR

Jonathan Swartz, swartz@pobox.com