view release on metacpan or  search on metacpan

lib/Mason/Interp.pm  view on Meta::CPAN

__END__

=pod

=head1 NAME

Mason::Interp - Mason Interpreter

=head1 SYNOPSIS

    my $interp = Mason->new(
        comp_root => '/path/to/comps',
        data_dir  => '/path/to/data',
        ...
    );
    my $output = $interp->run( '/request/path', foo => 5 )->output();

=head1 DESCRIPTION

Interp is the central Mason object, returned from C<< Mason->new >>. It is
responsible for creating new requests, compiling components, and maintaining
the cache of loaded components.

=head1 PARAMETERS TO THE new() CONSTRUCTOR

=over

=item allow_globals (varnames)

List of one or more global variable names that will be available in all
components, like C<< $m >> is by default.

    allow_globals => [qw($dbh)]

As in any programming environment, globals should be created sparingly (if at
all) and only when other mechanisms (parameter passing, attributes, singletons)
will not suffice. L<Catalyst::View::Mason2|Catalyst::View::Mason2>, for
example, creates a C<< $c >> global set to the context object in each request.

Set the values of globals with L<set_global|/set_global>.

=item autobase_names

Array reference of L<autobase|Mason::Manual/Autobase components> filenames to
check in order when determining a component's superclass. Default is C<<
["Base.mp", "Base.mc"] >>.

=item autoextend_request_path

Whether to automatically add the L<top level extensions|/top_level_extensions>
(by default ".mp" and ".mc") to the request path when searching for a matching
page component. Defaults to true.

=item class_header

Perl code to be added at the top of the compiled class for every component,
e.g. to bring in common features or import common methods. Default is the empty
string.

    # Add to the top of every component class:
    #   use Modern::Perl;
    #   use JSON::XS qw(encode_json decode_json);
    #
    my $mason = Mason->new(
        ...
        class_header => qq(
            use Modern::Perl;
            use JSON::XS qw(encode_json decode_json);
        ),
    );

This is used by
L<Mason::Compilation::output_class_header|Mason::Compilation/output_class_header>.
For more advanced usage you can override that method in a subclass or plugin.

=item comp_root

Required. The component root marks the top of your component hierarchy and
defines how component paths are translated into real file paths. For example,
if your component root is F</usr/local/httpd/docs>, a component path of
F</products/sales.mc> translates to the file
F</usr/local/httpd/docs/products/sales.mc>.

This parameter may be either a single path or an array reference of paths. If
it is an array reference, the paths will be searched in the provided order
whenever a component path is resolved, much like Perl's C<< @INC >>.

=item component_class_prefix

Prefix to use in generated component classnames. Defaults to 'MC' plus the
interpreter's count, e.g. MC0. So a component '/foo/bar' would get a classname
like 'MC0::foo::bar'.

=item data_dir

The data directory is a writable directory that Mason uses for various features
and optimizations: for example, component object files and data cache files.
Mason will create the directory on startup if necessary.

Defaults to a temporary directory that will be cleaned up at process end. This
will hurt performance as Mason will have to recompile components on each run.

=item dhandler_names

Array reference of dhandler file names to check in order when resolving a
top-level path. Default is C<< ["dhandler.mp", "dhandler.mc"] >>. An empty list
disables this feature.

=item index_names

Array reference of index file names to check in order when resolving a
top-level path. Default is C<< ["index.mp", "index.mc"] >>. An empty list
disables this feature.

=item no_source_line_numbers

Do not put in source line number comments when generating code.  Setting this
to true will cause error line numbers to reflect the real object file, rather
than the source component.

=item object_file_extension

Extension to add to the end of object files. Default is ".mobj".

=item plugins

A list of plugins and/or plugin bundles: