Mason::Request(3pm)

💖 Mason::Request 💖

okay bestie, so this is the manual for Mason::Request — the Mason Request Class — and it's genuinely one of the most useful pages in the whole Mason universe, no cap. Let's get into it. 🦋

---

✨ SYNOPSIS ✨

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

like... that's the whole vibe. a taste. an amuse-bouche. keep reading. 🍓

---

🌸 DESCRIPTION 🌸

Mason::Request represents a single request for a page, and it's the access point for basically all the Mason features that the syntactic tags don't hand you directly. it's giving main character energy for your whole request lifecycle, fr fr.

a Mason request gets created when you call $interp->run, or — in a web environment — once for every new web request. and a brand new (sub-)request gets created too whenever you call visit or go on the current request. so many little requests, all iconic. ✨

inside a component, you reach the current request object through the global $m. outside of a component, you use the class method Mason::Request->current_request. two doors, same room. 🚪

---

🧭 COMPONENT PATHS 🧭

okay so these methods — comp, comp_exists, construct, go, load, and visit — all take a component path argument. if that path doesn't start with a /, it gets made absolute based on the current component path (using rel_to_abs). lowkey magical, but that's literally how it works.

and component paths? they're like URL paths. they always use a forward slash (/) as the separator, no matter what your operating system thinks the separator should be. your OS does not get a vote here. 💅

---

🎀 PARAMETERS TO THE new() CONSTRUCTOR 🎀

these params would normally be passed in an initial hashref to $interp->run, $m->visit, or $m->go. so like, you don't usually call new() yourself, you just hand these over to the cool kids. 😌

• out_method — tells Mason where to send the page output. if out_method is a scalar reference, output gets 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]) }

and when out_method is unspecified? the output can be obtained from the Mason::Result object returned from $interp->run. so you're never left hanging. 🫶

---

👑 PUBLIC METHODS 👑

abort ()

ends the current request, finishing the page without returning through components. it just... dips. bye. ✌️

abort is implemented by throwing an Mason::Exception::Abort object, which means it can be caught by eval. and the aborted method is your shortcut for figuring out whether a caught error was generated by abort. convenient queen behaviour.

aborted ([$err])

returns true or undef telling you whether the specified $err was generated by abort. if no $err was passed, it uses $@. (sneaky. love that for us.)

in this Try::Tiny code, we catch and process fatal errors while letting abort exceptions pass right on 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. tiny little janitor, doing the most. 🧹

clear_and_abort ()

this method is syntactic sugar for calling clear_buffer() and then abort(). so if you're aborting the request because of an error (or, in a web environment, to do a redirect), you'll often want to clear the buffer first so that any output generated up to that point does not get sent to the client. goodbye to that half-rendered page nobody needed. 💀

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. mid-request plot twist, and we wipe the tape. 🎬

clear_buffer is, of course, thwarted by flush_buffer. those two are enemies. it's giving rival houses.

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. iykyk. ✨

comp_exists (path)

makes the component path absolute if necessary, and calls Interp comp_exists to determine whether a component exists at that path. yes/no, does it exist, answer the question. 🎯

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. climbing the family tree until we find a real one. 🌳

current_request ()

this class method returns the Mason::Request currently in use. if called when no Mason request is active, it will return undef. sad. empty. nobody home. 🙈

construct (path[, params ...])

constructs and returns 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. no path, no component, no mercy.

decline ()

clears the output buffer and tries the current request again, but acting as if the previously chosen page component(s) do not exist. it's the "nvm pretend i didn't see that" of Mason. 😭

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. three strikes and you're out, bestie.

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. sending it. shipping it. it's out of our hands now. 📤

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. don't even try, babe.

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. a full glow-up in the middle of a request.

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. your interp. your ride or die.

load (path)

makes the component path absolute if necessary, and calls Interp load to load the component class associated with the path. pulling the class into the building. 🫶

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. very specific. very slay.

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. it's the group chat of your 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. just a suggestion, bestie. 🌸

print (string)

add the given string to the Mason output buffer. this happens implicitly for all content placed in the main component body. yes, every time you just type text in a component, this is quietly happening behind the scenes. iconic, honestly.

page ()

returns the page component originally called in the request. the original. the blueprint. the main character. 👑

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 /. relative to absolute, glow up complete. ✨

request_args ()

returns the original hashref of arguments passed to the request, e.g. via $interp->run. the receipts. 🧾

request_path ()

returns the original path passed to the request, e.g. in $interp->run. the receipts, but the path edition.

scomp (comp, args...)

like comp, but returns the component output as a string instead of printing it. (think sprintf versus printf.) catch it in a variable, do whatever you want with it, it's yours now. 🎀

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. a little request inside your request. request-ception. 🌈

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. so like, hands off unless you know what you're doing, but if you do know, go off. 💅

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. the final sweep before closing time.

construct_page_component ($compc, $args)

constructs the page component of class $compc, with hashref of constructor arguments $args. building the page. literally.

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. it's the matchmaker of paths. 💘

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. last chance to edit before it goes out into the world. the final photoshop pass. 📸

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. tie the filehandle, unleash the code, chaos ensues (in a good way). 🧚

---

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

---

okay that's the whole page, you ate it, you read it, you understood it. and just so you know who to thank: this was perl v5.34.0, dated 2022-05-27, and it's the Mason::Request(3pm) page. mwah. 💖✨🎀🦋🌸💅🫶