=head1 NAME

HTML::Mason::Request - Mason Request Class

=head1 SYNOPSIS

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

=head1 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 C<$m>.

=head1 COMPONENT PATHS

The methods L<Request/comp>, L<Request/comp_exists>, L<Request/fetch_comp>, and
L<Request/process_comp_path> take a component path as argument.

=over

=item *

If the path is absolute (starting with a '/'), then the component is
found relative to the component root.

=item *

If the path is relative (no leading '/'), then the component is found
relative to the current component directory.

=item *

If the path matches both a subcomponent and file-based component, the
subcomponent takes precedence.

=back

=head1 METHODS

=over

=for html <a name="item_abort">

=item abort ([return value])

Ends the current request, finishing the page without returning
through components. The optional argument specifies the return
value from C<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 C<E<lt>%filterE<gt>> sections will
not be applied to the output after an abort.  This is a known bug but
there is no easy workaround.

The methods C<aborted> and C<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 C<$@>.

=for html <a name="item_aborted">

=item aborted

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

=for html <a name="item_aborted_value">

=item aborted_value

Returns the argument passed to C<abort> when the request was
aborted. Returns undef if the request was not aborted or was aborted
without an argument.

=for html <a name="item_base_comp">

=item base_comp

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, C<base_comp> is dynamically set to that
component until call_method exits. See L<Devel/Object-Oriented
Techniques> for examples of usage.

=for html <a name="item_cache">

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

C<$m-E<gt>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 L<Devel/data caching>
section of the I<Component Developer's Guide> for examples
and caching strategies.

The argument to I<action> is one of:

o I<retrieve>: returns the cache value if successful, or C<undef>
if there was no value or if it has expired.

o I<store>: stores a new cache value under the given key.  Default key
is 'main'.  Returns the value being stored if successful.

o I<expire>: expires a given cache value or values.
key may be a single key or a list reference. Default key is 'main'.

o I<keys>: returns a list of all the keys in the cache.

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

I<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 I<expire_at>: takes an absolute expiration time, in Perl time() format
(number of seconds since the epoch)

o I<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 I<expire_next>: takes a string, either 'hour' or 'day'. It indicates
an expiration time at the top of the next hour or day.

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

=for html <a name="item_cache_self">

=item cache_self (... same as cache options...)

Uses C<$m-E<gt>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
C<E<lt>%init%E<gt>> 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.

C<$m-E<gt>cache_self> handles both the retrieve and store, so you can pass
both kinds of options to it. See C<$m-E<gt>cache> for an explanation of
options.

C<$m-E<gt>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 C<$m-E<gt>cache_self> for the first time.

o C<$m-E<gt>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 C<$m-E<gt>cache_self> which immediately returns 0 this time.

o foo goes about its business and generates content into the C<$m-E<gt>cache_self> buffer.

o When control is returned to C<$m-E<gt>cache_self>, it stores the content and
return value in the cache and also outputs the content normally.
Finally C<$m-E<gt>cache_self> returns the list (retval,1) which in turn
causes foo to return immediately.

=for html <a name="item_caller_args">

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

=for html <a name="item_callers">

=item 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

=for html <a name="item_call_next">

=item 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 C<$m-E<gt>comp> in terms of return value and
scalar/list context.  See the L<Devel/autohandlers> section of the
I<Component Developer's Guide> for examples.

=for html <a name="item_clear_buffer">

=item 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
C<flush_buffer>.

=for html <a name="item_comp">

=item comp (comp, args...)

Calls the component designated by I<comp> with the specified
option/value pairs. I<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 C<$m-E<gt>comp> call.

The <& &> tag provides a convenient shortcut for C<$m-E<gt>comp>.

=for html <a name="item_comp_exists">

=item comp_exists (comp_path)

Returns 1 if I<comp_path> is the path of an existing component, 0 otherwise. 

=for html <a name="item_count">

=item count

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

=for html <a name="item_current_comp">

=item current_comp

Returns the current component object.

=for html <a name="item_decline">

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

=for html <a name="item_depth">

=item depth

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

=for html <a name="item_dhandler_arg">

=item dhandler_arg

If the request has been handled by a dhandler, this method returns the
remainder of the URI or C<Interp::exec> path when the dhandler directory is
removed. Otherwise returns undef.

C<dhandler_arg> may be called from any component in the request, not just
the dhandler.

=for html <a name="item_fetch_comp">

=item fetch_comp (comp_path)

Given a I<comp_path>, returns the corresponding component object or
undef if no such component exists.

=for html <a name="item_fetch_next">

=item 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 L<Devel/autohandlers> section of the I<Component Developer's
Guide> for usage and examples.

=for html <a name="item_fetch_next_all">

=item fetch_next_all

Returns a list of the remaining components in the content wrapping
chain. Usually called from an autohandler.  See the
L<Devel/autohandlers> section of the I<Component Developer's Guide>
for usage and examples.

=for html <a name="item_file">

=item file (filename)

Returns the contents of filename as a string. I<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.

=for html <a name="item_file_root">

=item file_root

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

=for html <a name="item_flush_buffer">

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

=for html <a name="item_interp">

=item interp

Returns the Interp object associated with this request.

=for html <a name="item_out">

=item out (string)

Print the given I<string>. Rarely needed, since normally all HTML is just
placed in the component body and output implicitly. C<$m-E<gt>out> is useful
if you need to output something in the middle of a Perl block.

C<$m-E<gt>out> should be used instead of C<print> or C<$r-E<gt>print>,
since C<$m-E<gt>out> may be redirected or buffered depending on the
current state of the interpreter.

=for html <a name="item_parser">

=item parser

Returns the Parser object associated with this request.

=for html <a name="item_process_comp_path">

=item process_comp_path (comp_path)

Given a I<comp_path>, returns the corresponding absolute component path.

=for html <a name="item_scomp">

=item scomp (comp, args...)

Like C<$m-E<gt>comp>, but returns the component output as a string
instead of printing it. (Think sprintf versus printf.) The
component's return value is discarded.

=for html <a name="item_time">

=item time

Returns the interpreter's notion of the current time in Perl time()
format (number of seconds since the epoch).

By using C<$m-E<gt>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.

=for html <a name="item_top_args">

=item top_args

Returns the arguments originally passed to the top level component
(see L<Request/top_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.

=for html <a name="item_top_comp">

=item top_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
C<$m-E<gt>call_next> chain.

=back

=head1 APACHE-ONLY METHODS

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

=over

=for html <a name="item_ah">

=item ah

Returns the ApacheHandler object associated with this request.

=for html <a name="item_apache_req">

=item apache_req

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

=for html <a name="item_cgi_object">

=item 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 C<args_method> parameter.  If you are using the
'mod_perl' args method, then calling this method is a fatal error.
See the L<HTML::Mason::ApacheHandler> documentation for more details.

=back

=head1 AUTHOR

Jonathan Swartz, swartz@pobox.com

=head1 SEE ALSO

L<HTML::Mason::Component>
L<HTML::Mason::ApacheHandler>

=cut
