Appendix A: The Mason API
To provide a convenient reference to the main elements of the Mason class
hierarchy, we've collected the
APIs of the Interpreter, Resolver, Compiler, Lexer, ApacheHandler, CGIHandler,
Component, and Request classes. The parameters to each class's
new() method are listed in Appendix B. Many of these parameters also correspond to simple accessor methods for getting/setting their values; those methods are not listed here, so see Appendix B for a complete list.
We have attempted to show the arguments taken by each method. Replaceable text
is shown in angle brackets (
<>). indicating a value you must specify. An ellipsis (
...) indicates a list of values. Optional arguments are indicated by square
). An optional list of arguments doesn't get both kinds of brackets,
because we figure that's just a list with no elements in it. If alternate
sets of parameters can be given (such as
comp_file for the Interpreter's
make_component() method), we sometimes indicate this by separate listings.
We intend this appendix to be a quick reference; in many cases the official Mason documentation will provide more detail.
The Interpreter is the main entry point for
Mason and coordinates the efforts of several other classes. The default
Interpreter class is
Creates a new Mason Interpreter and returns it. See Appendix B for a list of parameters accepted.
Returns the Compiler object associated with this Interpreter.
Returns the Resolver object associated with this Interpreter.
Returns true or false, depending on whether the
static_sourceparameter is currently set for this Interpreter.
autoflush([<true or false>])
Returns true or false, depending on whether the output buffers will be flushed immediately upon receiving output or not. An optional argument sets the value.
Returns the name of the file to be used for Mason's autohandler mechanism (i.e.,
Returns the name of the file to be used for Mason's dhandler mechanism (i.e.,
"dhandler"). An optional argument sets the value.
Returns the number of bytes allowed for caching of compiled component code. An optional argument sets the value.
Returns a regular expression indicating warnings to ignore when calling or compiling components. An optional argument sets the value.
Returns a hash reference of parameters that will be passed to the caching methods by default. An optional hash reference argument sets the value.
Returns an integer indicating the level of nesting allowed in component calls, as a deterrent to infinite component call loops. An optional argument sets the value.
Returns true or false, depending on whether the Interpreter will cache compiled components to disk as object files.
Returns reference to an array of glob-like patterns specifying components to be loaded when the Interpreter is created.
Returns a list of all files created by the Interpreter. This may be useful if you want to enforce certain file permissions or ownership.
A pass-through method to the Resolver method of the same name.
Returns a string containing the name of the directory in which Mason's component objects will be cached.
Returns the current value of the
Initiates a new Mason request. The first argument should be the component to execute, specified either as an absolute pathname or as a component object. Any additional arguments will be passed to the component.
load(<absolute component path>)
Returns the component at the path specified by the argument. Throws an exception if no such component exists.
comp_exists(<absolute component path>)
Returns true or false, depending on whether a component exists at the path specified by the argument.
make_component(comp_file => <path> [, name => <string> ])
Creates a component object and returns it. The text of the component may be specified as a string in the
comp_sourceparameter or as a filename in the
comp_fileparameter. You may also provide a
nameparameter to associate with this component. If no name is provided, the name will default to a string like
set_global(<name> => <value>)
Sets the value of a Perl global variable so that it will be available to components at runtime. The first argument names the variable in a string (i.e., '$user'), including the leading
%character. The remaining arguments specify the value to assign. The name of the variable should not be fully package-qualified with
:: characters; the variable will be created in the same package in which components execute.
class represents a chain of components executing in a particular context. A
request is begun by invoking the Interpreter's
method. The current Request object is available by default in components as
Creates a new Request object. See Appendix B for a list of parameters accepted. Typically a Request is not created directly, but rather by invoking the Interpreter's
exec()method. The default Request class is
HTML::Mason::Request, though it is different when using ApacheHandler or CGIHandler.
Returns the Request currently running. This can be called as a class method (i.e.,
HTML::Mason::Interp->instance()) from code in which
$mis unavailable. In a subrequest, the subrequest object, not the main request, will be returned.
Returns the Interpreter object associated with this Request.
Returns the Interpreter's counter value for this Request.
error_mode([<'fatal' or 'output'>])
Returns the string
output, depending on whether error conditions should trigger an exception (
fatal) or display an error message in the regular output channel (
output). The mode can be set with an optional argument.
Returns a string indicating how error messages will be formatted. The currently available choices are
html. An optional argument sets the format.
out_method([<subroutine_reference or scalar_reference>])
Returns the current value of the
out_methodparameter or optionally sets it if you pass a subroutine reference or a scalar reference as an argument.
This method is not present in the regular
HTML::Mason::Requestclass, but it is added as a way to access the
CGI.pmrequest object when using
HTML::Mason::CGIHandler. It is also added when using
Only available when using
HTML::Mason::ApacheHandler, in which case the Apache Handler object is returned.
Only available when using
HTML::Mason::ApacheHandler, in which case the
Altering the Request Flow
Terminates the current Request. You may optionally specify a value to be returned by the Interpreter's
exec()method. In a web environment this value will ultimately become the HTTP response code. Accepts an optional exception argument to examine, otherwise
$@will be examined.
Returns true if the current request was aborted (and caught by an
evalblock), or false otherwise. Accepts an exception argument to examine, otherwise
$@will be examined.
If the current request was aborted, this returns the value passed to the
Stops the execution of the current component and passes control to the next applicable dhandler. Any output already generated will be discarded. If no dhandler exists to handle this request, an exception will be thrown.
If the current request is being handled by a dhandler, this method will return the remainder of the request path with the dhandler's directory removed. If no dhandler is executing, this method will return
See Chapter 4 for more information on the data cache and how to use it.
Cache::Cacheobject that manages this component's data cache.
Facilitates automatic caching of the current component's output and return value. The arguments to
cache_self()specify how long the cached data should persist, whether it should be associated with a particular key, and the details of how the data should be cached.
Returns the component that invoked the currently executing component or
undefif this is the topmost component executing.
When called with no arguments, returns a list of all components currently executing. This is known as the 'component stack.' When called with an integer argument
n, returns the component
nlevels up the execution stack. For instance,
$m->callers(1)is equivalent to
Given an integer argument
n, returns an array (if called in list context) or a hash reference (if called in scalar context) of the arguments passed to the component
nlevels up the execution stack.
Returns the current depth of the component stack. For instance, with components
/dir/component.htmlin the default setup, the depth will be 1 when queried in
/autohandler, 2 in
/dir/autohandler, and 3 in
/dir/component.htmlcalls another component, the depth will be 4 inside that component.
Content and Output
A synonym for
print(). This method will output the content of any arguments. In recent versions of Mason you may also print to Perl's STDOUT filehandle, as this is tied to Mason's buffers.
Discards the contents of Mason's output buffers.
Sends the contents of Mason's output buffers to their destination.
Returns the content block passed to the current component or
undefif this component was called without a content block. The content block will be evaluated in the lexical context of the calling component. See "Components called with content" in Chapter 2 for more details.
Given a file path, Mason will look for this file and return its contents as a string.
An absolute path refers to a file on the filesystem. If a relative path is given, Mason will prepend the current component's directory, if it has one. Otherwise Mason will simply make the path absolute by prepending the system's root directory to the path.
These methods deal with fetching and running
components. Some of the methods (in particular
scomp()) let you specify the component by path or by supplying a component object,
while other methods (
comp_exists()) allow only a path. For any of these four methods, if a relative pathname is
given, it is considered relative to the
dir_path of the current component.
Given a string argument specifying a component path, returns the component at that path or
undefif no such component exists.
Fetches the next component in the content-wrapping chain. This is the same component that will be invoked by the
Fetches all remaining components in the content-wrapping chain and returns them as a list. This is usually called from an autohandler and will return multiple components when multiple autohandlers are in use.
Calls a Mason component. The component is specified by the first argument, which should be either the name of the component to call or a component object. Any remaining arguments to
comp()are fed to the called component, either as key/value pairs declared in the component's
<%args>section, the special
%ARGSvariable, or the Perl argument array
@_. Any component output will be sent to the current component's output stream, and the component's return value will become the return value of
Identical to the
comp()method, but instead of sending the called component's output to the output stream, is returned as a string. Any return value from the component will be discarded.
Given a string argument, returns true if a component exists with that path or false otherwise.
Calls the next component in the component execution stack. Typically this is used by an autohandler to call the component it is wrapping around. Mason will pass any current component arguments (the
%ARGShash) to the next component, as well as any additional arguments passed to the
Returns an object representing the currently executing component.
Returns an object representing the component that was originally requested in the Interpreter's
Returns the current base component for methods and attributes. The base component is initially set to the
request_comp(). Calling a component method will set the base component to the component used in the method call. Calling a regular (nonmethod) component will set the base component to the called component.
Returns the arguments passed to the originally requested component. If called in a list context, the arguments will be returned as a list. If called in a scalar context, the arguments will be returned as a hash reference.
make_subrequest(comp => <path>, args => [...], <parameters...>)
Returns a new Request object with the given parameters. Other parameters will be inherited from the current request.
Sets the new request in motion with the given arguments passed to the given component. This should be used only when the request was created with the
exec()can happen only once for each request. In particular, it is illegal to call
$m->exec(...)inside a component.
execmethods into one step. Any arguments are passed to the given component, and the subrequest created will inherit all inheritable properties from the current
class represents a
Mason component. It may be a file-based component on disk, a component created
on the fly, or a method or subcomponent. The default Component class is
Creates a new component. See Appendix B for a list of parameters that affect the component behavior.
notthe proper way to create a component from scratch, since components must be associated with an Interpreter. See the
make_component()Interpreter method if you wish to create a component from scratch.
Returns a unique string identifying this component.
Returns a short string identifying this component. There may be more than one component with the same name.
Returns the path of this component relative to the source root.
Returns the component's notion of a current directory, relative to the component root.
Returns the component's enclosing directory if it is a file-based component. Note that Mason does not actually
chdir()to a component's directory before executing it, so you may need to use
source_dirto establish context.
Returns the full pathname of the object file associated with this component or
undefif this component is not associated with any object file.
Returns the time this component object (not its source file) was created, in number of seconds since the epoch.
Returns a hash reference indicating the variables declared in this component's
<%args>section. Each key in this hash reference is the name of a Perl variable (including the initial sigil,
%), and the value is a hash reference containing (at least) a
defaultkey. Its value, in turn, contains Perl code to be evaluated to get the default value for this component argument.
Given a string argument, returns the value of the Mason flag by that name for this component, as declared in a
<%flags>section. Throws an exception if the argument is not the name of a valid Mason flag. Currently, there is only one flag allowed in
inheritflag that specifies a parent component.
Note that flag values do not inherit from parent components.
Returns true if the component is a subcomponent or method or false otherwise.
Returns true if the component was loaded from a source or object file or false otherwise.
Returns a reference to a hash containing all subcomponents declared by this component, with names as keys and component objects as values. If you provide a string argument, returns only the subcomponent with that name or
undefif no such subcomponent exists.
Returns a reference to a hash containing all methods declared by this component, with names as keys and component objects as values. If you provide a string argument, returns only the method with that name or
undefif no such subcomponent exists.
Note that this does
notsearch for methods in any parent components. See the
call_methodentries in the next section if you wish to perform such a search.
Returns the parent component of this component or
undefif this component has no parent.
If this component is a subcomponent or method, returns the component object in which it was declared.
Given a string argument, returns the value of the attribute (declared in an
<%attr>block) by that name in this component or its parents. If no such attribute exists, an exception will be thrown.
Given a string argument, returns true if an attribute by that name exists in this component or its parents or false otherwise.
Given a string argument, returns the value of the attribute by that name in this component or its parents. If no such attribute exists, returns
call_method(<name> [, <arguments...>])
Given a string argument, searches for a method by that name in this component or its parents and executes it. If no such method exists, a fatal exception will be thrown.
scall_method(<name> [, <arguments...>])
call_method, but returns the component's output as a string instead of outputting it. Any return value will be discarded.
Given a string argument, returns true if a method by that name exists in this component or its parents or false otherwise.
Resolver is responsible for handling the interactions between the Interpreter
and the storage medium of component source files. The default resolver class is
Returns a new Resolver object. See Appendix B for a list of parameters accepted by the
Given a component path, returns an
HTML::Mason::ComponentSourceobject that may be queried to get information about the component source.
Returns the current value of the component root. The value returned may be a string or a reference to an array of arrays, depending on whether you're using one or several component roots. Optionally sets the value of the component root if you provide an argument, whose form is the same.
comp_root(), but in a list context always returns a list of arrays, one per component root. If there is only one root and its name is unspecified, it will be given the name
MAIN. In a scalar context, returns the number of component roots.
Given a "glob"-style pattern, returns a list of paths of all components that match that pattern in the component root.
apache_request_to_comp_path(<Apache request object>)
Given an Apache request object, this method is expected to return a component path, or
undefif the request cannot be translated to a component path.
HTML::Mason::ApacheHandler class provides the necessary glue between the Mason Interpreter and the Apache
mod_perl module. Its main task is to accept an incoming Apache request and invoke the
Interpreter with the proper parameters for handling that request.
ApacheHandler class makes the Apache request object available inside
components as the global variable
. This may be an object blessed into the
Apache::Request class or the
Apache class, depending on whether the Mason administrator has configured the
ApacheHandler to use the
ApacheHandler also turns
$m, the Request object, into an
HTML::Mason::Request::ApacheHandler object by subclassing
Creates a new ApacheHandler object. See Appendix B for a listing of the parameters accepted.
Returns the current Interpreter associated with this ApacheHandler. An optional argument sets the value to a new Interpreter.
Initiates a Mason request, processing any incoming arguments to the web server and calling the appropriate component.
A wrapper around
handle_request()suitable for using as a
mod_perl"handler." You must enable
mod_perlin order to use this handler.
Returns a new Mason Request object for the given Apache Request or an HTTP status code if an error was encountered.
Returns the title of the Mason status page generated by
Apache::Status. An optional argument sets the title.
Returns the current
args_methodsetting, which can be either
CGIdepending on whether you're using
CGI.pmfor HTTP argument processing.
decline_dirs([true or false])
Returns true or false, depending on whether requests for directories will be declined or accepted. An optional argument sets the value. If a request for a directory is accepted, it should usually be caught by using a dhandler mechanism, so Mason has a component to execute.
class is similar to ApacheHandler but runs under the CGI paradigm instead of
mod_perl paradigm. Its task is to accept an incoming CGI request and invoke the Mason
Interpreter with the proper parameters for handling that request.
Creates a new CGIHandler object. See Appendix B for a listing of the parameters accepted.
Initiates a Mason request, processing any incoming arguments to the web server and calling the appropriate component. The initial component will be the one specified in
handle_request(), but explicitly specifies the component as an argument, either as a component path or a component object.
handle_request(), but takes component path from the given CGI object's
path_infomethod. Additionally, this CGI object is available to the called components.
CGIHandler also turns
$r, normally the Apache request object, into an
HTML::Mason::FakeApache object. It provides the following methods for compatibility with a
header_out(<header> => <value>)
Adds an outgoing header to the HTTP response.
Sets the content type of the response to the argument given. If you don't set the content type, the type will be set to
responsible for turning a hierarchical component structure, as fed to it by
the Lexer, into a usable form. The default Compiler is
HTML::Mason::Compiler::ToObject, which creates a Component object.
Creates a new Compiler object and returns it. Called by the Interpreter object. See Appendix B for a list of parameters accepted.
Returns a list of variable names (including the initial
%type-identifying sigil) that have been declared as allowable globals within components or the number of such variables in a scalar context. The list of allowed globals can optionally be set by passing the variable names (again, including the initial sigils) as arguments. This replaces any previously set globals. To clear the list of allowed globals, pass an argument list containing the single element
my @allowed = $compiler->allow_globals; # Get list of globals $compiler->allow_globals('$dbh','%session'); # Set list of globals $compiler->allow_globals(undef); # Clear list of globals
Adds one or more variable names (including the initial
%type-identifying sigil) to the list of globals allowed within components. Returns a list of variable names (again, including the initial sigils) in a list context or the number of such variables in a scalar context.
Returns a string identifier that uniquely identifies this compiler and its current settings. This identifier is used mainly to make sure that components compiled under a different compiler, or under the same compiler with different settings, are declared stale.
compile(comp_source => <string>, name => <string>)
Compiles a component from source text and returns the compiled component. The source text is passed in a
comp_sourceparameter, and a unique identifier for this component is passed in a mandatory
nameparameter. The compiled component may take any of several forms, but the default
HTML::Mason::Compiler::ToObjectclass returns a bunch of Perl code in a string.
These are methods called by the Lexer while processing a component source. You may wish to override some of these methods if you're implementing your own custom Compiler class.
Called by the Lexer when it starts processing a component.
Called by the Lexer when it finishes processing a component.
start_block(block_type => <string>)
Called by the Lexer when it encounters an opening Mason block tag like
<%args>. Its main purpose is to keep track of the nesting of different kinds of blocks within each other. The type of block (
once, etc.) is passed via the
end_block(block_type => <string>)
Called by the Lexer when it encounters a closing Mason block tag like
start_block(), its main purpose is to help maintain syntactic integrity.
*_block(block => <string>, [ block_type => <string> ])
Several compiler methods like
raw_block()are called by the Lexer after
start_block()when it encounters blocks of certain types. These methods actually do the work of putting the body of a block into the compiled data structure.
The methods that follow this pattern are
raw_block(). The last method is called for all
text(text => <string>)
Inserts the text contained in a
textparameter into the component for verbatim output.
This is called when the Lexer finds plain text in a component.
variable_declaration( type => <string>, name => <string>, default => <string> )
Inserts a variable declaration from the
<%args>section into the component.
The type will be either
%, indicating a scalar, array, or hash. The name is the variable name without the leading sigil. The default is everything found after the first
<%args>block line and may include a comment.
key_value_pair(block_type => <string>, key => <string>, value => <string>)
Inserts a key/value pair from a
<%attr>section into the component.
block_typeparameter will be either
start_named_block(block_type => <string>, name => <name>)
start_block, earlier in this section, but starts a "named" block (
Called by the Lexer to end a "named" block.
substitution(substitution => <string>, escape => <string>)
Called by the Lexer when it encounters a substitution tag (
<% ... %>).
The value of the
escapeparameter will be everything found after the pipe (|) in the substitution tag and may be more than one character such as
component_call(call => <string>)
Called by the Lexer when it encounters a component call tag without embedded content (
<& ... &>).
callparameter contains the entire contents of the tag.
component_content_call(call => <string>)
Called by the Lexer when it encounters a component call tag with embedded content (
<&| ... &>).
Called by the Lexer when it encounters an end tag for a component call with content (
</&>). Note that there is no corresponding
component_call_end()method for component calls without content, because these calls don't have end tags.
perl_line(line => <string>)
Called by the Lexer when it encounters a
Lexer has a very limited API, because it is mostly subservient to (and hidden
by) the Compiler. The Compiler calls the Lexer's
lex() methods, then the Lexer calls various Compiler methods to generate the
component. The Lexer has more methods than are listed here, but they're
internal methods and should not be considered part of its formal API. The
default Lexer class is
Creates a new Lexer object and returns it. In the current version of Mason, the
new()method doesn't accept any parameters.
lex(name => <string>, compiler => <compiler>, comp_source => string)
Begins the process of lexing a component. The
nameparameter specifies a unique name for this component. For a file-based component, this is its full path relative to the component root. The
compilerparameter supplies the compiler object to use when processing this component. The
comp_sourceparameter supplies the source to process.
lex()method has no return value. If it encounters an error during processing, it will throw an exception.
Returns the Lexer's current line number in the component being processed.
Returns the name of the component currently being processed (i.e., the value of the
nameparameter passed to the
HTML::Mason::Exception::Syntaxerror with the given error message as well as additional information about the component source.
These HTML pages were created by running this script against the pseudo-POD source.