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.
new()
CONSTRUCTORUnder Apache, data_dir defaults to a directory called ``mason'' under the Apache server root. You will need to change this on certain systems that assign a high-level server root such as /usr!
In non-Apache environments, data_dir has no default. If it is left
unspecified, Mason will not use object files, and the default
data cache class will be
MemoryCache
instead of FileCache
.
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 components section of the administrator's manual for further details.
As mentioned in the developer's manual, 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.
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.
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->code_cache_max_size(20 * 1024 * 1024);
The following properties can be queried but not modified: data_dir, preloads.
\w
and the dash (-). It must start with an
alpha character or an underscore (_).
The right hand side may be one of several things. It can be a
subroutine reference. It can also be a string match /^\w+$/
, in
which case it is assumed to be the name of a subroutine in the
HTML::Mason::Escapes
module. Finally, if it is a string that does
not match the above regex, then it is assumed to be eval
able code,
which will return a subroutine reference.
When setting these with PerlSetVar
directives in an Apache
configuration file, you can set them like this:
PerlSetVar MasonEscapeFlags "flag => \&subroutine" PerlSetVar MasonEscapeFlags "uc => sub { ${$_[0]} = uc ${$_[0]}; }" PerlAddVar MasonEscapeFlags "thing => other_thing"
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.
This is useful for running Mason outside of a web environment. See using Mason from a standalone script in the HTML::Mason::Admin manpage for examples.
This method isn't generally useful in a mod_perl environment; see subrequests instead.
path
, or undef if none exists.
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
$m->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);
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
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
allow_globals parameter; otherwise you'll get warnings from
strict
.
When using Perl 5.00503 or earlier, using the code cache creates a circular reference between Interp and component objects. This means that Interp objects will not be destroyed unless you call flush_code_cache. If you are using Perl 5.6.0 or greater, Mason uses weak references to prevent this problem.