request(3)

NAME

HTML::Mason::Request - Mason Request Class

SYNOPSIS

$m->abort (...)
$m->comp (...)
etc.

DESCRIPTION

The Request API is your gateway to all Mason features not
provided by syntactic tags. Mason creates a new Request
object for every web request. Inside a component you
access the current request object via the global "$m".

COMPONENT PATHS

The methods the comp entry in the Request manpage, the
comp_exists entry in the Request manpage, the fetch_comp
entry in the Request manpage, and the process_comp_path
entry in the Request manpage take a component path as
argument.

� If the path is absolute (starting with a '/'), then: the component is found relative to the component root.
� If the path is relative (no leading '/'), then the: component is found relative to the current component
directory.
� If the path matches both a subcomponent and file-based: component, the subcomponent takes precedence.

METHODS

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 sta
tus code.; abort() is implemented via die() and can thus be caught by eval().; Under the current implementation, any pending "<%fil
ter>" sections will not be applied to the output after
an abort. This is a known bug but there is no easy
workaround.; The methods "aborted" and "aborted_value" return a
boolean indicating whether the current request was
aborted and the argument with which it was aborted,
respectively. These would be used, for example, after
an eval() returned with a non-empty "$@".
aborted: Returns true or undef indicating whether the current
request was aborted with "abort".
aborted_value: Returns the argument passed to "abort" when the
request was aborted. Returns undef if the request was
not aborted or was aborted without an argument.
base_comp: Returns the current base component for method and
attributes. Generally set to the original page compo
nent; however, if you invoke call_method on a compo
nent, "base_comp" is dynamically set to that component
until call_method exits. See the Object-Oriented Tech
niques entry in the Devel manpage for examples of
usage.
cache ([action=>'retrieve|store|expire|keys'], [key=>name], [value=>data], [keep_in_memory=>0|1], [expire options...]): "$m->cache" lets you store and retrieve the results of
computation for improved performance. Each component
has its own data cache for storing one or more
key/value pairs. The cache is implemented as a DBM
database. See the the data caching entry in the Devel
manpage section of the Component Developer's Guide for examples and caching strategies.; The argument to action is one of:; o retrieve: returns the cache value if successful, or "undef" if there was no value or if it has expired.; o store: stores a new cache value under the given key.
Default key is 'main'. Returns the value being stored
if successful.; o expire: expires a given cache value or values. key
may be a single key or a list reference. Default key
is 'main'.; o keys: returns a list of all the keys in the cache.; value defines what to store. It can be a scalar or a
reference to an arbitrary data structure. The allow
able size depends on your DBM implementation.; keep_in_memory indicates whether to save the value in memory once it is retrieved. Default is 0, meaning
that the value will be retrieved from the cache file
each time. If 1, each child server that retrieves this
value will save its own copy, which can result in sub
stantial memory usage for larger values. Use spar
ingly.; The various expiration options are:; o expire_at: takes an absolute expiration time, in Perl time() format (number of seconds since the epoch); o expire_in: takes a relative expiration time of the form "<num><unit>", where <num> is a positive number
and <unit> is one of seconds, minutes, hours, days, or
weeks, or any abbreviation thereof. E.g. "10min",
"30m", "1hour".; o expire_next: takes a string, either 'hour' or 'day'. It indicates an expiration time at the top of the next
hour or day.; o expire_if: calls a given anonymous subroutine and expires if the subroutine returns a non-zero value.
The subroutine is called with one parameter, the time
when the cache value was last written.
cache_self (... same as cache options...): Uses "$m->cache" to cache the entire output and/or the
return value of the current component. It is typi
cally used right at the top of an "<%init%>" section.; To cache the component's output:

