HTML::Mason::Request - Mason Request Class


HTML::Mason::Request - Mason Request Class


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


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.


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


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 via die() and can thus be caught by eval().

Under the current implementation, any pending <%filter> 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 $@.

Returns true or undef indicating whether the current request was aborted with abort.

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.

Returns the current base component for method and attributes. Generally set to the original page component; however, if you invoke call_method on a component, base_comp is dynamically set to that component until call_method exits. See Object-Oriented Techniques 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 data caching 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 allowable 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 substantial memory usage for larger values. Use sparingly.

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 typically used right at the top of an <%init%> section.

To cache the component's output:

        return if $m->cache_self(expire_in=>'3 hours'[, key=>'fookey']);
        ... <rest of init> ...

To cache the component's return value:

        my ($retval,$cached) = $m->cache_self
            (expire_in=>'3 hours'[, key=>'fookey']);
        return $retval if $cached;
        ... <rest of init> ...

This only works with scalar and reference return values.

$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 understanding 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.

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.

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

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 in the Devel manpage section of the Component Developer's Guide for examples.

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 only works in batch output mode, and is 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.

comp_exists (comp_path)
Returns 1 if comp_path is the path of an existing component, 0 otherwise.

Returns the number of this request, which is unique for a given request and interpreter.

Returns the current component object.

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 dhandler is available, an error occurs. This method bears no relation to the Apache DECLINED status except in name.

Returns the current size of the component stack. The lowest possible value is 1, which indicates we are in the top-level component.

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.

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 in the Devel manpage section of the Component Developer's Guide for usage and examples.

Returns a list of the remaining components in the content wrapping chain. Usually called from an autohandler. See the autohandlers 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 component directory if no static file root is defined.

Returns the static file root, used by $m->file to resolve relative filenames.

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.

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 output 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 interpreter.

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.

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 port-based time/date simulations. e.g. a port that looks one day into the future.

Returns the arguments originally passed to the top level component (see top_comp in the Request manpage 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.

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.


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

Returns the ApacheHandler object associated with this request.

Returns the Apache request object. This is also available in the global $r.

Returns the CGI object used to parse any CGI parameters submitted to the component, assuming that you have not changed the default value of the ApacheHandler 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.


Jonathan Swartz,


the HTML::Mason::Component manpage the HTML::Mason::ApacheHandler manpage

 HTML::Mason::Request - Mason Request Class