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.

PARAMETERS FOR new() CONSTRUCTOR

autohandler_name

File name used for autohandlers. Default is "autohandler".

autoflush

This parameter indicates whether or not requests created by this interpreter should have autoflush turned on or off by default.

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 Code Cache section in the Admin Guide for further details.

compiler

The Compiler object to associate with this Interpreter. If none is provided a default compiler using the HTML::Mason::Compiler::ToObject and HTML::Mason::Lexer classes will be created.

data_dir

The Mason data directory. Mason's various data directories (obj, cache, etc), live within the data_dir.

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.

data_cache_defaults

A hash reference of default options to use for the $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.

static_source

True or false, default is false. When false, Mason checks the timestamp of the component source file each time the component is used to see if it has changed. This provides the instant feedback for source changes that is expected for development. However it does entail a file stat for each component executed.

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

Regular expression indicating which warnings to ignore when loading components. Any warning that is not ignored will prevent the component from being loaded and executed. For example:

    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

A list of component paths, optionally with glob wildcards, to load when the interpreter initializes. e.g.

    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.

resolver

The Resolver object to associate with this Interpreter. If none is provided, a default Resolver will be created.

use_object_files

True or false, 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.

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 $c = $interp->compiler;
    $interp->dhandler_name("da-handler");

The following properties can be queried but not modified: data_dir, preloads.

OTHER METHODS

exec (comp, args...)

Creates a new HTML::Mason::Request object for the given comp and args, and executes it. The return value is the return value of comp, if any.

This is useful for running Mason outside of a web environment. See "Using Mason from a standalone script" in HTML::Mason::Admin for examples.

This method isn't generally useful in a mod_perl environment; see subrequests instead.

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 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_exists (path)

Given an absolute component path, this method returns a boolean value indicating whether or not a component exists for that path.

make_component (comp_source => ... )

make_component (comp_file => ... )

This method compiles Mason component source code and returns a Component object. The source may be passed in as a string in 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);

load (path)

Returns the component object corresponding to an absolute component path, or undef if none exists.

comp_root (comp_root)

This is a convenience method which simply calls the 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.

SEE ALSO

HTML::Mason, HTML::Mason::Admin, HTML::Mason::ApacheHandler