.\" 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::Intro 3pm"
.TH Mason::Manual::Intro 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::Intro \- Getting started with Mason
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A few quick examples to get your feet wet with Mason.  See
Mason::Manual::Setup for how to use Mason to generate web sites.
.SH "EXAMPLE 1"
.IX Header "EXAMPLE 1"
.SS "Hello world (from command-line)"
.IX Subsection "Hello world (from command-line)"
After installing Mason, you should have a \f(CW\*(C`mason\*(C'\fR command in your installation
path (e.g. \f(CW\*(C`/usr/local/bin\*(C'\fR). Try this:
.PP
.Vb 3
\&    % mason
\&    Hello! The local time is <% scalar(localtime) %>.
\&    ^D
.Ve
.PP
(where '^D' means ctrl-D or \s-1EOF\s0). You should see something like
.PP
.Vb 1
\&    Hello! The local time is Wed Mar  2 17:11:54 2011.
.Ve
.PP
The \f(CW\*(C`mason\*(C'\fR command reads in a Mason \fIcomponent\fR (template), runs it, and
prints the result to standard output. Notice that the tag
.PP
.Vb 1
\&    <% scalar(localtime) %>
.Ve
.PP
was replaced with the value of its expression. This is called a \fIsubstitution
tag\fR and is a central piece of Mason syntax.
.SH "EXAMPLE 2"
.IX Header "EXAMPLE 2"
.SS "Email generator (from script)"
.IX Subsection "Email generator (from script)"
The command line is good for trying quick things, but eventually you're going
to want to put your Mason components in files.
.PP
In a test directory, create a directory \f(CW\*(C`comps\*(C'\fR and create a file \f(CW\*(C`email.mc\*(C'\fR
with the following:
.PP
.Vb 4
\&    <%class>
\&    has \*(Aqamount\*(Aq;
\&    has \*(Aqname\*(Aq;
\&    </%class>
\&
\&    Dear <% $.name %>,
\&
\&        We are pleased to inform you that you have won $<% sprintf("%.2f", $.amount) %>!
\&
\&    Sincerely,
\&    The Lottery Commission
\&
\&    <%init>
\&    die "amount must be a positive value!" unless $.amount > 0;
\&    </%init>
.Ve
.PP
In addition to the substitution tag we've seen before, we declare two
\&\fIattributes\fR, \f(CW\*(C`amount\*(C'\fR and \f(CW\*(C`name\*(C'\fR, to be passed into the component; and we
declare a piece of initialization code to validate the amount.
.PP
In the same test directory, create a script \f(CW\*(C`test.pl\*(C'\fR with the following:
.PP
.Vb 4
\&     1  #!/usr/local/bin/perl
\&     2  use Mason;
\&     3  my $interp = Mason\->new(comp_root => \*(Aqcomps\*(Aq, data_dir => \*(Aqdata\*(Aq);
\&     4  print $interp\->run(\*(Aq/email\*(Aq, name => \*(AqJoe\*(Aq, amount => \*(Aq1500\*(Aq)\->output;
.Ve
.PP
Line 3 creates a \fIMason interpreter\fR, the main Mason object. It specifies two
parameters: a \fIcomponent root\fR, indicating the directory hierarchy where your
components will live; and a \fIdata directory\fR, which Mason will use for
internal purposes such as class generation and caching.
.PP
Line 4 runs the template \- notice that the \f(CW\*(C`.mc\*(C'\fR extension is added
automatically \- passing values for the \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`amount\*(C'\fR attributes.
.PP
Run \f(CW\*(C`test.pl\*(C'\fR, and you should see
.PP
.Vb 1
\&    Dear Joe,
\&
\&        We are pleased to inform you that you have won $1500.00!
\&
\&    Sincerely,
\&    The Lottery Commission
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mason::Manual::Tutorial, Mason::Manual
.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.