HTML::Mason::Interp - Mason Component Interpreter

- NAME
- SYNOPSIS
- DESCRIPTION
- PARAMETERS FOR new() CONSTRUCTOR
- ACCESSOR METHODS
- OTHER METHODS
- STANDALONE MODE
  - Using Mason from a CGI script
  - Using Mason from a standalone script
- AUTHOR
- SEE ALSO

# 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.

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.

# PARAMETERS FOR new() CONSTRUCTOR

allow_recursive_autohandlers
  True or undef. Default is true as of verison 0.85. If true, autohandlers apply both to their own directories and all subdirectories; if undef, only to their own directories. See the autohandlers section of the Component Developer's Guide for a discussion of the pros and cons.

autohandler_name
  File name used for autohandlers. Default is ``autohandler''. If undef, Mason will not look for autohandlers.

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 of the Admin Guide for further details.

comp_root
  The required Mason component root. All components live under the comp_root.

  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.

current_time
  Overrides the time returned by $m->time with a fixed Perl `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
  The required Mason data directory. Mason's various data directories (obj, cache, debug, etc), live within the data_dir.

data_cache_dir
  Specifies an absolute directory for data cache files. By default, it lives under data_dir/cache.

die_handler
  Specifies a subroutine reference to be used to override $SIG{__DIE__} when components are being executed. If this parameter is specified then it will override the normal error handling done by Mason. The default error handler produces a stack trace that excludes the part of the stack inside the Mason core code.

  If this parameter is false, then $SIG{__DIE__} will not be overridden at all. Defaults to:

       sub { Carp::confess($_[0]) }

dhandler_name
  File name used for dhandlers. Default is ``dhandler''. If undef, Mason will not look for dhandlers.

max_recurse
  The maximum component stack depth the interpreter is allowed to descend before signalling an error. Default is 32.

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]) }

  By default, out_method prints to standard output. (In a mod_perl environment this is automatically redirected to the HTTP client.)

out_mode
  Specifies one of two ways to send output, 'batch' or 'stream'. In batch mode Mason computes the entire page in a memory buffer and then transmits it all at once. In stream mode Mason outputs data as soon as it is computed. (This does not take into account buffering done by Apache or the O/S.) The default mode is batch. See the staging vs production section of the Admin Guide for a discussion of the trade-offs.

parser
  Parser object for compiling components on the fly. If omitted, creates a parser with default parameters.

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. 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 `$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.

system_log_events
  A string value indicating one or more events to record in the system log, separated by ``|''. Default is to log nothing.

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'').

use_autohandlers
  True or undef, default is true. If not true, Mason will not attempt to use autohandlers.

use_data_cache
  True or undef, default is true. Specifies whether the $m->cache and related commands are operational. You may need to disable data caching temporarily for debugging purposes, but normally this should be left alone.

use_dhandlers
  True or undef, default is true. If not true, Mason will not attempt to use dhandlers.

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.

# 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 $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.

# OTHER METHODS

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 Parser parameter 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 allow_globals; otherwise you'll get warnings from `strict`.

# STANDALONE MODE

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.

When using Mason outside of mod_perl, just create an 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.

## Using Mason from a CGI script

Here is a skeleton CGI script that calls a component and sends the output to the browser.

        #!/usr/bin/perl -w
        use CGI;
        use HTML::Mason;
        use HTML::Mason::Utils qw(cgi_request_args);

        my $interp = new HTML::Mason::Interp (comp_root=>'...',
                                              data_dir=>'...');

        my $q = new CGI;
        my $comp = $ENV{'PATH_TRANSLATED'};
        my $root = $interp->comp_root;
        $comp =~ s/^$root//
            or die "Requested file '$comp' is outside component root '$root'";
        my %args = cgi_request_args($q, $q->request_method);
        print $q->header;

        $interp->exec($comp, %args);

The relevant portions of the httpd.conf file look like:

        DocumentRoot /path/to/comp/root
        ScriptAlias /cgi-bin/ /path/to/cgi-bin/
        Action html-mason /cgi-bin/handler.cgi

        <Directory /path/to/comp/root>
        SetHandler html-mason
        </Directory>

This simply causes Apache to call handler.cgi every time a file under the component root is requested.

It should be noted that because this script simply prints standard HTTP headers and then executes a component, there would be no way of sending non-OK responses to the browser from your components.

A more complex handler.cgi script might look like this:

        #!/usr/bin/perl -w
        use CGI;
        use HTML::Mason;
        use HTML::Mason::Compiler::ToObject;
        use HTML::Mason::Utils qw(cgi_request_args);
        use HTTP::Headers;

        my $parser = new HTML::Mason::Parser (allow_globals='$H');
        my $interp = new HTML::Mason::Interp (comp_root=>'...',
                                              data_dir=>'...',
                                              parser=>$parser);

        my $q = new CGI;
        my $comp = $ENV{'PATH_TRANSLATED'};
        my $root = $interp->comp_root;
        $comp =~ s/^$root//
            or die "Requested file '$comp' is outside component root '$root'";
        my %args = cgi_request_args($q, $q->request_method);

        # Gather all component output into a buffer.
        my $buffer;
        $interp->out_method(\$buffer);

        my $H = new HTTP::Headers;
        $interp->set_global('$H'=>$H);

        eval { $interp->exec($comp, %args) };

        if ($@) {
            handle_error($@);
        } else {
            unless ($H->header('content-type')) {
                $H->header('content-type' => 'text/html');
            }
            print $H->as_string;
            print $buffer;
        }

This script offers components the use of a global named `$h` which can be used to set headers (for example, for a redirect). It also catches errors in the execution of the script and has a routine to handle them.

## Using Mason from a standalone script

Here is a skeleton script that calls a component and places the output in a file:

        my $outbuf;
        my $interp = new HTML::Mason::Interp (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";

This allows you to use Mason as a pure text templating solution -- like Text::Template and its brethren, but with more power (and of course more complexity).

# AUTHOR

Jonathan Swartz, swartz@pobox.com

# SEE ALSO

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