perldoc > HTML::Mason::Request(3pm)

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

COMPONENT PATHS
    The methods Request->comp, Request->comp_exists, and Request->fetch_comp take a component path
    argument. Component paths are like URL paths, and always use a forward slash (/) as the
    separator, regardless of what your operating system uses.

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

PARAMETERS TO THE new() CONSTRUCTOR
    autoflush
        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.

    data_cache_api
        The "$m->cache" API to use:

        *   '1.1', the default, indicates a "Cache::Cache" based API.

        *   'chi' indicates a "CHI" based API.

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

    data_cache_defaults
        A hash reference of default options to use for the "$m->cache" command. For example, to use
        Cache::Cache's "MemoryCache" implementation by default:

            data_cache_defaults => {cache_class => 'MemoryCache'}

        To use the CHI "FastMmap" driver by default:

            data_cache_api      => 'CHI',
            data_cache_defaults => {driver => 'FastMmap'},

        These settings are overridden by options given to particular "$m->cache" calls.

    dhandler_name
        File name used for dhandlers. Default is "dhandler". If this is set to an empty string ("")
        then dhandlers are turned off entirely.

    error_format
        Indicates how errors are formatted. The built-in choices are

        *   *brief* - just the error message with no trace information

        *   *text* - a multi-line text format

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

    error_mode
        Indicates how errors are returned to the caller. The choices are *fatal*, meaning die with
        the error, and *output*, meaning output the error just like regular output.

        The default under Apache and CGI is *output*, causing the error to be displayed in the
        browser. The default for standalone mode is *fatal*.

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

    max_recurse
        The maximum recursion depth for the component stack, for the request stack, and for the
        inheritance stack. An error is signalled if the maximum is exceeded. Default is 32.

    out_method
        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":

            my $fh = new IO::File ">mason.out";
            ...
            out_method => sub { $fh->print($_[0]) }

        By default, out_method prints to standard output. Under Apache, standard output is
        redirected to "$r->print".

    plugins
        An array of plugins that will be called at various stages of request processing. Please see
        HTML::Mason::Plugin for details.

ACCESSOR METHODS
    All of the above properties have standard accessor methods of the same name. In general, no
    arguments retrieves the value, and one argument sets and returns the value. For example:

        my $max_recurse_level = $m->max_recurse;
        $m->autoflush(1);

