.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" 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::Manual::Syntax 3pm"
.TH Mason::Manual::Syntax 3pm "2014-02-01" "perl v5.18.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::Manual::Syntax \- Mason component syntax reference
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A reference for all the syntax that can be used in components.
.SH "SUBSTITUTION TAGS"
.IX Header "SUBSTITUTION TAGS"
.SS "<% \fIexpr\fP %>"
.IX Subsection "<% expr %>"
Blocks of the form \f(CW\*(C`<% expr %>\*(C'\fR are replaced with the result of evaluating
\&\f(CW\*(C`expr\*(C'\fR as a Perl expression in scalar context.
.PP
.Vb 1
\&    Hello, <% $name %>! The current time is <% scalar(localtime) %>.
.Ve
.PP
Whitespace after '<%' and before '%>' is required. This gives us a little
leeway in implementing variations on this tag in the future \- it also just
looks better.
.SS "<% \fIexpr\fP | \fIfilter\fP,\fIfilter\fP... %>"
.IX Subsection "<% expr | filter,filter... %>"
A filter list may appear after a << | >> character in a substitution,
containing one or more names separated by commas. The names are as filter
methods on the current component class. The filters are applied to the result
before it is output.
.PP
.Vb 1
\&    <% $content | NoBlankLines,Trim %>
.Ve
.PP
See Mason::Manual::Filters for more information on filters.
.SH "PERL LINES"
.IX Header "PERL LINES"
.SS "%\-lines"
.IX Subsection "%-lines"
Lines beginning with a single '%' are treated as Perl. The '%' must be followed
by at least one whitespace character.
.PP
.Vb 5
\&    <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>
\&    % }
.Ve
.SH "UNNAMED BLOCKS"
.IX Header "UNNAMED BLOCKS"
Blocks that do not take a name argument.
.SS "<%class>"
.IX Subsection "<%class>"
Contains Perl code code that executes once when the component is loaded, in the
main body of the class outside of any methods. This is the place to use
modules, declare attributes, and do other things on a class level.
.PP
.Vb 2
\&   <%class>
\&   </%class>
.Ve
.SS "<%doc>"
.IX Subsection "<%doc>"
Text in this section is treated as a comment and ignored.
.PP
.Vb 4
\&    <%doc>
\&    Name: foo.mc
\&    Purpose: ...
\&    </%doc>
.Ve
.SS "<%flags>"
.IX Subsection "<%flags>"
Specifies flags that affect the compilation of the component. Each flag is
listed one per line in \f(CW\*(C`key => value\*(C'\fR form.
.PP
.Vb 3
\&    <%flags>
\&    extends => \*(Aq/foo/bar\*(Aq
\&    </%flags>
.Ve
.PP
The \f(CW\*(C`<%flags>\*(C'\fR block is extracted in a special first pass through the
component, so that it can affect the remainder of the compilation.
.PP
The built-in flags are:
.IP "extends" 4
.IX Item "extends"
Declares the component's superclass (another component). The path may be
absolute as shown above, or relative to the component's path. This is the only
way to declare the component's superclass; using an \f(CW\*(C`extends\*(C'\fR keyword
directly will not work reliably. If not provided, the component's superclass is
determined automatically via autobase components.
.PP
Plugins may implement additional flags.
.SS "<%init>"
.IX Subsection "<%init>"
Contains Perl code that is executed at the beginning of the current method.
Equivalent to a \f(CW\*(C`<%perl>\*(C'\fR section at the top of the method.
.PP
.Vb 4
\&   <%init>
\&   my $article = MyApp::Article\->find($.article_id);
\&   my $title = $article\->title;
\&   </%init>
.Ve
.SS "<%perl>"
.IX Subsection "<%perl>"
Contains Perl code that is executed in place. The return value, if any, is
discarded.  May appear anywhere in the text and any number of times.
.PP
.Vb 4
\&   <%perl>
\&   my $article = MyApp::Article\->find($.article_id);
\&   my $title = $article\->title;
\&   </%perl>
.Ve
.SS "<%text>"
.IX Subsection "<%text>"
Text in this section is printed as-is with all Mason syntax ignored.
.PP
.Vb 4
\&    <%text>
\&    % This is an example of a Perl line.
\&    <% This is an example of an expression block. %>
\&    </%text>
.Ve
.PP
This works for almost everything, but doesn't let you output \f(CW\*(C`</%text>\*(C'\fR
itself! When all else fails, use print:
.PP
.Vb 1
\&    % $m\->print(\*(AqThe tags are <%text> and </%text>.\*(Aq);
.Ve
.SH "NAMED BLOCKS"
.IX Header "NAMED BLOCKS"
Blocks that take a name argument.
.SS "<%method \fIname\fP \fIparams\fP>"
.IX Subsection "<%method name params>"
Creates a new method with the specified \fIname\fR and \fIparams\fR.  Uses
Method::Signatures::Simple underneath, so
\&\f(CW$self\fR and any other declared parameters are automatically shifted off of
\&\f(CW@_\fR.
.PP
.Vb 5
\&   <%method greet ($name, $color)>
\&   <div style="color: <% $color %>">
\&      Hello, <% $name %>!
\&   </div>
\&   </%method>
.Ve
.SS "<%after \fIname\fP>"
.IX Subsection "<%after name>"
.SS "<%augment \fIname\fP>"
.IX Subsection "<%augment name>"
.SS "<%around \fIname\fP>"
.IX Subsection "<%around name>"
.SS "<%before \fIname\fP>"
.IX Subsection "<%before name>"
.SS "<%override \fIname\fP>"
.IX Subsection "<%override name>"
Modifies a content-producing method with the specified \fIname\fR. See
Moose::Manual::MethodModifiers for a description of each modifier.
.PP
\&\f(CW$self\fR is automatically shifted off for the body of \f(CW\*(C`<%after>\*(C'\fR, \f(CW\*(C`<%augment>\*(C'\fR, \f(CW\*(C`<%before>\*(C'\fR and \f(CW\*(C` <%override\*(C'\fR >. \f(CW$orig\fR and \f(CW$self\fR are
automatically shifted off for the body of \f(CW\*(C`<%around>\*(C'\fR.
.PP
.Vb 4
\&    <%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>
.Ve
.SS "<%filter \fIname\fP \fIparams\fP>"
.IX Subsection "<%filter name params>"
Creates a filter method with the specified \fIname\fR and \fIparams\fR. Works just
like a \f(CW\*(C`<%method>\*(C'\fR block, except that you can call \f(CW\*(C`$yield\->()\*(C'\fR to
generate the original content. e.g.
.PP
.Vb 7
\&    <%filter Row ($class)>
\&    <tr class="<% $class %>">
\&    % foreach my $item (split(/\es/, $yield\->())) {
\&       <td><% $item %></td>
\&    % }
\&    </tr>
\&    </%filter>
\&
\&    % $.Row(\*(Aqstd\*(Aq) {{
\&    First Second Third
\&    % }}
.Ve
.PP
generates
.PP
.Vb 5
\&    <tr class="std">
\&      <td>First</td>
\&      <td>Second</td>
\&      <td>Third</td>
\&    </tr>
.Ve
.PP
See Mason::Manual::Filters for more information on filters.
.SH "CALLING COMPONENTS"
.IX Header "CALLING COMPONENTS"
.SS "<& \fIpath\fP, \fIargs\fP &>"
.IX Subsection "<& path, args &>"
.Vb 1
\&    <& /path/to/comp.mi, name=>value, ... &>
.Ve
.PP
\&\fIpath\fR is an absolute or relative component path. If the latter, it is
considered relative to the location of the current component. \fIargs\fR is a list
of one or more name/value pairs.
.PP
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 \f(CW\*(C`[\ew/\e.]\*(C'\fR,
comp_path is assumed to be a literal string running up to the first comma or
&>. Otherwise, comp_path is evaluated as an expression.
.PP
Here are some examples:
.PP
.Vb 3
\&    # relative component paths
\&    <& topimage.mi &>
\&    <& tools/searchbox.mi &>
\&
\&    # absolute component path
\&    <& /shared/masthead.mi, color=>\*(Aqsalmon\*(Aq &>
\&
\&    # 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)) ? \*(Aqthiscomp.mi\*(Aq : \*(Aqthatcomp.mi\*(Aq), id=>123 &>
.Ve
.PP
You can also call components with the comp and
scomp methods.
.SH "COMMENTS"
.IX Header "COMMENTS"
.SS "<% # comment... %>"
.IX Subsection "<% # comment... %>"
A \f(CW\*(C`<% %>\*(C'\fR tag is considered a comment if all of its lines are either
whitespace, or begin with a '#' optionally preceded by whitespace. For example,
.PP
.Vb 1
\&    <% # This is a single\-line comment %>
\&
\&    <%
\&       # This is a
\&       # multi\-line comment
\&    %>
.Ve
.SS "% # comment"
.IX Subsection "% # comment"
Because a line beginning with \f(CW\*(C`%\*(C'\fR is treated as Perl, \f(CW\*(C`% #\*(C'\fR automatically
works as a comment. However we prefer the \f(CW\*(C`<% # comment %>\*(C'\fR form over \f(CW\*(C`% #\*(C'\fR, because it stands out a little more as a comment and because it is more
flexible with regards to preceding whitespace.
.SS "% if (0) { }"
.IX Subsection "% if (0) { }"
Anything between these two lines
.PP
.Vb 3
\&   % if (0) {
\&   ...
\&   % }
.Ve
.PP
will be skipped by Mason, including component calls.  While we don't recomend
this for comments per se, it is a useful notation for \*(L"commenting out\*(R" code
that you don't want to run.
.SS "\s-1HTML/XML/...\s0 comments"
.IX Subsection "HTML/XML/... comments"
\&\s-1HTML\s0 and other markup languages will have their own comment markers, for
example \f(CW\*(C`<!\-\- \-\->\*(C'\fR. Note two important differences with these comments
versus the above comments:
.IP "\(bu" 4
They will be sent to the client and appear in the source of the page.
.IP "\(bu" 4
They do not block component calls and other code from running, so don't try to
use them to comment out code!
.Sp
.Vb 3
\&   <!\-\- Oops, the code below will still run
\&      <& /shared/expensive.mhtml &>
\&   \-\->
.Ve
.SH "WHITESPACE AND NEWLINES"
.IX Header "WHITESPACE AND NEWLINES"
.SS "Newlines between blocks"
.IX Subsection "Newlines between blocks"
Mason will ignore a single newline between blocks, so that you can space them
nicely.  Additional newlines beyond that will be displayed.
.PP
.Vb 12
\&   <%class>
\&   ...
\&   </%class>
\&                     <\-\- ignored
\&   <%method foo>
\&   ...
\&   </%method>
\&                     <\-\- ignored
\&                     <\-\- displayed
\&   <%method bar>
\&   ...
\&   </%method>
.Ve
.SS "Backslash at end of line"
.IX Subsection "Backslash at end of line"
A backslash (\e) at the end of a line suppresses the newline. In \s-1HTML\s0
components, this is mostly useful for fixed width areas like \f(CW\*(C`<pre>\*(C'\fR tags,
since browsers ignore white space for the most part. An example:
.PP
.Vb 7
\&    <pre>
\&    foo
\&    % if (1) {
\&    bar
\&    % }
\&    baz
\&    </pre>
.Ve
.PP
outputs
.PP
.Vb 3
\&    foo
\&    bar
\&    baz
.Ve
.PP
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:
.PP
.Vb 7
\&    <pre>
\&    foo\e
\&    % if (1) {
\&    bar\e
\&    % }
\&    baz
\&    </pre>
.Ve
.PP
which prints
.PP
.Vb 1
\&    foobarbaz
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mason
.SH "AUTHOR"
.IX Header "AUTHOR"
Jonathan Swartz <swartz@pobox.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2012 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.