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.
new()
CONSTRUCTORcode_cache_max_size => 20*1024*1024 code_cache_max_size => 20_000_000
Default is 10 MB. See the Code Cache section in the Admin Guide for further details.
HTML::Mason::Compiler::ToObject
and HTML::Mason::Lexer
classes
will be created.
If this parameter is not given then there are several results. First, Mason will not use object files, since it has no place to put them. Second, the default caching class for the request object will be Cache::MemoryCache instead of Cache::FileCache.
$m->cache
command. For example, to use the Cache::MemoryCache implementation
by default,
data_cache_defaults => {cache_class => 'MemoryCache'}
These settings are overriden by options given to particular
$m->cache
calls.
When true, Mason assumes that the component source tree is unchanging: it will not check component source files to determine if the memory cache or object file has expired. This can save many file stats per request. However, in order to get Mason to recognize a component source change, you must remove object files and restart the server (so as to clear the memory cache).
Use this feature for live sites where performance is crucial and where updates are infrequent and well-controlled.
ignore_warnings_expr => 'Global symbol.*requires explicit package'
If undef, all warnings are heeded; if '.', all warnings are ignored.
By default, this is set to 'Subroutine .* redefined'. This allows you to declare global subroutines inside <%once> sections and not receive an error when the component is reloaded.
preloads => ['/foo/index.html','/bar/*.pl']
Default is the empty list. For maximum performance, this should only be used for components that are frequently viewed and rarely updated. See the preloading section in the Admin Guide for further details.
As mentioned in the developer's guide, a component's <%once>
section is executed when it is loaded. For preloaded components, this
means that this section will be executed before a Mason or Apache
request exist, so preloading a component that uses $m
or $r
in a
<%once>
section will fail.
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 $c = $interp->compiler; $interp->dhandler_name("da-handler");
The following properties can be queried but not modified: data_dir, 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
Compiler's in_package parameter.
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
Compiler's allow_globals
parameter; otherwise you'll get warnings from strict
.
comp_source
,
or as a filename in comp_file
. When using comp_file
, the
filename is specified as a path on the file system, not as a path
relative to Mason's component root (see
Request->fetch_comp for that).
If Mason encounters an error during processing, an exception will be thrown.
Example of usage:
# Make an anonymous component my $anon_comp = eval { $interp->make_component ( comp_source => '<%perl>my $name = "World";</%perl>Hello <% $name %>!' ) }; die $@ if $@;
$m->comp($anon_comp);
path
, or undef if none exists.
comp_root
method in the resolver object. Obviously, if you are using a custom
resolver class which does not have a comp_root
method, then this
convenience method will not work.