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. Outside of a component, you can use the class method instance.

True or false, default is false. Indicates whether to flush the output buffer ($m->flush_buffer) after every string is output. Turn on autoflush if you need to send partial output to the client, for example in a progress meter.

As of Mason 1.3, autoflush will only work if enable_autoflush has been set. Components can be compiled more efficiently if they don't have to check for autoflush. Before using autoflush you might consider whether a few manual $m->flush_buffer calls would work nearly as well.

'1.0' indicates the custom cache API used in Mason 1.0x and earlier. This compatibility layer is provided as a convenience for users upgrading from older versions of Mason, but will not be supported indefinitely.

line - a single-line text format, with different pieces of information separated by tabs (useful for log files)

html - a fancy html format

The default format under Apache and CGI is either line or html depending on whether the error mode is fatal or output, respectively. The default for standalone mode is text.

The formats correspond to HTML::Mason::Exception methods named as_format. You can define your own format by creating an appropriately named method; for example, to define an "xml" format, create a method HTML::Mason::Exception::as_xml patterned after one of the built-in methods.

A code reference used to handle errors thrown during component compilation or runtime. By default, this is a subroutine that turns non-exception object errors in components into exceptions. If this parameter is set to a false value, these errors are simply rethrown as-is.

Turning exceptions into objects can be expensive, since this will cause the generation of a stack trace for each error. If you are using strings or unblessed references as exceptions in your code, you may want to turn this off as a performance boost.

Indicates where to send output. If out_method is a reference to a scalar, output is appended to the scalar. If out_method is a reference to a subroutine, the subroutine is called with each output string. For example, to send output to a file called "mason.out":

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, unlessabort is called from a <%shared> block.

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.

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

$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__'.

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.

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.

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.

$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:

Here is a piece of code that traps all errors occuring 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

True or false, default is true. Indicates whether Mason should automatically send HTTP headers before sending content back to the client. If you set to false, you should call $r->send_http_header manually.

See the sending HTTP headers section of the developer's manual for more details about the automatic header feature.

NOTE: This parameter has no effect under mod_perl-2, since calling $r->send_http_header is no longer needed.

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 ApacheHandler and CGIHandler documentation for more details.

Given a url, this generates a proper HTTP redirect for that URL. It uses $m->clear_and_abort to clear out any previous output, and abort the request. By default, the status code used is 302, but this can be overridden by the user.

Since this is implemented using $m->abort, it will be trapped by an eval {} block. If you are using an eval {} block in your code to trap errors, you need to make sure to rethrow these exceptions, like this: