interp(3)

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 true as of verison 0.85. If
true, autohandlers apply both to their own directories
and all subdirectories; if undef, only to their own
directories. See the Devel/autohandlers section of the
Component Developer's Guide for a discussion of the
pros and cons.
autohandler_name: File name used for autohandlers. Default is "autohan
dler". If undef, Mason will not look for autohandlers.
code_cache_max_size: Specifies the maximum size, in bytes, of the in-memory
code cache where components are stored. e.g.

code_cache_max_size => 20*1024*1024
code_cache_max_size => 20_000_000; Default is 10 MB. See the Admin/Code Cache section of
the Admin Guide for further details.
comp_root: The required Mason component root. All components live
under the comp_root.; You may also specify multiple component roots to be
searched in the spirit of Perl's @INC. To do so you
must specify a list of lists:

comp_root => [[key1, root1], [key2, root2], ...]; Each pair consists of a key and root. The key is a
string that identifies the root mnemonically to a com
ponent developer. Data cache and object directories
are split up by these keys to make sure different com
ponents sharing the same path have different cache and
object files. The key is also included whenever Mason
prints the component title, as in an error message.; For example:

comp_root => [['private', '/usr/home/joe/comps'],

['main', '/usr/local/www/htdocs']]; This specifies two component roots, a main component
tree and a private tree which overrides certain compo
nents. The order is respected ala @INC, so 'private'
is searched first and 'main' second.
current_time: Overrides the time returned by $m->time with a fixed
Perl time() value (seconds since the epoch). On timesensitive sites, this can be used to set up port-based
time/date simulations, e.g. a port that looks one day
into the future.; With no current_time parameter (the default), $m->time
reports the true time.
data_dir: The required Mason data directory. Mason's various
data directories (obj, cache, debug, etc), live within
the data_dir.
data_cache_dir: Specifies an absolute directory for data cache files.
By default, it lives under "data_dir"/cache.
dhandler_name: File name used for dhandlers. Default is "dhandler".
If undef, Mason will not look for dhandlers.
max_recurse: The maximum component stack depth the interpreter is
allowed to descend before signalling an error.
Default is 32.
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 redi
rected to the HTTP client.)
out_mode: Specifies one of two ways to send output, 'batch' or
'stream'. In batch mode Mason computes the entire
page in a memory buffer and then transmits it all at
once. In stream mode Mason outputs data as soon as it
is computed. (This does not take into account buffer
ing done by Apache or the O/S.) The default mode is
batch. See the Admin/staging vs production section of
the Admin Guide for a discussion of the trade-offs.
parser: Parser object for compiling components on the fly. If
omitted, creates a parser with default parameters.
preloads: A list of component paths, optionally with glob wild
cards, to load when the interpreter initializes. e.g.

preloads => ['/foo/index.html','/bar/*.pl']; Default is the empty list. 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 "$m->file()". Does not require a trailing slash.
For example, if the file root is '/foo/bar', then
"$m->file('baz/bap')" will read the file
'/foo/bar/baz/bap'. Undefined by default; if left
undefined, relative path names to "$m->file()" are
prepended with the current component directory.
system_log_events: A string value indicating one or more events to record
in the system log, separated by "|". Default is to log
nothing.
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 sys
tem log. Default is ctrl-A ("
use_data_cache: True or undef, default is true. Specifies whether the
$m->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 com
ponent 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 inter
pret the error message. Does not affect runtime
errors.

ACCESSOR METHODS

All of the above properties have standard accessor methods of the same name. In general, no arguments retrieves the value, and one argument sets and returns the value. For example:: my $interp = new HTML::Mason::Interp (...);
my $p = $interp->parser;
my $comproot = $interp->comp_root;
$interp->out_method(uf);
The following properties can be queried but not modified: comp_root, data_dir, system_log_file, system_log_separa tor, preloads.

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_pack
age. 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 glori
fied Text::Template, producing a set of files from compo
nents, or used to generate a flat version of a componen
tized 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(<comp> [,<..list of component; params..>]);
where comp is a component path or component object.
Component parameters are given as a series of name/value pairs, just as they are with "$m->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=>'<com

ponent root>',
data_dir=>'<data

directory>',
out_method=>ut

buf);; my $retval = $interp->exec('<component; path>',<args>...);
open(F,">mason.out");
print F $outbuf;
close(F);
print "return value of component was: $retval0;

AUTHOR

Jonathan Swartz, swartz@pobox.com

docs.sk

comprehensive documentation repository

Most Viewed