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

If you want to call components outside of mod_perl (e.g. from CGI or a stand-alone Perl script), see the STANDALONE MODE section below.

PARAMETERS FOR new() CONSTRUCTOR

allow_recursive_autohandlers

True or undef, default is undef. If true, autohandlers apply both to their own directories and all subdirectories; if undef, only to their own directories. See the Components/autohandlers section of the Component Developer's Guide for a discussion of the pros and cons.

code_cache_mode

Specifies whether components are cached in memory when they are loaded. This allows you to trade off memory consumption and cache effectiveness. Must be one of 'all', 'request', or 'none'. 'all' means that all components are cached for the lifetime of the process. 'request' means that components are cached for the duration of each HTTP request and then discarded. 'none' means that components are never cached. The default is 'all'. Note that you may preload components (using preloads) regardless of the value of this parameter; preloaded components stick around for the lifetime of the process.

This parameter may be augmented in the future with more sophisticated caching and cache expiration options.

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 is a Perl time() value (seconds since the epoch).

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]) }

By default, out_method prints to standard output. (In a mod_perl environment this is automatically redirected to the HTTP client.)

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 Admin/preloading 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'. Undefined by default; if left undefined, relative path names to mc_file() are prepended with the current component directory.

system_log_file

Absolute path of system log. Default is data_dir/etc/system.log.

system_log_separator

Separator to use between fields on a line in the system log. Default is ctrl-A ("\cA").

system_log_events

A string value indicating one or more events to record in the system log, separated by "|". Default is to log nothing.

use_data_cache

True or undef, default is true. Specifies whether the mc_cache and related commands are operational. You may need to disable data caching temporarily for debugging purposes, but normally this should be left alone.

use_object_files

True or undef, default is true. Specifies whether Mason creates object files to save the results of component parsing. You may want to turn off object files for disk space reasons, but otherwise this should be left alone.

use_reload_file

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

verbose_compile_error

True or undef, default is 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.

ACCESSOR METHODS

All 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 $interp = new HTML::Mason::Interp (...);
    my $p = $interp->parser;
    my $comproot = $interp->comp_root;
    $interp->out_method(\$buf);

The following properties can be queried but should not be modified:

o comp_root, data_dir: these are too integral to the interpreter to reliably change on-the-fly. Better to create multiple interpreters.

o preloads: changing this is ineffective since preloading happens when the interpreter is created

o system_log_file: changing this is ineffective since a persistent log file handle is opened when the interpreter is created

OTHER METHODS

set_global ($varname, [values...])

This method sets a global to be used in components. varname is a variable name, optionally preceded with a prefix ($, @, or %); if the prefix is omitted then $ is assumed. varname is followed by a value, in the case of a scalar, or by one or more values in the case of a list or hash. For example:

    # Set a global variable $dbh containing the database handle
    $interp->set_global(dbh => DBI->connect(...));

    # Set a global hash %session from a local hash
    $interp->set_global('%session', %s);

The global is set in the package that components run in: usually HTML::Mason::Commands, although this can be overridden via the Parser parameter Parser/in_package. The lines above, for example, are equivalent to:

    $HTML::Mason::Commands::dbh = DBI->connect(...);
    %HTML::Mason::Commands::session = %s;

assuming that in_package has not been changed.

Any global that you set should also be registered with the Parser parameter Parser/allow_globals; otherwise you'll get warnings from strict.

STANDALONE MODE

Although Mason is most commonly used in conjunction with mod_perl, there is also a functional API that allows you to use Mason from CGI programs or from stand-alone Perl scripts. In the latter case Mason can be used as a glorified Text::Template, producing a set of files from components, or used to generate a flat version of a componentized site.

When using Mason outside of mod_perl, just create a Parser and Interp object; you do not need the ApacheHandler object. Once you've created an interpreter, the main thing you'll want to do with it is call a component and do something with the output. To call a component, use Interp's exec() method:

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

Component parameters are given as a series of name/value pairs, just as they are with mc_comp. exec returns the return value of the component. Component output is sent to standard output by default, but you can change this by specifying out_method. Here is a skeleton script that calls a component and places the output in a file:

    my $outbuf;
    my $parser = new HTML::Mason::Parser;
    my $interp = new HTML::Mason::Interp (parser=>$parser,
                                          comp_root=>'<component root>',
                                          data_dir=>'<data directory>',
                                          out_method=>\$outbuf);
    my $retval = $interp->exec('<component path>',<args>...);
    open(F,"mason.out");
    print F $outbuf;
    close(F);
    print "return value of component was: $retval\n";

AUTHOR

Jonathan Swartz, swartz@transbay.net

SEE ALSO

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