abort ([return value])
Ends the current request, finishing the page without returning through components. The optional
argument specifies the return value from "Interp::exec"; in a web environment, this ultimately
becomes the HTTP status code.
"abort" is implemented by throwing an HTML::Mason::Exception::Abort object and can thus be caught by
eval(). The "aborted" method is a shortcut for determining whether a caught error was generated by
"abort".
If "abort" is called from a component that has a "<%filter>", than any output generated up to that
point is filtered, unless "abort" is called from a "<%shared>" block.
clear_and_abort ([return value])
This method is syntactic sugar for calling clear_buffer() and then abort(). If you are aborting the
request because of an error, you will often want to clear the buffer first so that any output
generated up to that point is not sent to the client.
aborted ([$err])
Returns true or undef indicating whether the specified $err was generated by "abort". If no $err was
passed, uses $@.
In this code, we catch and process fatal errors while letting "abort" exceptions pass through:
eval { code_that_may_fail_or_abort() };
if ($@) {
die $@ if $m->aborted;
# handle fatal errors...
$@ can lose its value quickly, so if you are planning to call $m->aborted more than a few lines after
the eval, you should save $@ to a temporary variable.
base_comp
Returns the current base component.
Here are the rules that determine base_comp as you move from component to component.
• At the beginning of a request, the base component is initialized to the requested component
("$m->request_comp()").
• When you call a regular component via a path, the base component changes to the called component.
• When you call a component method via a path (/foo/bar:baz), the base component changes to the
method's owner.
• The base component does not change when:
• a component call is made to a component object
• a component call is made to SELF:x or PARENT:x or REQUEST:x
• a component call is made to a subcomponent (<%def>)
This may return nothing if the base component is not yet known, for example inside a plugin's
start_request_hook() method, where we have created a request but it does not yet know anything about
the component being called.
cache
"$m->cache" returns a new cache object with a namespace specific to this component. The parameters to
and return value from "$m->cache" differ depending on which data_cache_api you are using.
If data_cache_api = 1.1 (default)
cache_class specifies the class of cache object to create. It defaults to "FileCache" in most
cases, or "MemoryCache" if the interpreter has no data directory, and must be a backend subclass
of "Cache::Cache". The prefix "Cache::" need not be included. See the "Cache::Cache" package for
a full list of backend subclasses.
Beyond that, cache_options may include any valid options to the new() method of the cache class.
e.g. for "FileCache", valid options include "default_expires_in" and "cache_depth".
See HTML::Mason::Cache::BaseCache for information about the object returned from "$m->cache".
If data_cache_api = CHI
chi_root_class specifies the factory class that will be called to create cache objects. The
default is 'CHI'.
driver specifies the driver to use, for example "Memory" or "FastMmap". The default is "File" in
most cases, or "Memory" if the interpreter has no data directory.
Beyond that, cache_options may include any valid options to the new() method of the driver. e.g.
for the "File" driver, valid options include "expires_in" and "depth".
cache_self ([expires_in => '...'], [key => '...'], [get_options], [cache_options])
"$m->cache_self" caches the entire output and return result of a component.
"cache_self" either returns undef, or a list containing the return value of the component followed by
'1'. You should return immediately upon getting the latter result, as this indicates that you are
inside the second invocation of the component.
"cache_self" takes any of parameters to "$m->cache" (e.g. cache_depth), any of the optional
parameters to "$cache->get" (expire_if, busy_lock), and two additional options:
• expire_in or expires_in: Indicates when the cache expires - it is passed as the third argument to
"$cache->set". e.g. '10 sec', '5 min', '2 hours'.
• key: An identifier used to uniquely identify the cache results - it is passed as the first
argument to "$cache->get" and "$cache->set". The default key is '__mason_cache_self__'.
To cache the component's output:
<%init>
return if $m->cache_self(expire_in => '10 sec'[, key => 'fookey']);
... <rest of init> ...
</%init>
To cache the component's scalar return value:
<%init>
my ($result, $cached) = $m->cache_self(expire_in => '5 min'[, key => 'fookey']);
return $result if $cached;
... <rest of init> ...
</%init>
To cache the component's list return value:
<%init>
my (@retval) = $m->cache_self(expire_in => '3 hours'[, key => 'fookey']);
return @retval if pop @retval;
... <rest of init> ...
</%init>
We call "pop" on @retval to remove the mandatory '1' at the end of the list.
If a component has a "<%filter>" block, then the filtered output is cached.
Note: users upgrading from 1.0x and earlier can continue to use the old "$m->cache_self" API by
setting data_cache_api to '1.0'. This support will be removed at a later date.
See the the DATA CACHING section of the developer's manual section for more details on how to
exercise finer control over caching.
caller_args
Returns the arguments passed by the component at the specified stack level. Use a positive argument
to count from the current component and a negative argument to count from the component at the bottom
of the stack. e.g.
$m->caller_args(0) # arguments passed to current component
$m->caller_args(1) # arguments passed to component that called us
$m->caller_args(-1) # arguments passed to first component executed
When called in scalar context, a hash reference is returned. When called in list context, a list of
arguments (which may be assigned to a hash) is returned. Returns undef or an empty list, depending
on context, if the specified stack level does not exist.
callers
With no arguments, returns the current component stack as a list of component objects, starting with
the current component and ending with the top-level component. With one numeric argument, returns the
component object at that index in the list. Use a positive argument to count from the current
component and a negative argument to count from the component at the bottom of the stack. e.g.
my @comps = $m->callers # all components
$m->callers(0) # current component
$m->callers(1) # component that called us
$m->callers(-1) # first component executed
Returns undef or an empty list, depending on context, if the specified stack level does not exist.
caller
A synonym for "$m->callers(1)", i.e. the component that called the currently executing component.
call_next ([args...])
Calls the next component in the content wrapping chain; usually called from an autohandler. With no
arguments, the original arguments are passed to the component. Any arguments specified here serve to
augment and override (in case of conflict) the original arguments. Works like "$m->comp" in terms of
return value and scalar/list context. See the autohandlers section of the developer's manual for
examples.
call_self (output, return, error, tag)
This method allows a component to call itself so that it can filter both its output and return
values. It is fairly advanced; for most purposes the "<%filter>" tag will be sufficient and simpler.
"$m->call_self" takes four arguments, all of them optional.
output - scalar reference that will be populated with the component output.
return - scalar reference that will be populated with the component return value.
error - scalar reference that will be populated with the error thrown by the component, if any. If
this parameter is not defined, then call_self will not catch errors.
tag - a name for this call_self invocation; can almost always be omitted.
"$m->call_self" acts like a fork() in the sense that it will return twice with different values.
When it returns 0, you allow control to pass through to the rest of your component. When it returns
1, that means the component has finished and you can examine the output, return value and error.
(Don't worry, it doesn't really do a fork! See next section for explanation.)
The following examples would generally appear at the top of a "<%init>" section. Here is a no-op
"$m->call_self" that leaves the output and return value untouched:
<%init>
my ($output, $retval);
if ($m->call_self(\$output, \$retval)) {
$m->print($output);
return $retval;
}
...
Here is a simple output filter that makes the output all uppercase. Note that we ignore both the
original and the final return value.
<%init>
my ($output, $error);
if ($m->call_self(\$output, undef)) {
$m->print(uc $output);
return;
}
...
Here is a piece of code that traps all errors occurring anywhere in a component or its children, e.g.
for the purpose of handling application-specific exceptions. This is difficult to do with a manual
"eval" because it would have to span multiple code sections and the main component body.
<%init>
my ($output, undef, $error);
if ($m->call_self(\$output, undef, \$error)) {
if ($error) {
# check $error and do something with it
}
$m->print($output);
return;
}
...
clear_buffer
Clears the Mason output buffer. Any output sent before this line is discarded. Useful for handling
error conditions that can only be detected in the middle of a request.
clear_buffer is, of course, thwarted by "flush_buffer".
comp (comp, args...)
Calls the component designated by comp with the specified option/value pairs. comp may be a component
path or a component object.
Components work exactly like Perl subroutines in terms of return values and context. A component can
return any type of value, which is then returned from the "$m->comp" call.
The <& &> tag provides a convenient shortcut for "$m->comp".
As of 1.10, component calls can accept an initial hash reference of modifiers. The only currently
supported modifier is "store", which stores the component's output in a scalar reference. For
example:
my $buf;
my $return = $m->comp( { store => \$buf }, '/some/comp', type => 'big' );
This mostly duplicates the behavior of scomp, but can be useful in rare cases where you need to
capture both a component's output and return value.
This modifier can be used with the <& &> tag as well, for example:
<& { store => \$buf }, '/some/comp', size => 'medium' &>
comp_exists (comp_path)
Returns 1 if comp_path is the path of an existing component, 0 otherwise. comp_path may be any path
accepted by comp or fetch_comp, including method or subcomponent paths.
Depending on implementation, <comp_exists> may try to load the component referred to by the path, and
may throw an error if the component contains a syntax error.
content
Evaluates the content (passed between <&| comp &> and </&> tags) of the current component, and
returns the resulting text.
Returns undef if there is no content.
has_content
Returns true if the component was called with content (i.e. with <&| comp &> and </&> tags instead of
a single <& comp &> tag). This is generally better than checking the defined'ness of "$m->content"
because it will not try to evaluate the content.
count
Returns the number of this request, which is unique for a given request and interpreter.
current_args
Returns the arguments passed to the current component. When called in scalar context, a hash
reference is returned. When called in list context, a list of arguments (which may be assigned to a
hash) is returned.
current_comp
Returns the current component object.
decline
Used from a top-level component or dhandler, this method clears the output buffer, aborts the current
request and restarts with the next applicable dhandler up the tree. If no dhandler is available, a
not-found error occurs.
This method bears no relation to the Apache DECLINED status except in name.
declined ([$err])
Returns true or undef indicating whether the specified $err was generated by "decline". If no $err
was passed, uses $@.
depth
Returns the current size of the component stack. The lowest possible value is 1, which indicates we
are in the top-level component.
dhandler_arg
If the request has been handled by a dhandler, this method returns the remainder of the URI or
"Interp::exec" path when the dhandler directory is removed. Otherwise returns undef.
"dhandler_arg" may be called from any component in the request, not just the dhandler.
exec (comp, args...)
Starts the request by executing the top-level component and arguments. This is normally called for
you on the main request, but you can use it to execute subrequests.
A request can only be executed once; e.g. it is an error to call this recursively on the same
request.
fetch_comp (comp_path)
Given a comp_path, returns the corresponding component object or undef if no such component exists.
fetch_next
Returns the next component in the content wrapping chain, or undef if there is no next component.
Usually called from an autohandler. See the autohandlers section of the developer's manual for usage
and examples.
fetch_next_all
Returns a list of the remaining components in the content wrapping chain. Usually called from an
autohandler. See the autohandlers section of the developer's manual for usage and examples.
file (filename)
Returns the contents of filename as a string. If filename is a relative path, Mason prepends the
current component directory.
flush_buffer
Flushes the Mason output buffer. Under mod_perl, also sends HTTP headers if they haven't been sent
and calls "$r->rflush" to flush the Apache buffer. Flushing the initial bytes of output can make your
servers appear more responsive.
Attempts to flush the buffers are ignored within the context of a call to "$m->scomp" or when output
is being stored in a scalar reference, as with the " { store => \$out } " component call modifier.
"<%filter>" blocks will process the output whenever the buffers are flushed. If "autoflush" is on,
your data may be filtered in small pieces.
instance
This class method returns the "HTML::Mason::Request" currently in use. If called when no Mason
request is active it will return "undef".
If called inside a subrequest, it returns the subrequest object.
interp
Returns the Interp object associated with this request.
make_subrequest (comp => path, args => arrayref, other parameters)
This method creates a new Request object which inherits its parent's settable properties, such as
autoflush and out_method. These values may be overridden by passing parameters to this method.
The "comp" parameter is required, while all other parameters are optional. It may be specified as an
absolute path or as a path relative to the current component.
See the subrequests section of the developer's manual for more information about subrequests.
log Returns a "Log::Any" logger with a log category specific to the current component. The category for
a component "/foo/bar" would be "HTML::Mason::Component::foo::bar".
notes (key, value)
The notes() method provides a place to store application data, giving developers a way to share data
among multiple components. Any data stored here persists for the duration of the request, i.e. the
same lifetime as the Request object.
Conceptually, notes() contains a hash of key-value pairs. "notes($key, $value)" stores a new entry
in this hash. notes($key) returns a previously stored value. notes() without any arguments returns
a reference to the entire hash of key-value pairs.
notes() is similar to the mod_perl method "$r->pnotes()". The main differences are that this notes()
can be used in a non-mod_perl environment, and that its lifetime is tied to the Mason request object,
not the Apache request object. In particular, a Mason subrequest has its own notes() structure, but
would access the same "$r->pnotes()" structure.
out (string)
A synonym for "$m->print".
print (string)
Print the given string. Rarely needed, since normally all text is just placed in the component body
and output implicitly. "$m->print" is useful if you need to output something in the middle of a Perl
block.
In 1.1 and on, "print" and "$r->print" are remapped to "$m->print", so they may be used
interchangeably. Before 1.1, one should only use "$m->print".
request_args
Returns the arguments originally passed to the top level component (see request_comp for definition).
When called in scalar context, a hash reference is returned. When called in list context, a list of
arguments (which may be assigned to a hash) is returned.
request_comp
Returns the component originally called in the request. Without autohandlers, this is the same as the
first component executed. With autohandlers, this is the component at the end of the "$m->call_next"
chain.
request_depth
Returns the current size of the request/subrequest stack. The lowest possible value is 1, which
indicates we are in the top-level request. A value of 2 indicates we are inside a subrequest of the
top-level request, and so on.
scomp (comp, args...)
Like comp, but returns the component output as a string instead of printing it. (Think sprintf versus
printf.) The component's return value is discarded.
subexec (comp, args...)
This method creates a new subrequest with the specified top-level component and arguments, and
executes it. This is most often used to perform an "internal redirect" to a new component such that
autohandlers and dhandlers take effect.
time
Returns the interpreter's notion of the current time (deprecated).
Install Now
PNG Icons
