class represents a chain of components
executing in a particular context. A request is begun by invoking the
method. The current Request object is available by default in
components as the variable
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
method. The default Request class is
, though it is different when using
ApacheHandler or CGIHandler.
Returns the Request currently running. This can be called as a class
from code in which
$m is unavailable. In a
subrequest, the subrequest object, not the main request, will be
Returns the Interpreter object associated with this Request.
Returns the Interpreter’s counter value for this Request.
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
Returns a string indicating how error messages will be formatted. The
currently available choices are
html. An optional argument sets the format.
Returns the current value of the
parameter 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::Request class, but it is added as a
way to access the
CGI.pm request object when using
HTML::Mason::CGIHandler. It is also added when
HTML::Mason::ApacheHandler with the
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
mod_perl request object
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
eval block), or false otherwise. Accepts an
exception argument to examine, otherwise
If the current request was aborted, this returns the value passed to
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::Cache object that manages this
component’s data cache.
Facilitates automatic caching of the current
component’s output and return value. The arguments
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.
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
levels 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
n levels up the execution stack.
Returns the current depth of the component stack. For instance, with
/dir/component.html in the default setup, the
depth will be 1 when queried in
/autohandler, 2 in
/dir/autohandler, and 3 in
/dir/component.html calls another component, the
depth will be 4 inside that component.
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
undef if this component was called without a
content block. The content block will be evaluated in the lexical
context of the calling component. See Section 188.8.131.52 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
comp( ) and
scomp( )) let you specify the component by path or by supplying a
component object, while other methods (
fetch_comp( ) and
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
Given a string argument specifying a component path, returns the
component at that path or
undef if no such
Fetches the next component in the content-wrapping chain. This is the
same component that will be invoked by the
call_next( ) method.
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
%ARGS variable, 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
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
%ARGS hash) 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
exec( ) method.
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
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.
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
make_subrequest( ) method, since
exec( ) can happen only once for each request. In
particular, it is illegal to call
inside a component.
exec methods into one step. Any arguments are
passed to the given component, and the subrequest created will
inherit all inheritable properties from