HTML::Mason::Parser - Mason Component Parser

- NAME
- SYNOPSIS
- DESCRIPTION
- PARAMETERS FOR new() CONSTRUCTOR
- ACCESSOR METHODS
- OTHER METHODS
- AUTHOR
- SEE ALSO

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

  Undefined by default, meaning that all warnings are fatal.

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

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

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