Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
HTML::Mason::Request(3User Contributed Perl DocumentatiHTML::Mason::Request(3)

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.

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

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

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

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

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

	   o   '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

	   o   brief - just the	error message with no trace information

	   o   text - a	multi-line text	format

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

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

	   o   At the beginning	of a request, the base component is
	       initialized to the requested component ("$m->request_comp()").

	   o   When you	call a regular component via a path, the base
	       component changes to the	called component.

	   o   When you	call a component method	via a path (/foo/bar:baz), the
	       base component changes to the method's owner.

	   o   The base	component does not change when:

	       o   a component call is made to a component object

	       o   a component call is made to SELF:x or PARENT:x or REQUEST:x

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

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

	   o   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

perl v5.32.0			  2020-05-16	       HTML::Mason::Request(3)

NAME | SYNOPSIS | DESCRIPTION | COMPONENT PATHS | PARAMETERS TO THE new() CONSTRUCTOR | ACCESSOR METHODS | OTHER METHODS | APACHE-ONLY METHODS | CGI-ONLY METHODS | APACHE- OR CGI-ONLY METHODS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=HTML::Mason::Request&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help