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

FreeBSD Manual Pages

  
 
  

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

NAME
       Mason::Request -	Mason Request Class

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

DESCRIPTION
       Mason::Request represents a single request for a	page, and is the
       access point for	most Mason features not	provided by syntactic tags.

       A Mason request is created when you call	"$interp->run",	or in a	web
       environment, for	each new web request. A	new (sub-)request is also
       created when you	call visit or go on the	current	request.

       Inside a	component you can access the current request object via	the
       global $m.  Outside of a	component, you can use the class method
       "Mason::Request->current_request".

COMPONENT PATHS
       The methods comp, comp_exists, construct, go, load, and visit take a
       component path argument.	If the path does not begin with	a '/', then it
       is made absolute	based on the current component path (using
       rel_to_abs).

       Component paths are like	URL paths, and always use a forward slash (/)
       as the separator, regardless of what your operating system uses.

PARAMETERS TO THE new()	CONSTRUCTOR
       These parameters	would normally be passed in an initial hashref to
       "$interp->run", "$m->visit", or "$m->go".

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

	       open(my $fh, ">", "mason.out);
	       ...
	       out_method => sub { $fh->print($_[0]) }

	   When	"out_method" is	unspecified, the output	can be obtained	from
	   the Mason::Result object returned from "$interp->run".

PUBLIC METHODS
       abort ()
	   Ends	the current request, finishing the page	without	returning
	   through components.

	   "abort" is implemented by throwing an "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".

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

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

	       try {
		   code_that_may_fail_or_abort()
	       } catch {
		   die $_ if $m->aborted($_);
		   # handle fatal errors...
	       };

       add_cleanup (code)
	   Add a code reference	to be executed when the	request	is cleaned up.

       clear_and_abort ()
	   This	method is syntactic sugar for calling "clear_buffer()" and
	   then	"abort()".  If you are aborting	the request because of an
	   error (or, in a web environment, to do a redirect), you will	often
	   want	to clear the buffer first so that any output generated up to
	   that	point is not sent to the client.

       capture (code)
	   Execute the code, capturing and returning any Mason output instead
	   of outputting it. e.g. the following

	       my $buf = $m->capture(sub { $m->comp('/foo') });

	   is equivalent to

	       my $buf = $m->scomp('/foo');

       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 (path[, params ...])
	   Creates a new instance of the component designated by path, and
	   calls its "main" method. params, if any, are	passed to the
	   constructor.

	   The "<& &>" tag provides a shortcut for "$m->comp".

       comp_exists (path)
	   Makes the component path absolute if	necessary, and calls Interp
	   comp_exists to determine whether a component	exists at that path.

       current_comp_class ()
	   Returns the current component class.	This is	determined by walking
	   up the Perl caller()	stack until the	first Mason::Component
	   subclass is found.

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

       construct (path[, params	...])
	   Constructs and return a new instance	of the component designated by
	   path.  params, if any, are passed to	the constructor. Throws	an
	   error if path does not exist.

       decline ()
	   Clears the output buffer and	tries the current request again, but
	   acting as if	the previously chosen page component(s)	do not exist.

	   For example,	if the following components exist:

	       /news/sports.mc
	       /news/dhandler.mc
	       /dhandler.mc

	   then	a request for path "/news/sports" will initially resolve to
	   "/news/sports.mc".  A call to "$m->decline" would restart the
	   request and resolve to "/news/dhandler.mc", a second	"$m->decline"
	   would resolve to "/dhandler.mc", and	a third	would throw a "not
	   found" error.

       filter (filter_expr, [filter_expr...], string|coderef)
	   Applies one or more filters to a string or to a coderef that
	   returns a string.

	       my $filtered_string = $m->filter($.Trim,	$.NoBlankLines,	$string);

       flush_buffer ()
	   Flushes the main output buffer. Anything currently in the buffer is
	   sent	to the request's out_method.

	   Note	that anything output within a "$m->scomp" or "$m->capture"
	   will	not have made it to the	main output buffer, and	thus cannot be
	   flushed.

       go ([request params], path, args...)
	   Performs an internal	redirect. Clears the output buffer, runs a new
	   request for the given path and args,	and then aborts	when that
	   request is done.

	   The first argument may optionally be	a hashref of parameters	which
	   are passed to the "Mason::Request" constructor.

	   See also visit.

       interp ()
	   Returns the Interp object associated	with this request.

       load (path)
	   Makes the component path absolute if	necessary, and calls Interp
	   load	to load	the component class associated with the	path.

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

       notes ([key[, value]])
	   The "notes()" method	provides a place to store application data
	   between components -	essentially, a hash which persists for the
	   duration of the request.

	   "notes($key,	$value)" stores	a new entry in the hash; "notes($key)"
	   returns a previously	stored value; and "notes()" without any
	   arguments returns a reference to the	entire hash of key-value
	   pairs.

	   Consider storing this kind of data in a read-write attribute	of the
	   page	component.

       print (string)
	   Add the given string	to the Mason output buffer. This happens
	   implicitly for all content placed in	the main component body.

       page ()
	   Returns the page component originally called	in the request.

       path_info ()
	   Returns the remainder of the	request	path beyond the	path of	the
	   page	component, with	no leading slash. e.g. If a request for
	   '/foo/bar/baz' resolves to "/foo.mc", the path_info is "bar/baz".
	   For an exact	match, it will contain the empty string	(never undef),
	   so you can determine	whether	there's	a path_info with

	       if ( length($m->path_info) )

       rel_to_abs (path)
	   Converts a component	path to	absolute form based on the current
	   component, if it does not already begin with	a '/'.

       request_args ()
	   Returns the original	hashref	of arguments passed to the request,
	   e.g.	via "$interp->run".

       request_path ()
	   Returns the original	path passed to the request, e.g. in
	   "$interp->run".

       scomp (comp, args...)
	   Like	comp, but returns the component	output as a string instead of
	   printing it.	(Think sprintf versus printf.)

	   See also capture.

       visit ([request params],	path, args...)
	   Performs a subrequest with the given	path and args, with output
	   being sent to the current output buffer.

	   The first argument may optionally be	a hashref of parameters	which
	   are passed to the "Mason::Request" constructor. e.g.	to capture the
	   output of the subrequest:

	       $m->visit({out_method =>	\my $buffer}, ...);

	   See also go.

MODIFIABLE METHODS
       These methods are not intended to be called externally, but may be
       useful to modify	with method modifiers in plugins and subclasses. Their
       APIs will be kept as stable as possible.

       cleanup_request ()
	   A place to perform cleanup duties when the request finishes or dies
	   with	an error, even if the request object is	not immediately
	   destroyed. Includes anything	registered with	add_cleanup.

       construct_page_component	($compc, $args)
	   Constructs the page component of class $compc, with hashref of
	   constructor arguments $args.

       match_request_path ($request_path)
	   Given a top level $request_path, return a corresponding component
	   path	or undef if none was found. Search includes dhandlers and
	   index files.	See Mason::Manual::RequestDispatch.

       process_output ($outref)
	   This	method is called on the	output buffer right before it is sent
	   to its final	destination. $outref is	a reference to the output
	   string; the method can modify it as desired.

       run ($request_path, args)
	   Runs	the request with $request_path and args, where the latter can
	   be either a hashref or a hash. This is generally called via <<
	   $interp->run	>>.

       with_tied_print ($code)
	   Execute the given $code with	the current selected filehandle
	   ('print') tied to the Mason output stream. You could	disable	the
	   filehandle selection	by overriding this to just call	$code.

SEE ALSO
       Mason

AUTHOR
       Jonathan	Swartz <swartz@pobox.com>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2012 by Jonathan Swartz.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

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

NAME | SYNOPSIS | DESCRIPTION | COMPONENT PATHS | PARAMETERS TO THE new() CONSTRUCTOR | PUBLIC METHODS | MODIFIABLE METHODS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

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

home | help