HTML::Mason::Interp - Mason Component Interpreter
my $i = new HTML::Mason::Interp (data_dir=>'/usr/local/mason',
comp_root=>'/usr/local/www/htdocs/',
< other params >);
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.
- 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]) }
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
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'.
- 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. 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 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.
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";
Jonathan Swartz, swartz@transbay.net
HTML::Mason,
HTML::Mason::Parser,
HTML::Mason::ApacheHandler,
HTML::Mason::Admin