.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Mason::Request 3pm" .TH Mason::Request 3pm "2012-05-02" "perl v5.14.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Mason::Request \- Mason Request Class .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& $m\->abort (...) \& $m\->comp (...) \& etc. .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Mason::Request represents a single request for a page, and is the access point for most Mason features not provided by syntactic tags. .PP A Mason request is created when you call \f(CW\*(C`$interp\->run\*(C'\fR, 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. .PP Inside a component you can access the current request object via the global \&\f(CW$m\fR. Outside of a component, you can use the class method \&\f(CW\*(C`Mason::Request\->current_request\*(C'\fR. .SH "COMPONENT PATHS" .IX Header "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). .PP Component paths are like \s-1URL\s0 paths, and always use a forward slash (/) as the separator, regardless of what your operating system uses. .SH "PARAMETERS TO THE \fInew()\fP CONSTRUCTOR" .IX Header "PARAMETERS TO THE new() CONSTRUCTOR" These parameters would normally be passed in an initial hashref to \f(CW\*(C`$interp\->run\*(C'\fR, \f(CW\*(C`$m\->visit\*(C'\fR, or \f(CW\*(C`$m\->go\*(C'\fR. .IP "out_method" 4 .IX Item "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 \&\*(L"mason.out\*(R": .Sp .Vb 3 \& open(my $fh, ">", "mason.out); \& ... \& out_method => sub { $fh\->print($_[0]) } .Ve .Sp When \f(CW\*(C`out_method\*(C'\fR is unspecified, the output can be obtained from the Mason::Result object returned from \f(CW\*(C`$interp\->run\*(C'\fR. .SH "PUBLIC METHODS" .IX Header "PUBLIC METHODS" .IP "abort ()" 4 .IX Item "abort ()" Ends the current request, finishing the page without returning through components. .Sp \&\f(CW\*(C`abort\*(C'\fR is implemented by throwing an \f(CW\*(C`Mason::Exception::Abort\*(C'\fR object and can thus be caught by \f(CW\*(C`eval\*(C'\fR. The \f(CW\*(C`aborted\*(C'\fR method is a shortcut for determining whether a caught error was generated by \f(CW\*(C`abort\*(C'\fR. .IP "aborted ([$err])" 4 .IX Item "aborted ([$err])" Returns true or undef indicating whether the specified \f(CW$err\fR was generated by \&\f(CW\*(C`abort\*(C'\fR. If no \f(CW$err\fR was passed, uses \f(CW$@\fR. .Sp In this Try::Tiny code, we catch and process fatal errors while letting \f(CW\*(C`abort\*(C'\fR exceptions pass through: .Sp .Vb 6 \& try { \& code_that_may_fail_or_abort() \& } catch { \& die $_ if $m\->aborted($_); \& # handle fatal errors... \& }; .Ve .IP "add_cleanup (code)" 4 .IX Item "add_cleanup (code)" Add a code reference to be executed when the request is cleaned up. .IP "clear_and_abort ()" 4 .IX Item "clear_and_abort ()" This method is syntactic sugar for calling \f(CW\*(C`clear_buffer()\*(C'\fR and then \&\f(CW\*(C`abort()\*(C'\fR. 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. .IP "capture (code)" 4 .IX Item "capture (code)" Execute the \fIcode\fR, capturing and returning any Mason output instead of outputting it. e.g. the following .Sp .Vb 1 \& my $buf = $m\->capture(sub { $m\->comp(\*(Aq/foo\*(Aq) }); .Ve .Sp is equivalent to .Sp .Vb 1 \& my $buf = $m\->scomp(\*(Aq/foo\*(Aq); .Ve .IP "clear_buffer ()" 4 .IX 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. .Sp clear_buffer is, of course, thwarted by flush_buffer. .IP "comp (path[, params ...])" 4 .IX Item "comp (path[, params ...])" Creates a new instance of the component designated by \fIpath\fR, and calls its \&\f(CW\*(C`main\*(C'\fR method. \fIparams\fR, if any, are passed to the constructor. .Sp The \f(CW\*(C`<& &>\*(C'\fR tag provides a shortcut for \f(CW\*(C`$m\->comp\*(C'\fR. .IP "comp_exists (path)" 4 .IX Item "comp_exists (path)" Makes the component \fIpath\fR absolute if necessary, and calls Interp comp_exists to determine whether a component exists at that path. .IP "current_comp_class ()" 4 .IX Item "current_comp_class ()" Returns the current component class. This is determined by walking up the Perl \&\fIcaller()\fR stack until the first Mason::Component subclass is found. .IP "current_request ()" 4 .IX Item "current_request ()" This class method returns the \f(CW\*(C`Mason::Request\*(C'\fR currently in use. If called when no Mason request is active it will return \f(CW\*(C`undef\*(C'\fR. .IP "construct (path[, params ...])" 4 .IX Item "construct (path[, params ...])" Constructs and return a new instance of the component designated by \fIpath\fR. \&\fIparams\fR, if any, are passed to the constructor. Throws an error if \fIpath\fR does not exist. .IP "decline ()" 4 .IX Item "decline ()" Clears the output buffer and tries the current request again, but acting as if the previously chosen page component(s) do not exist. .Sp For example, if the following components exist: .Sp .Vb 3 \& /news/sports.mc \& /news/dhandler.mc \& /dhandler.mc .Ve .Sp then a request for path \f(CW\*(C`/news/sports\*(C'\fR will initially resolve to \&\f(CW\*(C`/news/sports.mc\*(C'\fR. A call to \f(CW\*(C`$m\->decline\*(C'\fR would restart the request and resolve to \f(CW\*(C`/news/dhandler.mc\*(C'\fR, a second \f(CW\*(C`$m\->decline\*(C'\fR would resolve to \&\f(CW\*(C`/dhandler.mc\*(C'\fR, and a third would throw a \*(L"not found\*(R" error. .IP "filter (filter_expr, [filter_expr...], string|coderef)" 4 .IX Item "filter (filter_expr, [filter_expr...], string|coderef)" Applies one or more filters to a string or to a coderef that returns a string. .Sp .Vb 1 \& my $filtered_string = $m\->filter($.Trim, $.NoBlankLines, $string); .Ve .IP "flush_buffer ()" 4 .IX Item "flush_buffer ()" Flushes the main output buffer. Anything currently in the buffer is sent to the request's out_method. .Sp Note that anything output within a \f(CW\*(C`$m\->scomp\*(C'\fR or \f(CW\*(C`$m\->capture\*(C'\fR will not have made it to the main output buffer, and thus cannot be flushed. .IP "go ([request params], path, args...)" 4 .IX Item "go ([request params], path, args...)" Performs an internal redirect. Clears the output buffer, runs a new request for the given \fIpath\fR and \fIargs\fR, and then aborts when that request is done. .Sp The first argument may optionally be a hashref of parameters which are passed to the \f(CW\*(C`Mason::Request\*(C'\fR constructor. .Sp See also visit. .IP "interp ()" 4 .IX Item "interp ()" Returns the Interp object associated with this request. .IP "load (path)" 4 .IX Item "load (path)" Makes the component \fIpath\fR absolute if necessary, and calls Interp load to load the component class associated with the path. .IP "log ()" 4 .IX Item "log ()" Returns a \f(CW\*(C`Log::Any\*(C'\fR logger with a log category specific to the current component. The category for a component \*(L"/foo/bar\*(R" would be \&\*(L"Mason::Component::foo::bar\*(R". .IP "notes ([key[, value]])" 4 .IX Item "notes ([key[, value]])" The \f(CW\*(C`notes()\*(C'\fR method provides a place to store application data between components \- essentially, a hash which persists for the duration of the request. .Sp \&\f(CW\*(C`notes($key, $value)\*(C'\fR stores a new entry in the hash; \f(CW\*(C`notes($key)\*(C'\fR returns a previously stored value; and \f(CW\*(C`notes()\*(C'\fR without any arguments returns a reference to the entire hash of key-value pairs. .Sp Consider storing this kind of data in a read-write attribute of the page component. .IP "print (string)" 4 .IX Item "print (string)" Add the given \fIstring\fR to the Mason output buffer. This happens implicitly for all content placed in the main component body. .IP "page ()" 4 .IX Item "page ()" Returns the page component originally called in the request. .IP "path_info ()" 4 .IX Item "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 \*(L"/foo.mc\*(R", the path_info is \*(L"bar/baz\*(R". For an exact match, it will contain the empty string (never undef), so you can determine whether there's a path_info with .Sp .Vb 1 \& if ( length($m\->path_info) ) .Ve .IP "rel_to_abs (path)" 4 .IX Item "rel_to_abs (path)" Converts a component \fIpath\fR to absolute form based on the current component, if it does not already begin with a '/'. .IP "request_args ()" 4 .IX Item "request_args ()" Returns the original hashref of arguments passed to the request, e.g. via \f(CW\*(C`$interp\->run\*(C'\fR. .IP "request_path ()" 4 .IX Item "request_path ()" Returns the original path passed to the request, e.g. in \f(CW\*(C`$interp\->run\*(C'\fR. .IP "scomp (comp, args...)" 4 .IX Item "scomp (comp, args...)" Like comp, but returns the component output as a string instead of printing it. (Think sprintf versus printf.) .Sp See also capture. .IP "visit ([request params], path, args...)" 4 .IX Item "visit ([request params], path, args...)" Performs a subrequest with the given \fIpath\fR and \fIargs\fR, with output being sent to the current output buffer. .Sp The first argument may optionally be a hashref of parameters which are passed to the \f(CW\*(C`Mason::Request\*(C'\fR constructor. e.g. to capture the output of the subrequest: .Sp .Vb 1 \& $m\->visit({out_method => \emy $buffer}, ...); .Ve .Sp See also go. .SH "MODIFIABLE METHODS" .IX Header "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. .IP "cleanup_request ()" 4 .IX Item "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. .ie n .IP "construct_page_component ($compc, $args)" 4 .el .IP "construct_page_component ($compc, \f(CW$args\fR)" 4 .IX Item "construct_page_component ($compc, $args)" Constructs the page component of class \fI\f(CI$compc\fI\fR, with hashref of constructor arguments \fI\f(CI$args\fI\fR. .IP "match_request_path ($request_path)" 4 .IX Item "match_request_path ($request_path)" Given a top level \fI\f(CI$request_path\fI\fR, return a corresponding component path or undef if none was found. Search includes dhandlers and index files. See Mason::Manual::RequestDispatch. .IP "process_output ($outref)" 4 .IX Item "process_output ($outref)" This method is called on the output buffer right before it is sent to its final destination. \fI\f(CI$outref\fI\fR is a reference to the output string; the method can modify it as desired. .IP "run ($request_path, args)" 4 .IX Item "run ($request_path, args)" Runs the request with \fI\f(CI$request_path\fI\fR and \fIargs\fR, where the latter can be either a hashref or a hash. This is generally called via << \f(CW$interp\fR\->run >>. .IP "with_tied_print ($code)" 4 .IX Item "with_tied_print ($code)" Execute the given \fI\f(CI$code\fI\fR with the current selected filehandle ('print') tied to the Mason output stream. You could disable the filehandle selection by overriding this to just call \fI\f(CI$code\fI\fR. .SH "SEE ALSO" .IX Header "SEE ALSO" Mason .SH "AUTHOR" .IX Header "AUTHOR" Jonathan Swartz .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2011 by Jonathan Swartz. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.