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

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

cache ([action=>'retrieve|store|expire|keys'], [key=>name], [value=>data], [keep_in_memory=>0|1], [expire options...])

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:

    <%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.

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.

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

call_next ([args...])

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

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 dhandler 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

fetch_next_all

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.

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

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 port-based 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 context, 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.

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