HTML::Mason::Request - Mason Request Class

- NAME
- SYNOPSIS
- DESCRIPTION
- COMPONENT PATHS
- METHODS
- APACHE-ONLY METHODS
- AUTHOR
- SEE ALSO

# 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 comp, comp_exists, fetch_comp, and process_comp_path 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

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
  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 Object-Oriented Techniques for examples of usage.

cache ([action=>'retrieve|store|expire|keys'], [key=>name], [value=>data], [keep_in_memory=>0|1], [expire options...])
  `$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 data caching 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.

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...])
  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 Component Developer's Guide for examples.

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
  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 Component Developer's Guide 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 Component Developer's Guide for usage and examples.

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

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 `$m->call_next` chain.

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

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 HTML::Mason::ApacheHandler documentation for more details.

# AUTHOR

Jonathan Swartz, swartz@pobox.com

# SEE ALSO

HTML::Mason::Component HTML::Mason::ApacheHandler