|
HTML::Mason::Interp - Mason Component Interpreter |
new() CONSTRUCTOR
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.
new() CONSTRUCTOR
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.
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 component developer. Data cache and object directories are split up by these keys to make sure different components 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 components. The order is respected ala @INC, so 'private' is searched first and 'main' second.
time() value
(seconds since the epoch). On time-sensitive 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/cache.
If this parameter is false, then $SIG{__DIE__} will not be overridden at all. Defaults to:
sub { Carp::confess($_[0]) }
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.)
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.
$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.
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(\$buf);
The following properties can be queried but not modified: comp_root, data_dir, system_log_file, system_log_separator, preloads.
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.
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(<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=>'<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@pobox.com
HTML::Mason, HTML::Mason::Parser, HTML::Mason::ApacheHandler, HTML::Mason::Admin
|
HTML::Mason::Interp - Mason Component Interpreter |