Mason:...:Syntax(3pm)

🌸 Mason:...:Syntax(3pm) — bestie, it's the syntax reference 🌸

okay so this is Mason::Manual::Syntax, and it's literally the whole dictionary of everything you can write inside a Mason component. every tag, every block, every lil trick. no cap. 💅

---

✨ DESCRIPTION ✨

A reference for all the syntax that can be used in components. that's it, that's the whole vibe — it's your one-stop lookup for "wait how do I write that again" 🦋

---

💖 SUBSTITUTION TAGS 💖

<% expr %>

blocks that look like <% expr %> get swapped out for whatever expr evaluates to as a Perl expression in scalar context. it's giving "fill in the blank but make it code":

Hello, <% $name %>! The current time is <% scalar(localtime) %>.

heads up though: whitespace after <% and before %> is required. this gives a lil leeway for implementing variations on this tag in the future — and honestly it just looks better, periodt. ✨

<% expr | filter,filter... %>

you can pop a filter list after a | character in a substitution, with one or more names separated by commas. those names are filter methods on the current component class, and the filters get applied to the result before it's output. slay:

<% $content | NoBlankLines,Trim %>

See Mason::Manual::Filters for more info on filters. 🎀

---

🧚 PERL LINES 🧚

%-lines

lines starting with a single % are treated as Perl. the % must be followed by at least one whitespace character. iykyk:

<ul>
% foreach my $item (@items) {
<li><% $item %></li>
% }
</ul>

% if ($.logged_in) {
<div class="welcome">
   Welcome, <% $.username %>.
</div>
% }
% else {
<a href="/login">Click here to log in</a>
% }

---

🎀 UNNAMED BLOCKS 🎀

these are the blocks that don't take a name argument. lowkey the backbone of everything.

<%class>

holds Perl code that runs once when the component is loaded, in the main body of the class, outside of any methods. this is THE spot to use modules, declare attributes, and do other class-level stuff. main character energy fr:

<%class>
</%class>

<%doc>

text in here is treated as a comment and ignored. like a lil diary entry nobody reads 🫶

<%doc>
Name: foo.mc
Purpose: ...
</%doc>

<%flags>

sets flags that affect how the component gets compiled. each flag goes one per line in key => value form:

<%flags>
extends => '/foo/bar'
</%flags>

the <%flags> block is extracted in a special first pass through the component, so it can affect the rest of the compilation. iconic.

the built-in flags are:

• extends — declares the component's superclass (another component). the path may be absolute like above, or relative to the component's path. this is the only way to declare the component's superclass; using an extends keyword directly will not work reliably. if you don't provide it, the component's superclass is determined automatically via autobase components.

plugins may implement additional flags too. 🌈

<%init>

holds Perl code that runs at the beginning of the current method. it's equivalent to a <%perl> section at the top of the method:

<%init>
my $article = MyApp::Article->find($.article_id);
my $title = $article->title;
</%init>

<%perl>

holds Perl code that runs in place. the return value, if any, is discarded. it may appear anywhere in the text and any number of times:

<%perl>
my $article = MyApp::Article->find($.article_id);
my $title = $article->title;
</%perl>

<%text>

text in here gets printed as-is, with all Mason syntax ignored. it's a vibe shield:

<%text>
% This is an example of a Perl line.
<% This is an example of an expression block. %>
</%text>

this works for almost everything, but it doesn't let you output </%text> itself! when all else fails, use print:

% $m->print('The tags are <%text> and </%text>.');

---

👑 NAMED BLOCKS 👑

these ones take a name argument. we love a block with an identity.

<%method name params>

creates a new method with the specified name and params. it uses Method::Signatures::Simple underneath, so $self and any other declared parameters are automatically shifted off of @_. so convenient bestie:

<%method greet ($name, $color)>
<div style="color: <% $color %>">
   Hello, <% $name %>!
</div>
</%method>

<%after name> / <%augment name> / <%around name> / <%before name> / <%override name>

these modify a content-producing method with the specified name. See Moose::Manual::MethodModifiers for a description of each modifier.

$self is automatically shifted off for the body of <%after>, <%augment>, <%before> and <%override>. $orig and $self are automatically shifted off for the body of <%around>. okay noted 📝

<%after render>
   <% # Add analytics line after everything has rendered %>
   <& /shared/google_analytics_line.mi &>
