REQUEST(1)

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
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 the Object-Oriented Techniques entry in the Devel manpage for examples of usage. `$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 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. 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:

    <%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
            (expire_in=>'3 hours'[, key=>'fookey']);
        return $retval if $cached;
        ... <rest of init> ...
    </%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
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 the autohandlers entry 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'. 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'. 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. 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 the autohandlers entry 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 the autohandlers entry in the Devel manpage section of the Component Developer's Guide for usage and examples. 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. 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. Given a comp_path, returns the corresponding absolute component path. 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 the top_comp entry 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.

APACHE-ONLY METHODS
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.

AUTHOR
Jonathan Swartz, swartz@pobox.com

SEE ALSO
the HTML::Mason::Component manpage the HTML::Mason::ApacheHandler manpage