NAME

HTML::Mason::Interp - Mason Component Interpreter

SYNOPSIS

    my $i = new HTML::Mason::Interp (data_dir=>'/usr/local/mason',
                                     comp_root=>'/usr/local/www/htdocs/',
                                     < other params >);

DESCRIPTION

Interp is the Mason workhorse, executing components and routing their output and errors to all the right places. In a web environment, Interp objects are handed off immediately to an ApacheHandler object which internally calls the Interp implementation methods. In that case the only user method is the new() constructor.

The special case of Mason running in standalone mode (in which case you interact with an Interp directly) is described in a separate section below.

PARAMETERS FOR new() CONSTRUCTOR

comp_root

A required argument, this specifies the root of your component source tree.

current_time

Overrides the time and date returned by mc_time and mc_date with a fixed value. This is useful for testing time-based components, e.g. seeing what a page will look like tomorrow. The argument may be specified as a time() value (seconds since 1/1/70) or as a Date::Manip date string. For example:

    current_time => 891963000              # simulate 4/7/1998 at 8:30 AM
    current_time => 'Apr 7, 1998 8:30 AM'  # same
    current_time => 'tomorrow'             # simulate tomorrow at midnight

With no current_time parameter (the default), mc_time and mc_date report the true time.

data_dir

The other required argument. Mason's various data directories (obj, cache, debug, etc), live within the data_dir.

max_recurse

The maximum component stack depth the interpreter is allowed to descend before signalling an error. Default is 16.

out_method

Indicates where to send output. If out_method is a reference to a scalar, output is appended to the scalar. If out_method is a reference to a subroutine, the subroutine is called with each output string. For example, to send output to a file called "mason.out":

    my $fh = new IO::File ">mason.out";
    ...
    out_method => sub { $fh->print($_[0]) }

In standalone mode, out_method prints to standard output. In a web environment, out_method defaults to using $r-print>.

parser

Parser object for compiling components on the fly. If omitted, creates a parser with default parameters.

preloads

A set of component paths and/or component directories to load when the interpreter initializes. This should only be used for components that are frequently viewed and rarely updated. See the "preloading" in Admin section of the Admin Guide for further details.

static_file_root

Absolute path to prepend to relative filenames passed to mc_file(). Does not require a trailing slash. For example, if the file root is '/foo/bar', then mc_file('baz/bap') will read the file '/foo/bar/baz/bap'.

use_data_cache

True or undef, default is true. You may need to disable data caching temporarily for debugging purposes, but normally this should be left alone.

use_reload_file

True or undef, default undef. If true, disables Mason's automatic timestamp checking on component source files, relying instead on an explicitly updated "reload file" in Admin.

verbose_compile_error

True or undef, default undef. If true, component compile errors are followed with the full component source, annotated with line numbers, to better interpret the error message. Does not affect runtime errors.

STANDALONE MODE

In a web environment, Interp objects don't stand by themselves. Instead each is kept as an ApacheHandler property, which internally invokes the Interp as needed.

You can call components outside a web environment by using Interp's exec() method:

        $i->exec(compPath [,<..list of component params..>]);

Component parameters are given as a series of name/value pairs, just as they are with mc_comp().

AUTHOR

Jonathan Swartz, swartz@transbay.net

SEE ALSO

HTML::Mason, HTML::Mason::Parser, HTML::Mason::ApacheHandler, HTML::Mason::Admin