</%after>

<%augment wrap>
  <html>
    <body>
      <% inner() %>
    </body>
  </html>
</%augment>

<%around navbar>
  <div class="navbar_special">
    <% $self->$orig() %>
  </div>
</%around>

<%override navbar>
  <% super() %>
  <a href="extra">extra</a>
</%override>

<%filter name params>

creates a filter method with the specified name and params. works just like a <%method> block, except that you can call $yield->() to generate the original content. e.g.

<%filter Row ($class)>
<tr class="<% $class %>">
% foreach my $item (split(/\s/, $yield->())) {
   <td><% $item %></td>
% }
</tr>
</%filter>

% $.Row('std') {{
First Second Third
% }}

generates

<tr class="std">
  <td>First</td>
  <td>Second</td>
  <td>Third</td>
</tr>

See Mason::Manual::Filters for more info on filters. 🍓

---

💜 CALLING COMPONENTS 💜

<& path, args &>

<& /path/to/comp.mi, name=>value, ... &>

path is an absolute or relative component path. if it's relative, it's considered relative to the location of the current component. args is a list of one or more name/value pairs.

the path may be a literal string (quotes optional) or a Perl expression that evaluates to a string. to eliminate the need for quotes in most cases, Mason employs some magic parsing: if the first character is one of [\w/\.], comp_path is assumed to be a literal string running up to the first comma or &>. otherwise, comp_path is evaluated as an expression. okay that's the tea ✨

here are some examples:

# relative component paths
<& topimage.mi &>
<& tools/searchbox.mi &>

# absolute component path
<& /shared/masthead.mi, color=>'salmon' &>

# this component path MUST have quotes because it contains a comma
<& "sugar,eggs.mi", mix=>1 &>

# variable component path
<& $comp &>

# variable component and attributes
<& $comp, %args &>

# you can use arbitrary expression for component path, but it cannot
# begin with a letter or number; delimit with () to remedy this
<& (int(rand(2)) ? 'thiscomp.mi' : 'thatcomp.mi'), id=>123 &>

you can also call components with the comp and scomp methods. 🌟

---

🙈 COMMENTS 🙈

<% # comment... %>

a <% %> tag counts as a comment if all of its lines are either whitespace, or begin with a # optionally preceded by whitespace. for example,

<% # This is a single-line comment %>

<%
   # This is a
   # multi-line comment
%>

% # comment

because a line beginning with % is treated as Perl, % # automatically works as a comment. however we prefer the <% # comment %> form over % #, because it stands out a little more as a comment and because it's more flexible with regards to preceding whitespace. 💅

% if (0) { }

anything between these two lines

% if (0) {
...
% }

will be skipped by Mason, including component calls. while we don't recomend this for comments per se, it is a useful notation for "commenting out" code that you don't want to run. sneakyyyy 🔥

HTML/XML/... comments

HTML and other markup languages will have their own comment markers, for example <!-- -->. note two important differences with these comments versus the above comments:

• they will be sent to the client and appear in the source of the page.
• they do not block component calls and other code from running, so don't try to use them to comment out code!

<!-- Oops, the code below will still run
   <& /shared/expensive.mhtml &>
-->

---

🌈 WHITESPACE AND NEWLINES 🌈

Newlines between blocks

Mason will ignore a single newline between blocks, so you can space them nicely. additional newlines beyond that will be displayed.

<%class>
...
</%class>
                  <-- ignored
<%method foo>
...
</%method>
                  <-- ignored
                  <-- displayed
<%method bar>
...
</%method>

Backslash at end of line

a backslash (\) at the end of a line suppresses the newline. in HTML components, this is mostly useful for fixed width areas like <pre> tags, since browsers ignore white space for the most part. an example:

<pre>
foo
% if (1) {
bar
% }
baz
</pre>

outputs

foo
bar
baz

because of the newlines on lines 2 and 4. (lines 3 and 5 do not generate a newline because the entire line is taken by Perl.) to suppress the newlines:

<pre>
foo\
% if (1) {
bar\
% }
baz
</pre>

which prints

foobarbaz

---

🦋 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 bestie that's the whole page, you ate it 💅 and for the record this was perl v5.34.0, dated 2022-05-27, page Mason:...:Syntax(3pm) — go forth and write iconic components, mwah 🫶✨🎀