OTHER 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 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, *unless* "abort" is called from a "<%shared>" block.

    clear_and_abort ([return value])
        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.

    aborted ([$err])
        Returns true or undef indicating whether the specified $err was generated by "abort". If no
        $err was passed, uses $@.

        In this code, we catch and process fatal errors while letting "abort" exceptions pass
        through:

            eval { code_that_may_fail_or_abort() };
            if ($@) {
                die $@ if $m->aborted;

                # handle fatal errors...

        $@ can lose its value quickly, so if you are planning to call $m->aborted more than a few
        lines after the eval, you should save $@ to a temporary variable.

    base_comp
        Returns the current base component.

        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
        "$m->cache" returns a new cache object with a namespace specific to this component. The
        parameters to and return value from "$m->cache" differ depending on which data_cache_api you
        are using.

        If data_cache_api = 1.1 (default)
            *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".

            See HTML::Mason::Cache::BaseCache for information about the object returned from
            "$m->cache".

        If data_cache_api = CHI
            *chi_root_class* specifies the factory class that will be called to create cache
            objects. The default is 'CHI'.

            *driver* specifies the driver to use, for example "Memory" or "FastMmap". The default is
            "File" in most cases, or "Memory" if the interpreter has no data directory.

            Beyond that, *cache_options* may include any valid options to the new() method of the
            driver. e.g. for the "File" driver, valid options include "expires_in" and "depth".

    cache_self ([expires_in => '...'], [key => '...'], [get_options], [cache_options])
        "$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__'.

        To cache the component's output:

            <%init>
            return if $m->cache_self(expire_in => '10 sec'[, key => 'fookey']);
            ... <rest of init> ...
            </%init>

        To cache the component's scalar return value:

            <%init>
            my ($result, $cached) = $m->cache_self(expire_in => '5 min'[, key => 'fookey']);

            return $result if $cached;
            ... <rest of init> ...
            </%init>

        To cache the component's list return value:

            <%init>
            my (@retval) = $m->cache_self(expire_in => '3 hours'[, key => 'fookey']);

            return @retval if pop @retval;
            ... <rest of init> ...
            </%init>

        We call "pop" on @retval to remove the mandatory '1' at the end of the list.

        If a component has a "<%filter>" block, then the *filtered* output is cached.

        Note: users upgrading from 1.0x and earlier can continue to use the old "$m->cache_self" API
        by setting data_cache_api to '1.0'. This support will be removed at a later date.

        See the the DATA CACHING section of the developer's manual section for more details on how
        to exercise finer control over caching.

    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. Returns undef or an empty
        list, depending on context, if the specified stack level does not exist.

    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

        Returns undef or an empty list, depending on context, if the specified stack level does not
        exist.

    caller
        A synonym for "$m->callers(1)", i.e. the component that called the currently executing
        component.

    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
        section of the developer's manual for examples.

    call_self (output, return, error, tag)
        This method allows a component to call itself so that it can filter both its output and
        return values. It is fairly advanced; for most purposes the "<%filter>" tag will be
        sufficient and simpler.

        "$m->call_self" takes four arguments, all of them optional.

        output - scalar reference that will be populated with the component output.
        return - scalar reference that will be populated with the component return value.
        error - scalar reference that will be populated with the error thrown by the component, if
        any. If this parameter is not defined, then call_self will not catch errors.
        tag - a name for this call_self invocation; can almost always be omitted.

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

            <%init>
            my ($output, $retval);
            if ($m->call_self(\$output, \$retval)) {
                $m->print($output);
                return $retval;
            }
            ...

        Here is a simple output filter that makes the output all uppercase. Note that we ignore both
        the original and the final return value.

            <%init>
            my ($output, $error);
            if ($m->call_self(\$output, undef)) {
                $m->print(uc $output);
                return;
            }
            ...

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

            <%init>
            my ($output, undef, $error);
            if ($m->call_self(\$output, undef, \$error)) {
                if ($error) {
                    # check $error and do something with it
                }
                $m->print($output);
                return;
            }
            ...

    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 is, of course, 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".

        As of 1.10, component calls can accept an initial hash reference of *modifiers*. The only
        currently supported modifier is "store", which stores the component's output in a scalar
        reference. For example:

          my $buf;
          my $return = $m->comp( { store => \$buf }, '/some/comp', type => 'big' );

        This mostly duplicates the behavior of *scomp*, but can be useful in rare cases where you
        need to capture both a component's output and return value.

        This modifier can be used with the <& &> tag as well, for example:

          <& { store => \$buf }, '/some/comp', size => 'medium' &>

    comp_exists (comp_path)
        Returns 1 if *comp_path* is the path of an existing component, 0 otherwise. *comp_path* may
        be any path accepted by comp or fetch_comp, including method or subcomponent paths.

        Depending on implementation, <comp_exists> may try to load the component referred to by the
        path, and may throw an error if the component contains a syntax error.

    content
        Evaluates the content (passed between <&| comp &> and </&> tags) of the current component,
        and returns the resulting text.

        Returns undef if there is no content.

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

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

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

    current_comp
        Returns the current component object.

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

    declined ([$err])
        Returns true or undef indicating whether the specified $err was generated by "decline". If
        no $err was passed, uses $@.

    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.

    exec (comp, args...)
        Starts the request by executing the top-level component and arguments. This is normally
        called for you on the main request, but you can use it to execute subrequests.

        A request can only be executed once; e.g. it is an error to call this recursively on the
        same request.

    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 autohandlers section of the
        developer's manual for usage and examples.

    fetch_next_all
        Returns a list of the remaining components in the content wrapping chain. Usually called
        from an autohandler. See the autohandlers section of the developer's manual for usage and
        examples.

    file (filename)
        Returns the contents of *filename* as a string. If *filename* is a relative path, Mason
        prepends the current component directory.

    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.

        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.

    instance
        This class method returns the "HTML::Mason::Request" currently in use. If called when no
        Mason request is active it will return "undef".

        If called inside a subrequest, it returns the subrequest object.

    interp
        Returns the Interp object associated with this request.

    make_subrequest (comp => path, args => arrayref, other parameters)
        This method creates a new Request object which inherits its parent's settable properties,
        such as autoflush and out_method. These values may be overridden by passing parameters to
        this method.

        The "comp" parameter is required, while all other parameters are optional. It may be
        specified as an absolute path or as a path relative to the current component.

        See the subrequests section of the developer's manual for more information about
        subrequests.

    log Returns a "Log::Any" logger with a log category specific to the current component. The
        category for a component "/foo/bar" would be "HTML::Mason::Component::foo::bar".

    notes (key, value)
        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.

    out (string)
        A synonym for "$m->print".

    print (string)
        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".

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

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

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

    scomp (comp, args...)
        Like comp, but returns the component output as a string instead of printing it. (Think
        sprintf versus printf.) The component's return value is discarded.

    subexec (comp, args...)
        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.

    time
        Returns the interpreter's notion of the current time (deprecated).

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.

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

CGI-ONLY METHODS
    This additional method is available when running Mason with the CGIHandler module.

    cgi_request
        Returns the Apache request emulation object, which is available as $r inside components.

        See the CGIHandler docs for more details.

APACHE- OR CGI-ONLY METHODS
    This method is available when Mason is running under either the ApacheHandler or CGIHandler
    modules.

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

    redirect ($url, [$status])
        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:

          eval {
              ...
          };

          die $@ if $m->aborted;

          # handle other exceptions