Mason:...l::FAQ(3pm)

💖 NAME 💖

So bestie, this is Mason::Manual::FAQ — literally the frequently asked questions page for Mason, aka the place you go when you're mid-crisis at 2am and just need somebody to tell you why your binary file is corrupted. (Spoiler: it's whitespace. It's always whitespace. 😭)

---

✨ COMPONENTS ✨

🫶 Can I create global variable(s) that can be seen from all components?

Okay so here's the tea: every Mason component runs in its own package, so if you just set a regular global in one of them, the others literally cannot see it. It's giving isolated. 🙈

But!! You can use allow_globals and set_global to create globals that all components can access. Slay. 💅

🦋 Why does my output have extra newlines/whitespace and how can I get rid of it?

Go read Whitespace And Newlines in the syntax manual, it explains everything.

To suppress the extra newlines, you've got two iconic options:

• slap a backslash at the end of each line, or
• use the NoBlankLines filter.

And if you need to emit binary data without the risk of sneaking extra whitespace in there (the way that ruins everything 😤), you wrap your code in $m->clear_buffer and $m->abort, like this:

<%init>
$m->clear_buffer;
open(my $fh, '<', 'binary-file') or die $!;
my $buffer;
while (read $fh, $buffer, 8192) {
    $m->print($buffer);
}
$m->abort;
</%init>

🎀 I'm trying to generate an image or other binary file, but it seems to be getting corrupted.

Bestie, this is almost always caused by unwanted whitespace or other output hanging out at the beginning or end of your binary data. Rude of it, honestly.

Fix: use $m->clear_buffer and $m->abort exactly like in the previous answer. 🫶

🌸 How do I put comments in components?

See the Comments section in the syntax manual for the full reference. But the quick version:

• Put general comments in the <%doc> section.
• Within code blocks (<%class>, <%init>, <%perl>, etc.), use standard Perl comments ('#').
• Use <% # %> for single or multi-line comments anywhere outside of Perl sections.
• If you are producing HTML, you can use standard HTML comments delimited by <!-- -->. The difference is that these comments will appear in the final output. Yes, everyone can see them. Main character behaviour, but for your source code. 👑

💀 What's a good way to temporarily comment out code in a component?

Okay for HTML, you might be tempted to surround the section with <!-- -->. But be careful! Any code inside the section will still execute. Not me warning you about the sneakiest bug of all time.

Here's an example of commenting out a call to an ad server:

<!-- temporarily comment out
<& /shared/fetch_ad.mi &>
-->

And the ad will still be fetched and counted, it just won't be displayed! 😭 So you're paying for ads nobody sees. Tragic.

A better way to block out a section is if (0):

% if (0) {
  ...
% }

Code blocked out this way will neither be executed nor displayed, and multiple if (0) blocks can be nested inside each other (unlike HTML comments). Nested!! We love a technique that actually works. 🔥

Another way to block out code is with a <%doc> tag, although this not cannot be nested. (Yes, that's the original wording, it lives there rent free.)

🌈 How can I capture the output of a component (and modify it, etc.) instead of having it automatically output?

Use $m->scomp. That's it, that's the answer. ✨

🧚 How can I capture the output from arbitrary code that calls components, etc.?

Use $m->capture. 💜

⭐ How can I get a list of components matching a path pattern?

Use $m->glob_paths, like so:

my @paths = $m->glob_paths('/some/comp/path/*');

And this will work even with multiple component roots — you'll get a combined list of all matching component paths across all component roots. Combined list, no cap. 🫶

👑 How can I access $m (the request object) from outside a component, e.g. inside a regular class?

Use Mason::Request->current_request:

package Foo;

sub bar {
    my $m = Mason::Request->current_request;
}

💅 When using multiple component roots, is there a way to explicitly call a component in a specific root?

Nope bestie, and here's why. Multiple component roots were designed to work just like Perl's @INC. A given component path matches exactly one file — the first file found in an ordered search through the roots. There is no way to explicitly ask for a file in a specific root. Periodt. 💅

---

🌐 HTTP and HTML 🌐

🍓 How do I use Mason to process web requests?

You need to use Mason in conjunction with a web framework. Poet is a web framework designed specially for Mason. Catalyst and Dancer can also use Mason for their templating layer. See Mason::Manual::Setup. 💖

🎀 How can I HTML-escape the output of <% %> tags?

See the "H" filter in Mason::Plugin::HTMLFilters. And if you want to do this automatically for all <% %> tags, see Mason::Plugin::DefaultFilter. Iconic automation. ✨

😭 Why is Mason so slow with standard CGI?

Okay so under standard CGI you have to load all modules and initialize your environment with every single request. Mason's startup cost (mostly due to Moose) will make this particularly sub-optimal. Genuinely rough.

So ask yourself: do you absolutely have to use CGI? And if not, switch to a persistent solution like mod_perl or Fast CGI or Starman. Your response times will thank you. 🫶

---

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

---

And that's the whole vibe check, bestie! 🎀 Go forth and comment out your ad server properly this time. 💅

Okay so this lil doc came to you via perl v5.34.0 and it's dated 2022-05-27 — it's giving vintage but make it serve. Stay slay, stay escaped, and remember: the whitespace is always the problem. 💖✨🦋