<%init>
return if $m->cache_self(expire_in=>'3

hours'[, key=>'fookey']);
... <rest of init> ...

</%init>; To cache the component's return value:

<%init>
my ($retval,$cached) = $m->cache_self(ex

pire_in=>'3 hours'[, key=>'fookey']);
return $retval if $cached;
... <rest of init> ...

</%init>; This only works with scalar and reference return val
ues.; "$m->cache_self" handles both the retrieve and store,
so you can pass both kinds of options to it. See
"$m->cache" for an explanation of options.; "$m->cache_self" uses a bit of magic to accomplish
everything in one line. You can use it without under
standing it, but if you're curious, here's how it
works:; o A component foo calls "$m->cache_self" for the first
time.; o "$m->cache_self" sees that the cache is empty and
calls foo again recursively, with a STORE option to
capture its content into a buffer.; o foo again calls "$m->cache_self" which immediately
returns 0 this time.; o foo goes about its business and generates content
into the "$m->cache_self" buffer.; o When control is returned to "$m->cache_self", it
stores the content and return value in the cache and
also outputs the content normally. Finally
"$m->cache_self" returns the list (retval,1) which in
turn causes foo to return immediately.
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 argu
ment 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 compo

nent 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.
callers: With no arguments, returns the current component stack
as a list of component objects, starting with the cur
rent component and ending with the top-level compo
nent. With one numeric argument, returns the component
object at that index in the list. Use a positive argu
ment to count from the current component and a nega
tive argument to count from the component at the bot
tom 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 exe

cuted
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 aug
ment and override (in case of conflict) the original
arguments. Works like "$m->comp" in terms of return
value and scalar/list context. See the the autohan
dlers entry in the Devel manpage section of the Compo_
nent Developer's Guide for examples.
clear_buffer: Clears the Mason output buffer. Any output sent before
this line is discarded. Useful for handling error con
ditions that can only be detected in the middle of a
request.; clear_buffer only works in batch output mode, and is
thwarted by "flush_buffer".
comp (comp, args...): Calls the component designated by comp with the speci
fied 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".
comp_exists (comp_path): Returns 1 if comp_path is the path of an existing com ponent, 0 otherwise.
count: Returns the number of this request, which is unique
for a given request and interpreter.
current_comp: Returns the current component object.
decline: Used from a top-level component or dhandler, this
method aborts the current request and restarts with
the next applicable dhandler up the tree. If no dhan
dler is available, an error occurs. This method bears
no relation to the Apache DECLINED status except in
name.
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.
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 the autohandlers
entry in the Devel manpage section of the Component Developer's Guide for usage and examples.
fetch_next_all: Returns a list of the remaining components in the con
tent wrapping chain. Usually called from an autohan
dler. See the the autohandlers entry in the Devel
manpage section of the Component Developer's Guide for usage and examples.
file (filename): Returns the contents of filename as a string. filename may be an absolute filesystem path (starting with a
'/') or relative (no leading '/'). If relative, Mason
prepends the static file root, or the current compo
nent directory if no static file root is defined.
file_root: Returns the static file root, used by "$m->file" to
resolve relative filenames.
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.
interp: Returns the Interp object associated with this
request.
out (string): Print the given string. Rarely needed, since normally
all HTML is just placed in the component body and out
put implicitly. "$m->out" is useful if you need to
output something in the middle of a Perl block.; "$m->out" should be used instead of "print" or
"$r->print", since "$m->out" may be redirected or
buffered depending on the current state of the inter
preter.
parser: Returns the Parser object associated with this
request.
process_comp_path (comp_path): Given a comp_path, returns the corresponding absolute component path.
scomp (comp, args...): Like "$m->comp", but returns the component output as a
string instead of printing it. (Think sprintf versus
printf.) The component's return value is discarded.
time: Returns the interpreter's notion of the current time
in Perl time() format (number of seconds since the
epoch).; By using "$m->time" rather than calling time()
directly, you enable the option of previewer or portbased time/date simulations. e.g. a port that looks
one day into the future.
top_args: Returns the arguments originally passed to the top
level component. When called in scalar context, a
hash reference is returned. When called in list con
text, a list of arguments (which may be assigned to a
hash) is returned.
top_comp: Returns the component originally called in the
request. Note: because of autohandlers this may or may
not be the first component executed.

APACHE-ONLY METHODS

These additional methods are available when running Mason
with mod_perl and the ApacheHandler.

ah Returns the ApacheHandler object associated with this: request.
apache_req: Returns the Apache request object. This is also
available in the global $r.
cgi_object: Returns the CGI object used to parse any CGI parame
ters submitted to the component, assuming that you
have not changed the default value of the ApacheHan
dler "args_method" parameter. If you are using the
'mod_perl' args method, then calling this method is a
fatal error. See the the HTML::Mason::ApacheHandler
manpage documentation for more details.

AUTHOR

Jonathan Swartz, swartz@pobox.com

docs.sk

comprehensive documentation repository

Most Viewed