├── CPAN
    ├── .gitignore
    ├── Makefile
    ├── README
    ├── build
    │   └── latex.pl
    ├── chapters
    │   ├── 00-preamble.pod
    │   ├── 01-intro.pod
    │   ├── 10-oo.pod
    │   ├── 20-templates.pod
    │   ├── 30-web.pod
    │   ├── 40-database.pod
    │   ├── 50-xml.pod
    │   ├── 60-serialization.pod
    │   ├── 70-testing.pod
    │   ├── 80-protocols.pod
    │   └── 90-uncategorized.pod
    └── tex
    │   └── asbook.sty
└── README


/CPAN/.gitignore:
--------------------------------------------------------------------------------
1 | mynotes
2 | book.*
3 | cpan-chapter?.pdf
4 | 


--------------------------------------------------------------------------------
/CPAN/Makefile:
--------------------------------------------------------------------------------
 1 | CHAPTERS=cpan-chapter1.pdf cpan-chapter2.pdf cpan-chapter3.pdf
 2 | 
 3 | book.pdf: book.tex tex/asbook.sty
 4 | 	TEXINPUTS=$$TEXINPUTS:tex xelatex book
 5 | 	makeindex book
 6 | 	TEXINPUTS=$$TEXINPUTS:tex xelatex book
 7 | 	TEXINPUTS=$$TEXINPUTS:tex xelatex book
 8 | 
 9 | book.tex: build/latex.pl chapters/*.pod
10 | 	build/latex.pl
11 | 
12 | clean:
13 | 	find . -name '*~' -delete
14 | 	rm -f book.* *.log
15 | 
16 | share: book.pdf $(CHAPTERS)
17 | 	@ rsync -aASPvz book.pdf ambs@eremita:public_html/cpan.pdf
18 | 	@ rsync -aASPvz $(CHAPTERS) ambs@camelo:public_html
19 | 
20 | cpan-chapter1.pdf: book.pdf
21 | 	pdfjam -q book.pdf  7-14 -o cpan-chapter1.pdf
22 | 
23 | cpan-chapter2.pdf: book.pdf
24 | 	pdfjam -q book.pdf 15-26 -o cpan-chapter2.pdf
25 | 
26 | cpan-chapter3.pdf: book.pdf
27 | 	pdfjam -q book.pdf 27-44 -o cpan-chapter3.pdf
28 | 
29 | nodraft: build/latex.pl chapters/*.pod tex/asbook.sty
30 | 	build/latex.pl -draft=0
31 | 	TEXINPUTS=$$TEXINPUTS:tex xelatex book
32 | 	makeindex book
33 | 	TEXINPUTS=$$TEXINPUTS:tex xelatex book
34 | 	TEXINPUTS=$$TEXINPUTS:tex xelatex book
35 | 
36 | 


--------------------------------------------------------------------------------
/CPAN/README:
--------------------------------------------------------------------------------
 1 | Book Guidelines
 2 | --------------------------------
 3 | 
 4 | 1. Chapters should be independent
 5 | 
 6 | A reader can read just a chapter, and no dependencies to other chapters
 7 | should exist. Only pointers for further information.
 8 | 
 9 | 2. Sections should be independent
10 | 
11 | Only the first paragraphs of the chapter, before the first section,
12 | should/can compare the modules being discussed. Individual module sections
13 | should not make comparisons bwteeen modules unless strictly necessary.
14 | 
15 | 3. See also section
16 | 
17 | Each chapter should end in a special section named 'See also', that is
18 | an listing of modules available on CPAN for similar tasks, and a small
19 | description on them.
20 | 
21 | 4. Depth
22 | 
23 | No section should have more than 15 pages. I can accept a limit of 20
24 | for big frameworks like Catalyst. If it is impossible to explain the
25 | module in such a reduced number of pages, then the module should not
26 | be included (put it into the see also section, and point to other
27 | books/documentation).
28 | 
29 | 5. Formatting
30 | 
31 | Use C<...> for module names. Do not forget to add X<Module, name> and
32 | X<name> whenever you mention a module (once per section, of course).
33 | 
34 | Also, for footnotes, use N<< ... >> but do not leave a blank space
35 | before the N. If it gets glued with another word, the parser will
36 | detect it correctly.
37 | 
38 | 6. Code blocks
39 | 
40 | Perl code blocks should be enclosed in =begin Perl and =end
41 | Perl. Also, keep them indented two or three spaces. If referring to
42 | one line of code, only, use standard verbatim. For other non-perl
43 | blocks, use standard verbatim blocks.
44 | 
45 | 
46 | Build
47 | --------------------------------
48 | 
49 | ATM for building you need head from Pod::PseudoPod::LaTeX git repository.
50 | Check it out: git://github.com/chromatic/Pod-PseudoPod-LaTeX.git
51 | 


--------------------------------------------------------------------------------
/CPAN/build/latex.pl:
--------------------------------------------------------------------------------
  1 | #!/usr/bin/perl -s
  2 | 
  3 | use strict;
  4 | use warnings;
  5 | use utf8;
  6 | 
  7 | use File::Slurp qw.edit_file.;
  8 | use Pod::PseudoPod::LaTeX;
  9 | 
 10 | our ($draft);
 11 | 
 12 | $draft = 1 unless defined $draft;
 13 | 
 14 | my $pod = 'build/book.pod';
 15 | my $tex = "book.tex";
 16 | 
 17 | 
 18 | my @files = sort {
 19 |       $a =~ m!(\d+)-! and my $c = $1;
 20 |       $b =~ m!(\d+)-! and my $d = $1;
 21 |       $c <=> $d
 22 | } <chapters/*pod>;
 23 | 
 24 | create_single_pod   (pod => $pod, files => \@files);
 25 | create_tex_from_pod (pod => $pod, tex => $tex);
 26 | post_process_tex    ($tex);
 27 | 
 28 | unlink $pod;
 29 | 
 30 | sub post_process_tex {
 31 |     my $filename = shift;
 32 |     edit_file {
 33 |         s/section\*/section/g;
 34 |         s/section\{\*/section*{/g;
 35 |         s/chapter\{\*/chapter*{/g;
 36 | 
 37 |         s/\\scriptsize\n\\begin{Verbatim/\\small\n\\begin{Verbatim/g;
 38 |         # this depends on the previous one
 39 |         s/
 40 |           \\vspace{-6pt}\n(\\small\n\\begin{Verbatim}\[[^]]+frame=single[^]]+\])
 41 |          /
 42 |           "\\vspace{-2pt}\n$1" # this way I can keep the indentation O:-)
 43 |          /xge;
 44 | 
 45 |         s!frame=single,label=!frame=single,numbers=left,label=!g;
 46 | 
 47 |         s!}``!}''!g;
 48 | 
 49 |         s/titleref/nameref/g;
 50 | 
 51 |         s!\bLaTeX\b!\\LaTeX{}!g;
 52 |         s!\bTeX\b!\\TeX{}!g;
 53 |     } $filename;
 54 | }
 55 | 
 56 | sub create_single_pod {
 57 |     my %data  = @_;
 58 |     my $pod   = $data{pod} or die;
 59 |     my @files = @{$data{files}} or die;
 60 | 
 61 |     open my $out, ">:utf8", $pod or die "Can't create file!";
 62 | 
 63 |     for my $file (@files) {
 64 |         open X, "<:utf8", $file or die "Error opening file $!";
 65 |         while(<X>) {
 66 |             print $out $_;
 67 |         }
 68 |         close X;
 69 |     }
 70 | 
 71 |     close $out;
 72 | }
 73 | 
 74 | sub parse_pod_file {
 75 |     my %data   = @_;
 76 |     my $fh     = $data{out} or die;
 77 |     my $pod    = $data{pod} or die;
 78 |     my $parser = Pod::PseudoPod::LaTeX->new(captions_bellow => 1, keep_ligatures => 1);
 79 |     $parser->output_fh($fh);
 80 |     $parser->accept_target_as_text('CPANinfo', 'small', 'SeeAlso', 'right');
 81 |     $parser->accept_target('Perl');
 82 |     $parser->emit_environments('CPANinfo' => 'cpaninfo',
 83 |                                'small'    => 'smallenv',
 84 |                                'right'    => 'flushright',
 85 |                                'SeeAlso'  => 'SeeAlso',
 86 |                                'Perl'     => 'lstlisting');
 87 |     $parser->parse_file($pod);
 88 | }
 89 | 
 90 | sub add_tex_preamble {
 91 |     my $fh = shift;
 92 |     # XXX - TODO: put this into a separate .tex file, and copy its
 93 |     #             contents here.
 94 |     print $fh <<'EOTex';
 95 | \documentclass[a5paper,twoside,9pt]{extbook}
 96 | EOTex
 97 |     print $fh "\\usepackage{draftwatermark}\n\\SetWatermarkLightness{0.95}\n" if $draft;
 98 |     print $fh <<'EOTeX';
 99 | \usepackage[left=1.7cm,right=2.2cm,top=2cm,bottom=1.5cm,footskip=7mm,headsep=7mm]{geometry}
100 | \usepackage{makeidx}
101 | \makeindex
102 | 
103 | \usepackage{asbook}
104 | \setdefaultlanguage{english}
105 | 
106 | \title{CPAN Modules and Frameworks}
107 | \subtitle{A bunch of relevant Perl modules and frameworks available from CPAN}
108 | \author{Alberto Simões\\[2mm]Nuno Carvalho}
109 | \date{First Edition}
110 | 
111 | \begin{document}
112 | \frontmatter
113 | \maketitle
114 | 
115 | EOTeX
116 | }
117 | 
118 | sub add_tex_postamble {
119 |     my $fh = shift;
120 |     print $fh <<'EOTeX'
121 | \printindex
122 | \end{document}
123 | EOTeX
124 | }
125 | 
126 | sub create_tex_from_pod {
127 |     my %data = @_;
128 |     my $tex = $data{tex} or die;
129 |     my $pod = $data{pod} or die;
130 |     open my $tex_fh, ">:utf8", $tex;
131 |     add_tex_preamble $tex_fh;
132 |     parse_pod_file out => $tex_fh, pod => $pod;
133 |     add_tex_postamble $tex_fh;
134 |     close $tex_fh;
135 | 
136 | }
137 | 


--------------------------------------------------------------------------------
/CPAN/chapters/00-preamble.pod:
--------------------------------------------------------------------------------
 1 | 
 2 | =for latex
 3 | 
 4 | \parskip 2mm
 5 | 
 6 | =end
 7 | 
 8 | =head0 *Preamble
 9 | 
10 | This book does not intend to be a complete reference to all modules
11 | from CPAN, nor a complete reference to some modules from
12 | CPAN. That would be mostly impossible to print, as there are thousands
13 | of Perl modules available, and some of them have rather long
14 | documentation.
15 | 
16 | That said, B<< this book aims to introduce a set of useful modules and
17 | frameworks >> that are not easy to learn just by reading the main
18 | Module documentation file (the one you usually get when executing
19 | C<perldoc Module> on the command line). Do not expect that all
20 | features are presented. The more important were chosen, and for
21 | further details you should read each module documentation.
22 | 
23 | The book is split in different chapters, each one covering a specific
24 | type of modules or frameworks. For instance, we have a chapter on web
25 | frameworks, and a chapter on XML parsers. For each chapter you will
26 | get a brief explanation or comparison between the modules that will be
27 | described, together with the reason why those modules where
28 | chosen. Then, each section will focus in one of those modules. And the
29 | chapter ends with a special section, where pointers to other useful
30 | modules that were not discussed but might be useful.
31 | 
32 | When writing this book we tried to make it possible to be read in any
33 | order: you can peek at a chapter about a topic you are interested in, and
34 | read it without reading all the other chapters. We even tried to make
35 | sections independent, so you can read a section on a specific
36 | framework without needing to read the sections for the other
37 | frameworks. Nevertheless, it might be a good idea to read the
38 | introduction to that chapter before reading a specific section.
39 | 
40 | If you are new to Perl or to using modules from CPAN we suggest you
41 | start by reading our first chapter. It presents some of the history
42 | about CPAN, how it works, who contributes code, how you can install
43 | modules from CPAN in your computer and where you can get information
44 | on how to contribute to CPAN.
45 | 
46 | Regarding previous knowledge on Perl or CPAN, we expect you to know
47 | how to write basic Perl programs, including the use of modules and
48 | references. The knowledge about I<old> Object Oriented Perl might be
49 | useful as well.
50 | 
51 | The authors would like to thank
52 | Stevan Little,
53 | Pedro Melo,
54 | David Precious,
55 | Marcos Ramos,
56 | Magda Joana Silva
57 | and
58 | Sawyer X
59 | for they comments, suggestions and proofreading.
60 | 
61 | Also, this book wouldn't be possible without LaTeX and the
62 | C<Pod::PseudoPod::LaTeX> Perl module from chromatic and Moritz.
63 | 
64 | =begin right
65 | 
66 | I<the authors>
67 | 
68 | =end right
69 | 
70 | =for latex
71 | 
72 | \parskip 0mm
73 | \tableofcontents
74 | \mainmatter
75 | \parskip 2mm
76 | \pagestyle{fancy}
77 | 
78 | =end
79 | 
80 | =cut
81 | 
82 | ## Local Variables:
83 | ##  ispell-local-dictionary: "english"
84 | ##  mode: flyspell
85 | ## End:
86 | 


--------------------------------------------------------------------------------
/CPAN/chapters/01-intro.pod:
--------------------------------------------------------------------------------
  1 | 
  2 | =head0 The Comprehensive Perl Archive Network
  3 | 
  4 | X<CPAN> The Comprehensive Perl Archive Network, known as CPANN<< It is
  5 | named after another archive, The Comprehensive TeX Archive Network, an
  6 | archive of TeX and LaTeX modules and styles. >> is an archive of Perl
  7 | applications, modules and frameworks.  It is available through the
  8 | Network and is Comprehensive, in the sense that it is a large
  9 | collection, but also that it includes nearly all developed modules,
 10 | and they are available in an organized way.
 11 | 
 12 | Note that CPAN does not have any kind of guarantee that the available
 13 | modules are not malicious, or that provides the documented
 14 | features. Therefore, knowing what modules are being used by the
 15 | community is great, as it gives information about their quality and
 16 | trust.
 17 | 
 18 | CPAN is available from L<http://cpan.org/> or one of the hundreds of
 19 | available mirrors around the world. You can access the modules using 
 20 | C<FTP>, C<HTTP> or, more interestingly, using the search feature of 
 21 | CPAN. It will give you information on the module author, what the 
 22 | latest version is, points to the download file, gives you access to 
 23 | the module documentation and a rating system, where users can rate modules.
 24 | 
 25 | There are a bunch of other web sites that were developed to make the
 26 | CPAN experience richer. There are some of them:
 27 | 
 28 | =over
 29 | 
 30 | =item B<AnnoCPAN>
 31 | 
 32 | X<CPAN, AnnoCPAN>
 33 | AnnoCPAN (L<http://www.annocpan.org>) gives you access to modules
 34 | documentation, but also to annotations over that documentation. What
 35 | this means, is that any user can annotate the documentation with
 36 | further information, incoherences and other (relevant) information.
 37 | 
 38 | =item B<CPAN Forum>
 39 | 
 40 | X<CPAN, Forum>
 41 | CPAN Forum (L<http://cpanforum.com/>) offers a forum for each
 42 | module. Some authors maintain their forum active, some others do not
 43 | use them. Some others, prefer to create forums in other web sites, or
 44 | to create mailing lists.
 45 | 
 46 | =item B<CPAN Testers>
 47 | 
 48 | X<CPAN, Testers>
 49 | CPAN Testers (L<http://static.cpantesters.org/>) gives information
 50 | about how each module installs, and how their tests pass or fail in
 51 | different architectures and perl versions.  When installing a module, 
 52 | if the build fails, this web site can be used to detect whether it is 
 53 | a local fail, or a known bug. For module developers it is very valuable
 54 | to check if modules are portable and if tests pass on different systems, helping
 55 | all authors to improve the quality and reliability of their code.
 56 | 
 57 | =item B<CPAN Ratings>
 58 | 
 59 | X<CPAN, Ratings>
 60 | CPAN Ratings (L<http://cpanratings.perl.org/>) allows users of modules to
 61 | leave ratings and reviews on Perl modules, providing useful information to
 62 | other users looking for a module to fulfil a particular task and facing
 63 | multiple modules to decide between.  Ratings are visible when viewing
 64 | distributions on L<http://search.cpan.org/>.
 65 | 
 66 | =item B<MetaCPAN>
 67 | 
 68 | X<CPAN, MetaCPAN> MetaCPAN (L<http://metacpan.org/>) is a new
 69 | interface to the CPAN repository. Aims at a fresh, light and fast user
 70 | interface, using new technologies like JavaScript. It has a very nice
 71 | feature over the standard CPAN web site, as it indexes new modules
 72 | faster. They get available on MetaCPAN a few minutes after the
 73 | developer uploads them.
 74 | 
 75 | =back
 76 | 
 77 | =head1 Installing CPAN Modules
 78 | 
 79 | X<Module, installing> There are three main different ways to install a
 80 | module from CPAN: using an automated installation tool, like C<cpan>,
 81 | C<cpanp> or C<cpanm>, installing a package provided by your OS vendor,
 82 | or installing manually.  Installing packages from the OS vendor's
 83 | repository (for instance, via C<apt-get> for Debian-based systems) is
 84 | preferred by some, but packages can lag behind the latest versions
 85 | available on CPAN.
 86 | 
 87 | Installing modules using CPAN.pm (C<cpan>), CPANPLUS (C<cpanp>) or
 88 | cpanminus (C<cpanm>) is considered ideal by many, as it provides easy
 89 | installation with automated tests and dependency handling, and allows
 90 | you to install the freshest version available from CPAN.
 91 | 
 92 | Installing manually gives the most control, but forces you to deal
 93 | with satisfying dependencies yourself; for a module with a long
 94 | dependency chain on a fresh Perl install, this can be a real pain.
 95 | 
 96 | =head2 *Using C<cpan>
 97 | 
 98 | X<Command, cpan> X<cpan>
 99 | The command line tool C<cpan> ships with Perl, and can be described as
100 | the official tool to install modules. The only situations whether you
101 | probably do not have C<cpan> installed in your system are derived of
102 | using ActiveState ActivePerl (in this case read the section on
103 | C<PPM>), or using a Linux distribution that splits the Perl package in
104 | smaller packages. In this case use your package system and search for
105 | the C<cpan> package.
106 | 
107 | Usually you want to run C<cpan> as a system administrator, so you have
108 | the needed permissions to write into the system tree.  Alternatively, the CPAN
109 | client can run as a normal user, and be configured to use C<sudo> where required
110 | to perform the final installation; this has the benefit of making the test suite
111 | run as a normal user, which can be preferable for security.
112 | 
113 | Recent C<cpan>
114 | versions have an automated configuring system. Nevertheless, if you
115 | run C<cpan> and it asks a lot of questions, you are safe on choosing
116 | the default answers. Just take care to choose a nearby mirror, so
117 | packages download faster.  
118 | 
119 | C<cpan> can be used from the command line issuing:
120 | 
121 |     cpan Module::Name Another::Module
122 | 
123 | This will install in your system the two modules C<Module::Name> and
124 | C<Another::Module>. The other approach is using C<cpan> shell. For
125 | that, just type C<cpan> in your command line, and a C<cpan> shell will
126 | appear. You can get help on the C<cpan> shell commands using "C<h>". To
127 | install modules use the "C<i>" command.
128 | 
129 | If for some reason the C<cpan> command is not installed, you can try to execute
130 | the CPAN.pm shell with:
131 | 
132 |   perl -MCPAN -e shell
133 | 
134 | Z<cpaninstall>
135 | 
136 | =begin screen Simple cpan interaction
137 | 
138 |  cpan shell -- CPAN exploration and modules installation
139 |  Enter 'h' for help.
140 |   
141 |  cpan[1]> i Module::Name Another::Module
142 | 
143 | =end screen
144 | 
145 | =head2 *Using C<cpanp>
146 | 
147 | X<Command, cpanp> X<cpanp> X<Module, CPANPLUS>
148 | C<cpanp> is the command line tool to the C<CPANPLUS> module, that
149 | enhances the C<CPAN> module used by C<cpan> with some new
150 | functionalities. Although some C<cpanp> commands differ from the ones
151 | available on C<cpan>, the basic behavior is similar. To install from
152 | the command line add the "C<-i>" switch:
153 | 
154 |     cpanp -i Module::Name Another::Module
155 | 
156 | For the interactive shell, C<cpanp> also uses the C<i> command (see
157 | A<cpaninstall>).
158 | 
159 | =head2 *Using C<cpanm>
160 | 
161 | X<Command, cpanm> X<cpanm> C<cpanm> is available through
162 | X<App::Cpanminus> C<App::Cpanminus> module. The main advantage of
163 | C<cpanm> regarding the other two approaches described above is
164 | efficiency. C<cpanm> is very quick, as it doesn't perform the amount
165 | of checks C<cpan> or C<cpanp> does, and finds out about modules via
166 | the CPAN MetaDB API, rather than by parsing large indexes. This
167 | provides fast operation, and ensures fresh module versions.
168 | 
169 | Install the module, and use C<cpanm> from the command lineN<<
170 | C<cpanm> does not have an interactive shell. You must use it directly
171 | from the command line. >>.
172 | 
173 |    cpanm --sudo Module::Name another::Module
174 | 
175 | The "C<--sudo>" switch is used to ask C<cpanm> to call C<sudo> when
176 | installing the module. This way you can call C<cpanm> from your user,
177 | knowing the when needed a password will be asked.
178 | 
179 | =head2 *ActivePerl PPM
180 | 
181 | X<PPM> X<ActivePerl> PPM stands for I<Perl Package Manager>, and it is
182 | an application by ActiveState to install modules from their own module
183 | repository. These packages have the advantage of being pre-compiled,
184 | making it easier to install on Windows machines without a compiler
185 | available. The main drawback is that PPM repositories do not have all
186 | available modules from CPAN, so you may well find that the module you
187 | need is not available, or is somewhat outdated.
188 | 
189 | Therefore, the authors suggest Windows users to download the Strawberry
190 | Perl X<Strawberry Perl> distribution which includes C<cpan> and a quite
191 | complete build system.
192 | 
193 | =head2 *Manual Install
194 | 
195 | X<Module, manual installation> The process of installing a module by
196 | hand depends a little on your operating system.  The instructions
197 | presented here describe the most usual process. First, get the module
198 | archive from a CPAN mirror. These files are usually named I<tarballs>,
199 | and are compressed using C<gzip> and archived by C<tar>. For this
200 | example we will describe the process of installing C<Try::Tiny>:
201 | 
202 | =begin screen Manual installation of a Perl Module
203 |  
204 |  $ tar zxf Try-Tiny-0.09.tar.gz
205 |  $ cd Try-Tiny-0.09
206 |  $ perl Makefile.PL
207 |  Checking if your kit is complete...
208 |  Looks good
209 |  Writing Makefile for Try::Tiny
210 |  Writing MYMETA.yml
211 |  $ make
212 |  cp lib/Try/Tiny.pm blib/lib/Try/Tiny.pm
213 |  Manifying blib/man3/Try::Tiny.3
214 |  $ make test
215 |  PERL_DL_NONLAZY=1 /opt/local/bin/perl [...] t/*.t
216 |  t/basic.t ....... ok     
217 |  t/finally.t ..... ok     
218 |  t/given_when.t .. ok   
219 |  t/when.t ........ ok   
220 |  All tests successful.
221 |  Files=4, Tests=48,  0 wallclock secs
222 |  ( 0.06 usr  0.02 sys +  0.14 cusr  0.03 csys =  0.25 CPU)
223 |  Result: PASS
224 |  $ sudo make install
225 |  [...]
226 |  Appending installation info to /opt/local/lib/.../perllocal.pod
227 |  $ cd ..
228 |  $ rm -fr Try-Tiny-0.09*
229 | 
230 | =end screen
231 | 
232 | A brief explanation of the issued commands follows:
233 | 
234 | =begin small
235 | 
236 | =over
237 | 
238 | =item *
239 | 
240 | B<Line 1:> uncompress the tarball. The command used is the more common
241 | for most Unix/BSD systems. It might be similar under Windows if you
242 | have GNU tools installed. If not, you can download a tool to
243 | uncompress these kind of files, like C<7zip> or C<IzArch>.
244 | 
245 | =item *
246 | 
247 | B<Line 2:> go to the folder created after uncompressing the tarball.
248 | 
249 | =item *
250 | 
251 | B<Line 3:> run C<perl> against the C<Makefile.PL> file, to configure the
252 | module. Note that some modules use a different build system, named
253 | C<Module::Build> X<Module, Module::Build> X<Module::Build> instead of
254 | C<ExtUtils::MakeMaker> X<Module, ExtUtils::MakeMaker>
255 | X<ExtUtils::MakeMaker>, the one responsible for C<Makefile.PL>. In
256 | this case, you should run C<perl> against the C<Build.PL> file:
257 | 
258 |    perl Build.PL
259 | 
260 | =item *
261 | 
262 | B<Line 8:> this step is the process of building the module files. When the module
263 | is just composed by Perl modules, this step just copy some files from
264 | different places to a temporary staging folder named C<blib>. If the
265 | module includes C<C> code, this step will also compile it.
266 | 
267 | Depending on your system C<make> might be named C<nmake> or
268 | C<dmake>. Also, if in the previous step you needed to use C<Build.PL>,
269 | then instead of C<make> you should run the newly created C<Build>
270 | file.
271 | 
272 | =item *
273 | 
274 | B<Line 11:> after compiling the module it is a good idea to test if
275 | your module is passing all the tests defined by the developers. To
276 | test your newly compiled module run C<< make test >> or C<< ./Build test
277 | >> depending on the module you are installing.
278 | 
279 | =item *
280 | 
281 | B<Line 21:> finally, time to install the module. Just run C<< make
282 | install >> or C<< ./Build install >>. It might be a good idea to run
283 | this command as superuser (for example, prepending C<sudo> to the
284 | command) as, by default, modules are installed system-wide into a directory to
285 | which normal users will not have write access..
286 | 
287 | =back
288 | 
289 | =end small
290 | 
291 | =head1 Installing Modules Locally
292 | 
293 | Perl lets you install modules on non standard directories. This is
294 | relevant if you are not the system administrator and need to install
295 | modules in your home directory, of if you like to have some modules
296 | installed on different paths for different projects.
297 | 
298 | =head2 *Configuring CPAN for a Non-Standard Path
299 | 
300 | When using the usual CPAN clients (C<cpan> and C<cpanp>) it is
301 | possible to define some variables where the modules will be installed.
302 | Enter the CPAN shell and configure the variables C<makepl_arg> and
303 | C<mbuild_arg>. They are the default arguments when running
304 | C<Makefile.PL> or C<Build.PL>. The following screen shows the
305 | interaction with C<cpan> to set the installation base to
306 | C</home/user/mymodules>.
307 | 
308 | =begin screen Configuring CPAN install base
309 | 
310 |   $ cpan
311 |   cpan> o conf makepl_arg INSTALL_BASE=/home/user/mymodules
312 |   cpan> o conf mbuild_arg "--install_base /home/user/mymodules"
313 |   cpan> o conf commit 
314 | 
315 | =end screen
316 | 
317 | After this, every time you run the C<cpan> shell, these configuration
318 | variables will be loaded, and will be used when installing modules. You
319 | will not need to configure the client again.
320 | 
321 | To use the modules installed in this location you have two
322 | options. The first is to define an environment variable named
323 | C<PERL5LIB>X<PERL5LIB> with the path where your modules got installed:
324 | 
325 |   export PERL5LIB=/home/user/mymodules
326 | 
327 | Unfortunately the Perl 5 installation path is quite complicated, and
328 | probably you will need to define more than one path:
329 | 
330 | =begin small
331 | 
332 |  export PERL5LIB=/home/user/mymodules:/home/user/mymodules/5.14.0/:
333 |  /home/user/mymodules/site_perl/5.14.0/:/home/user/mymodules/site_perl/
334 | 
335 | =end small
336 | 
337 | A more interesting and versatile method is to use the C<lib> pragma in
338 | the beginning of all your script files, followed by the path names
339 | where to find modules:
340 | 
341 |   use lib '/home/user/mymodules';
342 |   
343 | =head2 *Using C<local::lib> Module
344 | 
345 | X<Module, local::lib> X<local::lib>
346 | 
347 | The module C<local::lib> makes it easier to have a module tree in your
348 | home (by default, C<~/perl5>), install modules and use them. To start
349 | with, you need C<local::lib> in your system. If your system doesn't
350 | have this module installed and your administrator is not willing to
351 | install it, you can install it using the I<bootstrapping> technique.
352 | 
353 | First, download the C<local::lib> tarball from a CPAN mirror. Extract
354 | it, and run:
355 | 
356 |    perl Makefile.PL --bootstrap
357 | 
358 | The system should ask you some questions. You can let it configure as
359 | much as possible automatically. Then, run:
360 | 
361 |    make test && make install
362 | 
363 | After this, you need to set up your environment variables. You can the
364 | list of environment variables to define running:
365 | 
366 |    perl -I$HOME/perl5/lib/perl5 -Mlocal::lib
367 | 
368 | Add the output of this command to your C<~/.bashrc> or your
369 | C<~/.cshrc> file, depending on the shell you are running (Bourne shell
370 | or C shell, respectively). After this step you might need to reload
371 | the config file (or close and open a new shell).
372 | 
373 | To install modules use one of the following command lines:
374 | 
375 |   cpan -I Module::Name
376 |   cpanm -l Module::Name
377 | 
378 | As some of these commands just works on recent versions, you can use
379 | instead:
380 | 
381 |   perl -MCPAN -Mlocal::lib -e 'CPAN::install("Module::Name")'
382 | 
383 | Now, you can write your scripts adding the following line in the
384 | beginning of your file:
385 | 
386 |   use local::lib;
387 | 
388 | If you prefer to use the C<lib> pragma, you can use:
389 | 
390 |   use lib '/home/user/perl5';
391 | 
392 | =head2 *Using App::perlbrew
393 | 
394 | X<Module, App::perlbrew> X<App::perlbrew>
395 | 
396 | C<App::perlbrew> is something completely different. Its main purpose
397 | is not to install Perl modules locally, but to install a B<full> Perl
398 | version locally. First of all, install the module. Although you can
399 | install the module like a standard one, the author defends that the
400 | best installation procedure is to execute the following command on
401 | your shell:
402 | 
403 |       curl -L http://xrl.us/perlbrewinstall | bash
404 | 
405 | This will install C<perlbrew> in your home folder, under
406 | C<~/perl5/perlbrew/bin>. After installation, follow the on-screen
407 | instructions to set up your C<.bashrc> or C<.cshrc> to define the
408 | correct environment variables.
409 | 
410 | After this you need to reload your shell configuration files or start
411 | a new shell session. To initialize the C<perlbrew> folders run:
412 | 
413 |       perlbrew init
414 | 
415 | Then, a good idea is to install a local C<cpanm> to your C<perlbrew>
416 | installation. This can be easily done by:
417 | 
418 |       perlbrew install-cpanm
419 | 
420 | And now everything is set to start using C<App::perlbrew>.
421 | 
422 | =over
423 | 
424 | =item B<Installing a Perl version>
425 | 
426 | C<perlbrew> is great if you need more than one Perl version installed
427 | in your system. For example, because if you are a module developer and
428 | want to test your software against different Perl versions, or because
429 | you have different Perl projects that depend on different Perl
430 | versions.
431 | 
432 | To install a Perl version using C<perlbrew> is simple. Just issue the
433 | command:
434 | 
435 |    perlbrew install perl-5.14.0
436 | 
437 | You just need to know the official version name. If everything goes
438 | well you should end up with a new Perl installed in your home. For
439 | Perl 5.14.0, it will get installed on (using default the configuration
440 | values):
441 | 
442 |    ~/perl5/perlbrew/perls/perl-5.14.0/bin/perl
443 | 
444 | =item B<Switching from Perl versions>
445 | 
446 | Having more than on Perl installed in the system it gets crucial to
447 | know what Perl versions are installed, and to switch from different
448 | Perl versions. A list of the Perl versions installed in your system is
449 | available using:
450 | 
451 |    perlbrew list
452 | 
453 | It lists the name or the path to the Perl interpreter, and its
454 | versions. The current Perl version is marked with an asterisk. You can
455 | use a Perl version temporarily for the current shell with:
456 | 
457 |    perlbrew use perl-5.14.0
458 | 
459 | All consequent commands will use that Perl version, but any other
460 | shell or new shell will still use the previous Perl interpreter.
461 | To switch to other Perl interpreter globally (for your user) use:
462 | 
463 |    perlbrew switch perl-5.14.0
464 | 
465 | =item B<Installing modules>
466 | 
467 | The modules installation is simple. Switch to the Perl where you want
468 | to install the module, and use C<cpanm>:
469 | 
470 |    cpanm Module::Name
471 | 
472 | The module will be installed in the tree for that specific Perl. This
473 | means that every time you switch from Perl version an installed module
474 | can be no longer available.
475 | 
476 | =back
477 | 
478 | Although C<perlbrew> is quite interesting and powerful, it is still
479 | under heavy development and has some known problems. To use it well
480 | you need some expertise. For further documentation check the
481 | C<perlbrew> page.
482 | 
483 | =cut
484 | 
485 | ## Local Variables:
486 | ##  ispell-local-dictionary: "english"
487 | ##  mode: flyspell
488 | ## End:
489 | 


--------------------------------------------------------------------------------
/CPAN/chapters/10-oo.pod:
--------------------------------------------------------------------------------
  1 | 
  2 | =head0 Modern Perl OO
  3 | 
  4 | Z<chap:OO>
  5 | 
  6 | X<Moo>X<Module, Moo> X<Moose>X<Module, Moose> X<Mouse>X<Module, Mouse>
  7 | X<OO Programming> Perl always suffered from the lack of a rigid object
  8 | oriented system. Although blessed references did the trick for years,
  9 | developers felt sorry they did not have support for some common OO
 10 | features, like interfaces (or roles), multiple inheritance and
 11 | encapsulation.
 12 | 
 13 | A few years ago C<Moose> appeared. It revolutionized the OO world of
 14 | Perl. During these years it has been enriched with a lot of relevant
 15 | and useful features.
 16 | 
 17 | Nevertheless, C<Moose> still imposes a delay upon initial compilation
 18 | and startup, which can be problematic for applications like CGI
 19 | scripts, which are parsed and run every time a request is made, for
 20 | which the overhead of loading C<Moose> may not be acceptable.
 21 | 
 22 | To minimize this problem some developers started C<Mouse>, a smaller
 23 | implementation that does not include all C<Moose> functionalities, but
 24 | only the more relevant ones. It maintains the API compatibility with
 25 | C<Moose>, making it easier to switch whenever needed.
 26 | 
 27 | Another implementation, named C<Moo>, claims to be yet smaller and
 28 | faster than C<Mouse>, although at the time of writing, it still has a relatively
 29 | small userbase in comparison.
 30 | 
 31 | Given that all these modules share the same basic syntax, this chapter
 32 | structure will be slightly different from the next ones. First, we
 33 | will present C<Moo>, then, what C<Mouse> offers over C<Moo>, and
 34 | finally, what C<Moose> offers in addition.  It is hoped that this approach 
 35 | will make this chapter smaller and more helpful to the reader when choosing one
 36 | implementation.
 37 | 
 38 | =head1 Moo
 39 | 
 40 | X<Moo>X<Module, Moo>
 41 | 
 42 | =begin CPANinfo
 43 | 
 44 | B<Version:> 0.009008
 45 | 
 46 | B<CPAN:> L<http://search.cpan.org/dist/Moo>
 47 | 
 48 | =end CPANinfo
 49 | 
 50 | C<Moo> uses the usual approach to define objects: use packages (the
 51 | Perl equivalent to what we are used to call classes).
 52 | 
 53 | =head2 *Attributes
 54 | 
 55 | There follows a simple example of a I<Person> object with two attributes,
 56 | I<name> and I<phone>. The first is a read only attribute (you can't
 57 | change the person's name after initializing the object) while the second
 58 | has read/write permissions. This information is used by C<Moo> to
 59 | define whether to create accessors that are able to set and get
 60 | values, or just get values. The I<required> option means that every
 61 | time a I<Person> object is created a name must be providedN<< All
 62 | packages in Perl should return a true value after successful
 63 | load. That is why they usually have a last line with C<1;>.  In the
 64 | following examples we will add that line every time the example is a
 65 | full package. >>.
 66 | 
 67 | =begin Perl
 68 | 
 69 |  package Person;
 70 |  use Moo;
 71 | 
 72 |  has name  => ( is => 'ro',  required => 1 );
 73 |  has phone => ( is => 'rw' );
 74 |  1;
 75 | 
 76 | =end Perl
 77 | 
 78 | Note that the "fat comma" arrow  is equivalent to a comma, and the parenthesis
 79 | are not needed. The first attribute could be defined as:
 80 | 
 81 |   has "name", "is", "ro", "required", 1;
 82 | 
 83 | but its legibility is not the same. Therefore we will stick to the
 84 | usage of the fat comma arrow together with parenthesis or indentation to
 85 | group attribute options.
 86 | 
 87 | This object usage is similar to the usage of standard blessed
 88 | reference objects. C<Moo> creates the constructor and accessors automatically
 89 | for you.
 90 | 
 91 | =begin Perl
 92 | 
 93 |  use Person;
 94 | 
 95 |  my $person = Person->new(name => 'John');
 96 |  print $person->name;
 97 | 
 98 |  $person->phone("93453423");
 99 |  print $person->phone;
100 | 
101 | =end Perl
102 | 
103 | Unlike the next two alternatives, C<Moo> doesn't have a type
104 | system. If you need to guarantee that an attribute keeps a specific
105 | type of data, you need to validate it yourself. That is done by adding a
106 | code reference. The next example is a redefinition of the attribute
107 | C<phone> requiring the value to consist of nine numeric digits:
108 | 
109 | =begin Perl
110 | 
111 |  has phone =>
112 |       is  => 'rw',
113 |       isa => sub {
114 |          die "Need a nine digit string!" unless $_[0] =~ /^\d{9}$/
115 |       };
116 | 
117 | =end Perl
118 | 
119 | Attributes can have default values. This is specified using the
120 | C<default> option. It takes a code reference that receives the object,
121 | and should return the new value. Note that you should not rely on
122 | other attributes for this initialization as there is no guarantee that
123 | they were already populated (for that use I<lazy> attributes). As an
124 | example, you can create an attribute C<gender> and define it
125 | automatically to I<female> if not specified.
126 | 
127 | =begin Perl
128 | 
129 |  has gender =>
130 |       is => 'ro',
131 |       default => sub { return 'female' };
132 | 
133 | =end Perl
134 | 
135 | If the default value needs to be computed based on other attributes, or
136 | the task of computing it is time or CPU expensive, you can define the
137 | attribute as I<lazy> (set it to a true value). This way the value will
138 | only be computed when it is first accessed.
139 | 
140 | When some code should run after a specific attribute is set a
141 | C<trigger> should be used. It is just a code reference that will be
142 | called over the object (receiving the object as the first parameter), with the 
143 | new value as the second param. For instance, when a phone number is registered,
144 | call some function to send a SMS to the new number acknowledging the change:
145 | 
146 | =begin Perl
147 | 
148 |  has phone =>
149 |       is  => 'rw',
150 |       isa => sub {
151 |          die "Need a nine digit string!" unless $_[0] =~ /^\d{9}$/
152 |       },
153 |       trigger => sub {
154 |          my ($self, $new_number) = @_; 
155 |          send_sms( to  => $new_number,
156 |                    msg => "Hello there " . $self->name 
157 |                        . ", phone number correctly updated, thanks!")
158 |       };
159 | 
160 | =end Perl
161 | 
162 | =head2 *Inheritance and Roles
163 | 
164 | The usual inheritance between classes is also possible. In fact,
165 | C<Moo> supports multiple super-classes. They are defined with the
166 | C<extends> methodN<< Calling C<extends> more than once will B<replace>
167 | the super-classes, not add a new. >>:
168 | 
169 | =begin Perl
170 | 
171 |  package Student;
172 |  use Moo;
173 |  extends 'Person';
174 | 
175 |  has final_grade => ( is => 'rw' );
176 |  1;
177 | 
178 | =end Perl
179 | 
180 | One of C<Moo>'s sacrifices to remain small is to not support
181 | C<super>. This means it is not that easy to override
182 | methods. Nevertheless it can be done using method modifiers (see
183 | A<moomodifiers>).
184 | 
185 | If the code being extended (the super-class) will never be
186 | instantiated, probably you want to use I<roles>. I<Roles> can be seen
187 | as the Java interfaces, or as a specific set of methods that implement
188 | a specific functionality. C<Moo> roles are defined using the
189 | C<Role::Tiny> X<Module, Role::Tiny> X<Role::Tiny> module.
190 | 
191 | The definition of a role is simple. Create a brand new package, use
192 | C<Role::Tiny>, and write all the code the role should implement. As a
193 | simple example consider a role that dumps the object to the standard
194 | error (useful for debugging):
195 | 
196 | =begin Perl
197 | 
198 |  package Role::Dumper;
199 |  use Moo;
200 |  use Role::Tiny;
201 |  use Data::Dumper;
202 | 
203 |  sub dump {
204 |    my $self = shift;
205 |    print STDERR Dumper($self);
206 |  }
207 | 
208 |  1;
209 | 
210 | =end Perl
211 | 
212 | Now, you can switch from role to role using C<with>. For simplicity
213 | C<Moo> activates only one role at a time. Our class now can call
214 | C<dump> on a C<Person>:
215 | 
216 | =begin Perl
217 | 
218 |  package Person;
219 |  use Moo;
220 | 
221 |  ...
222 | 
223 |  my $person = Person->new(name => 'Mary', phone => '987654321');
224 | 
225 |  with 'Role::Dumper';
226 |  $person->dump;
227 | 
228 | =end Perl
229 | 
230 | Note that the C<dump> method is not implemented in the I<Person>
231 | class, but rather in the role. This means you can activate this role
232 | for any object.
233 | 
234 | =head2 *Method Modifiers
235 | 
236 | Z<moomodifiers>X<Class::Method::Modifiers>X<Module, Class::Method::Modifiers>
237 | 
238 | The method modifiers described here are not really part of the object
239 | system, but are available in C<Moo> as a workaround for some
240 | limitations, like the lack of access to C<super>. They are implemented
241 | though the C<Class::Method::Modifiers> module that can be used
242 | independently.
243 | 
244 | These methods can be viewed as hooks that are called before and/or
245 | after some methods are called. As an example, we want to add a line of
246 | debug before dumping a person. Therefore, in the C<Person.pm> file we
247 | will switch to the role that implements C<dump>, and activate a
248 | modifier, asking to run some code before the actual method:
249 | 
250 | =begin Perl
251 | 
252 |    with 'Role::Dumper';
253 |    before dump => sub { print STDERR "Dumping a Person!\n" };
254 | 
255 | =end Perl
256 | 
257 | The method will receive the same arguments as the method
258 | itself. Return values are ignoredN<< In fact, you can can change C<@_>
259 | directly, and the changed values will be received by the original
260 | method. But this approach is not suggested. Use C<around> instead. >>.
261 | 
262 | C<after> works in the same way, and receives C<@_> as the original
263 | method received. This means that if the original method changes the
264 | values, C<after> will receive them modified.
265 | 
266 | Finally, there is C<around>, that is called instead of the original
267 | method. This means that the code run should call the original method
268 | (if needed, or just ignore it). For that to be possible, the code you
269 | define will receive as first argument the method that is being
270 | replaced. Suppose you have a role that implements a method similar
271 | to that  described above, to send a SMS message, but which uses the
272 | phone number stored in the object, but you need to add a prefix to the
273 | number ("+0", for instance) before calling it, and that you need to
274 | get the result (a boolean) and transform it into a string "OK" or
275 | "NOK":
276 | 
277 | =begin Perl
278 | 
279 |   with 'SMS::Role';
280 |   around send_sms => sub { 
281 |            my ($orig, $self, $message) = @_;
282 | 
283 |            my $number = $self->phone; # save number
284 |            $self->phone("+0$number");
285 |            my $ok = $self->$orig($message);
286 |            $self->phone($number); # revert number
287 |            return $ok ? "OK" : "NOK";
288 |   }
289 | 
290 | =end Perl
291 | 
292 | =head1 Mouse
293 | 
294 | X<Mouse>X<Module, Mouse>
295 | 
296 | =begin CPANinfo
297 | 
298 | B<Version:> 0.93
299 | 
300 | B<CPAN:> L<http://search.cpan.org/dist/Mouse>
301 | 
302 | =end CPANinfo
303 | 
304 | As mentioned in this chapter introduction C<Mouse> aims to be a subset
305 | implementation of C<Moose>, with fewer dependencies, with an optional
306 | XS back-end (meaning you will not necessarily need a C<< C >>
307 | compiler) and reducing the C<Moose> startup time.
308 | 
309 | =head2 *Attributes
310 | 
311 | The syntax for defining attributes is the same C<Moo> uses. The first
312 | main difference is that C<Mouse> introduces a type system, instead of
313 | the code reference that C<Moo> uses to check values types. Some of
314 | C<Mouse> data types are: C<Any> to store anything, C<Bool> for boolean
315 | values, C<Str> to store a string or a number, just like Perl scalar
316 | variables handle them, C<Num> for numbers, including reals, C<Int> for
317 | integer numbers, C<ClassName> when you are storing a object class
318 | name, C<Ref> for any kind of reference, C<ScalarRef> for a reference
319 | to a scalar, C<ArrayRef> to a reference to an array, C<HashRef> to a
320 | reference to hashes, C<RegexpRef> for regular expressions, etc. You
321 | can get a detailed list and their relationship in the
322 | C<Mouse::Util::TypeConstraints>. This
323 | module also allows you to define sub-types based on the built-in
324 | types. Finally, if you define a type name that is unknown, C<Mouse>
325 | will interpret it as the name of a class that should be checked using
326 | C<ref>.
327 | 
328 | The C<default> value for the attribute can be set like with C<Moo>
329 | using a code reference, but it is also possible to specify directly a
330 | scalar value (you can not use references).
331 | 
332 | Our I<Person> class is written with C<Mouse> as follows:
333 | 
334 | =begin Perl
335 | 
336 |  package Person;
337 |  use Mouse;
338 | 
339 |  has name =>  (
340 |       is => 'ro', required => 1,  isa => 'Str',
341 |  );
342 | 
343 |  has phone => (
344 |       is      => 'rw',
345 |       isa     => 'Str',
346 |       trigger => sub {
347 |          send_sms( to => $_[1],
348 |                    msg => "Phone number correctly updated.")
349 |       },
350 |   );
351 | 
352 |  has gender => (
353 |       is => 'ro', default => "female",
354 |  );
355 | 
356 |  1;
357 | 
358 | =end Perl
359 | 
360 | There are some relevant differences in this code. First, we are not
361 | requiring the phone number to have nine digits. Check
362 | A<typeconstraints> for a solution through subtypes. The other
363 | difference is more subtle: the C<trigger> method receives the same
364 | first two arguments as the C<Moo> example, but a third argument is
365 | also supplied: the value before the attribution takes place.
366 | 
367 | =head2 *Inheritance and Roles
368 | 
369 | Inheritance in C<Mouse> is also handled using the C<extends> method.
370 | You an redefine completely any attribute:
371 | 
372 |    has name => ( is => 'rw', isa => 'Str' );
373 | 
374 | Or you can use the superclass attribute definition as the base for
375 | your new definition. If the line above this paragraph was in a
376 | superclass, we can redefine the attribute as required with:
377 | 
378 |    has +name => ( required => 1 );
379 | 
380 | This would maintain the C<is> and C<isa> properties, and add the
381 | C<required> flag.
382 | 
383 | Regarding roles (handled by C<Mouse::Role> X<Mouse::Role> X<Module,
384 | Mouse::Role>), they are very similar in behavior with C<Moo> roles.
385 | 
386 | The main difference is that a C<Mouse::Role> can require that the
387 | object that uses it implements some methods. That is specified with
388 | the C<requires> method. As an example, consider a role that adds
389 | arithmetic to any object that can be converted to a real value. For
390 | that to be possible, the object must implement a method named
391 | C<value>.  The role will use this method to perform the arithmetic
392 | operation.
393 | 
394 | =begin Perl
395 | 
396 |   package Arithmetics;
397 |   use Mouse::Role;
398 | 
399 |   requires 'value';
400 | 
401 |   sub add {
402 |     my ($self, $other) = @_;
403 |     return $self->value + $other->value;
404 |   }
405 | 
406 |   1;
407 | 
408 | =end Perl
409 | 
410 | Now, an object which represents stock exchange values can add stock
411 | values together:
412 | 
413 | =begin Perl
414 | 
415 |   package Stocks;
416 |   use Mouse;
417 | 
418 |   has name  => ( is => 'rw', isa => 'Str' );
419 |   has qt    => ( is => 'rw', isa => 'Int' );
420 |   has price => ( is => 'rw', isa => 'Num' );
421 | 
422 |   sub value {
423 |     my $self = shift;
424 |     return $self->qt * $self->price;
425 |   }
426 | 
427 |   with 'Arithmetics';
428 | 
429 |   my $stock1 = Stocks->new( qt => 10, price => 1.1 );
430 |   my $stock2 = Stocks->new( qt => 5,  price => 4.3 );
431 |   my $total_amount = $stock1->add($stock2);
432 | 
433 |   1;
434 | 
435 | =end Perl
436 | 
437 | Note that you can use an accessor to satisfy the role
438 | C<requires>. This object that represents a product and its market
439 | value would work as well:
440 | 
441 | =begin Perl
442 | 
443 |   package Product;
444 |   use Mouse;
445 | 
446 |   has name  => ( is => 'rw', isa => 'Str' );
447 |   has value => ( is => 'rw', isa => 'Int' );
448 | 
449 |   with 'Arithmetics';
450 | 
451 |   my $prod1 = Product->new( value => 3 );
452 |   my $prod2 = Product->new( value => 5 );
453 |   my $total_prods = $prod1->add($prod2);
454 | 
455 |   1;
456 | 
457 | =end Perl
458 | 
459 | You just need to make sure that the line with the C<has> that defines
460 | the attribute which accessor will satisfy the requirements is defined
461 | before composing the role. With this role you can even add different
462 | type of classes, given they satisfy the C<Arithmetics> role.
463 | 
464 | As a final note, note that unlike C<Moo>, C<Mouse> supports more than
465 | one role at a time.
466 | 
467 | =head2 *Method Modifiers
468 | 
469 | C<Mouse> supports C<before>, C<after> and C<around>, just like C<Moo>
470 | The main difference is that they accept a regular expression, and will
471 | apply the modifier to all the methods that match the expression.
472 | 
473 | =head2 *Type Constraints
474 | 
475 | Z<typeconstraints> X<Module,
476 | Mouse::Util::TypeConstraints> X<Mouse::Util::TypeConstraints>
477 | 
478 | To have built-in types is a cool feature, but can be limiting. If you
479 | compare our I<Person> example using C<Moo> and C<Mouse>, you will
480 | notice that C<Moo> restricts phone numbers to have only a fixed amount
481 | digits while C<Mouse> accepts any string.
482 | 
483 | The solution to make C<Mouse> more picky about its values is to define
484 | new data types. This is performed using the
485 | C<Mouse::Util::TypeConstraints> module, that defines new data types
486 | based on C<Mouse> basic types.
487 | 
488 | =begin Perl
489 | 
490 |   use Mouse::Util::TypeConstraints;
491 | 
492 |   subtype 'PhoneNumber'
493 |     => as 'Str'
494 |     => where { m/^\d{9}$ }
495 |     => message { "The string ($_) is not a valid phone number." };
496 | 
497 | =end Perl
498 | 
499 | This code specifies the base data type (String), a code block that
500 | returns true for valid values, and a code block with the action or
501 | message that should be performed when the value is not valid.
502 | 
503 | We can enhance our I<Person> class with some more interesting data
504 | types. For example, we know that the gender value will be one of I<male>
505 | or I<female>:
506 | 
507 |    enum 'Gender' => ('male', 'female');
508 | 
509 | C<Mouse::Util::TypeConstraints> allows the user to specify how to
510 | convert between data types. For instance, if we have a C<Time> data
511 | type that is defined in a string, that contains information on number
512 | of minutes and number of seconds, we can tell how to convert it to a
513 | number (computing the total number of seconds, for instance):
514 | 
515 | =begin Perl
516 | 
517 |   use Mouse::Util::TypeConstraints;
518 | 
519 |   subtype 'Time'
520 |     => as 'Str' => where { m[/^ \d+ m \d+ s $]x };
521 | 
522 |   coerce 'Num'
523 |     => from 'Time'
524 |     => via { m[^ (\d+) m (\d+) s $]x; $1*60+$2 };
525 | 
526 | =end Perl
527 | 
528 | The C<Time> value can be coerced to a number filling some object
529 | attribute. The only requirement is that the attribute has the
530 | C<coerce> option to true. The following example presents two
531 | attributes, one for a C<Time> value, than whenever is changed,
532 | triggers the update of the number of seconds.  The opposite would be
533 | also possible after defining a C<coerce> rule from C<Num> to C<Time>.
534 | 
535 | =begin Perl
536 | 
537 |   has time => (
538 |     is      => 'rw',
539 |     isa     => 'Time',
540 |     trigger => { 
541 |        my ($self, $value) = @_;
542 |        $self->seconds($value);
543 |     },
544 |   );
545 | 
546 |   has seconds => (
547 |     is     => 'rw',
548 |     isa    => 'Num',
549 |     coerce => 1,
550 |   );
551 | 
552 | =end Perl
553 | 
554 | It is part of the good practices to unload the module as soon as you
555 | defined your types (this will undefine all the syntactic sugar
556 | exported by the module):
557 | 
558 |    no Mouse::Util::TypeConstraints;
559 | 
560 | =head2 *Meta-Model
561 | 
562 | X<Module, Mouse::Meta::Class> X<Mouse::Meta::Class>
563 | 
564 | Another interesting feature of C<Mouse> (and C<Moose>) is the ability
565 | to query and change the object meta information (known in this context
566 | as meta-model). This meta-model defines the structure of the object:
567 | which attributes are defined, their definition details, whose methods
568 | are defined, its hierarchy and possible roles.
569 | 
570 | To query a class meta-model you need to have an instance of it. The
571 | easiest way to access it (from inside the class definition file) is
572 | using:
573 | 
574 |    my $meta = __PACKAGE__->meta;
575 | 
576 | Some of the B<methods> you can call on a meta-model object are:
577 | 
578 | =over
579 | 
580 | =item C<superclasses>
581 | 
582 | is an accessor that retrieves the list of all super-classes for that
583 | class. It can also be used to set them.
584 | 
585 |    my @superclases = $meta->superclasses();
586 | 
587 | =item C<has_method>
588 | 
589 | returns a boolean value given a method name. The value will be true
590 | if the class implements that method:
591 | 
592 |    $meta->has_method("compare");
593 | 
594 | =item C<add_method>
595 | 
596 | lets you add method to the class. It receives the method name and the
597 | reference to a code block:
598 | 
599 |    $meta->add_method( dump => sub {
600 |            use Data::Dumper; Dumper($_[0]); 
601 |    });
602 | 
603 | =item C<has_attribute>
604 | 
605 | works just like C<has_method> but returns a true value if there is an
606 | attribute with the supplied name:
607 | 
608 |    $meta->has_attribute("gender");
609 | 
610 | =item C<add_attribute>
611 | 
612 | lets you add a new attribute, works mostly like C<has>, but over a
613 | meta-class object:
614 | 
615 |    $meta->add_attribute("age", is => "rw", isa => "Int");
616 | 
617 | =back
618 | 
619 | Some of these methods are polymorphic, and can cope with other type of
620 | arguments. There are accessors to attributes and methods, just like
621 | the setters explained above. This section will finish here. For
622 | further documentation please read C<Mouse::Meta::Class> for a list of
623 | the available methods, and C<Moose::Meta::Class> for their
624 | explanation.
625 | 
626 | =head1 Moose
627 | 
628 | X<Moose>X<Module, Moose>
629 | 
630 | =begin CPANinfo
631 | 
632 | B<Version:> 2.0007
633 | 
634 | B<CPAN:> L<http://search.cpan.org/dist/Moose>
635 | 
636 | =end CPANinfo
637 | 
638 | The path between C<Mouse> and C<Moose> is simple, as C<Mouse> was
639 | designed for compatibility. But C<Moose> has much more features as we
640 | will see. In-depth discussion on C<Moose> can be read on Dave Rolsky
641 | and Stevan Little book available from LuluN<<
642 | L<http://www.lulu.com/product/paperback/moose/5187831> >>.
643 | 
644 | =head2 *Attributes
645 | 
646 | C<Moose> attributes basic functionalities are similar to C<Mouse>
647 | attributes. There are few extra functionalities, like the definition
648 | of C<traits> or C<handles>, but these will not be covered in this
649 | book. Please read the C<Moose> manual page for details.
650 | 
651 | =head2 *Inheritance and Roles
652 | 
653 | C<Moose> makes it possible to require that a superclass or a role
654 | being imported satisfy a minimum module version. That is done passing
655 | a hash reference after each superclass or role:
656 | 
657 |   extends 'Some::Parent'  => { -version => 3.20 },
658 |           'Other::Parent' => { -version => 1.03 };
659 | 
660 | The syntax for roles is similar, just replace C<extends> with
661 | C<with>. Roles are defined by the C<Moose::Role> X<Moose::Role>
662 | X<Module, Moose::Role> module.
663 | 
664 | =head2 *Method Modifiers
665 | 
666 | C<Moose> extends the three basic method modifies (C<before>, C<after>
667 | and C<around>) with some new:
668 | 
669 | =over
670 | 
671 | =item C<override>
672 | 
673 | Receive the name of the method being overridden, and the
674 | code. Although the same behavior can be obtained without using
675 | C<override> and defining a standard function, using C<override> will
676 | make it clearer that you are overriding the method. Inside your code
677 | you can call C<super> to access this method original definition in the
678 | superclass.
679 | 
680 | =item C<augment>
681 | 
682 | The C<augment> method modifier is not easy to explain. You can see it
683 | as the inverse of C<override>, and its companion method C<inner> as
684 | the inverse of C<super>. When you call an C<augment>ed method,
685 | C<Moose> will start with the top superclass definition, and substitute
686 | its C<inner> invocation by its child C<augment> code. This process
687 | will be repeated until you reach the bottom class. A complete example
688 | of this functionality is described in
689 | C<Moose::Cookbook::Basics::Recipe6>.
690 | 
691 | =back
692 | 
693 | =head2 *Type Constraints
694 | 
695 | X<Moose::Util::TypeConstraints> X<Module, Moose::Util::TypeConstraints>
696 | 
697 | Basic type constraints functionalities are similar with C<Mouse>. They
698 | are handled by the C<Moose::Util::TypeConstraints> module.
699 | 
700 | =head2 *Meta-Model
701 | 
702 | X<Moose::Meta::Class> X<Module, Moose::Meta::Class> C<Moose> meta
703 | class model is richer than C<Mouse> model, but again, their extended
704 | use is too advanced to be fully described here. You can read about its
705 | functionalities in C<Moose::Meta::Class>.
706 | 
707 | In addition to C<add_method> there are also C<add_override_method_modifier>
708 | and C<add_augment_method_modifier>.
709 | 
710 | There is the possibility to access all roles attached to a class with
711 | C<calculate_all_roles>.  Check if a specific class does a role with
712 | C<does_role>.
713 | 
714 | =begin SeeAlso
715 | 
716 | C<MooseX> is the namespace for Moose extensions. You can read
717 | C<Moose::Manual::MooseX> X<Moose::Manual::MooseX> X<Module,
718 | Moose::Manual::MooseX> for a list of some common and useful
719 | extensions. Follow some examples.
720 | 
721 | C<MooseX::StrictConstructor> X<MooseX::StrictConstructor> X<Module,
722 | MooseX::StrictConstructor> will make your module complain if you pass
723 | any attribute name to the constructor that is not defined (by default
724 | C<Moose> will quietly ignore any unknown attribute names).
725 | 
726 | C<MooseX::Getopt> X<Module, MooseX::Getopt> X<MooseX::Getopt> lets you
727 | define command line options as if they were standard C<Moose> attributes.
728 | 
729 | C<MooseX::Declare> X<Module, MooseX::Declare> X<MooseX::Declare> is
730 | used to define methods signature as you would in a typed language like
731 | C or Java. At the moment it is still in alpha stage, but there are
732 | high hopes on it.
733 | 
734 | If you use a basic subset of C<Moose> you might want to use
735 | C<Any::Moose> X<Any::Moose> X<Module, Any::Moose>. This module will
736 | load C<Moose> or C<Mouse> accordingly with the modules available on
737 | your system. The following lines can be used to load the object
738 | system, the role system and the type constraints system:
739 | 
740 |   use Any::Moose;                           # for classes
741 |   use Any::Moose 'Role';                    # for roles
742 |   use Any::Moose '::Util::TypeConstraints'; # for types
743 | 
744 | =end SeeAlso
745 | 
746 | =cut
747 | 
748 | ## Local Variables:
749 | ##  ispell-local-dictionary: "english"
750 | ##  mode: flyspell
751 | ## End:
752 | 
753 | 


--------------------------------------------------------------------------------
/CPAN/chapters/20-templates.pod:
--------------------------------------------------------------------------------
   1 | 
   2 | =head0 Template Engines
   3 | 
   4 | Templates are documents with place-holders that are filled with values
   5 | to produce final documents. For example, a corporate letter to send to
   6 | all employees in a company, where the name will be personalized.
   7 | 
   8 | The usage of templates is a typical methodology to separate code from
   9 | presentation, and are especially known for their relevance for web
  10 | frameworks that claim to follow the MVC (Model--View--Controller)
  11 | software architecture. Templates can be used to generate all type of
  12 | text: pure text, HTML, XML or even LaTeX documents.
  13 | 
  14 | There is a bunch of templating modules on CPAN. We chose three:
  15 | 
  16 | =over
  17 | 
  18 | =item C<Text::Template>
  19 | 
  20 | A simple template engine. It embeds Perl into the template text,
  21 | surrounding it by curly braces. This makes the template engine very
  22 | powerful and easy to understand by Perl programmers. In the other
  23 | hand, makes it hard to use by other users, like designers.
  24 | 
  25 | =item C<HTML::Template::Pro>
  26 | 
  27 | This is a reimplementation of C<HTML::Template>, but using some C<C>
  28 | code, making it faster. Its main advantage is being smaller than
  29 | C<Template::Toolkit>, have a syntax resembling HTML, and being
  30 | relatively fast.
  31 | 
  32 | =item C<Template::Toolkit>
  33 | 
  34 | The complete template engine, and probably the most common choice. It
  35 | is powerful, configurable and expendable. Has some dependencies,
  36 | namely the requirement for a C<C> compiler.
  37 | 
  38 | =item C<Text::Xslate>
  39 | 
  40 | This is a relatively new template engine, that has been getting the
  41 | attentions recently. It claims to be scalable, and fastest than
  42 | C<Template::Toolkit>. It defines a new syntax named Kolon, but also
  43 | includes a compatibility module that makes the migration from
  44 | C<Template::Toolkit> easier.
  45 | 
  46 | =back
  47 | 
  48 | =head1 Text::Template
  49 | 
  50 | X<Module, Text::Template>X<Text::Template>
  51 | 
  52 | =begin CPANinfo
  53 | 
  54 | B<Version:> 1.45
  55 | 
  56 | B<CPAN:> L<http://search.cpan.org/dist/Text-Template>
  57 | 
  58 | =end CPANinfo
  59 | 
  60 | This module was designed to produce any kind of text files. Its syntax
  61 | is not based in HTML or any other known mark-up language, but in Perl
  62 | blocks. This makes it easier to understand by any Perl programmer (but
  63 | harder for designers, for example).
  64 | 
  65 | The module is stable for some time: the last stable version is from
  66 | 2003! It doesn't have any dependency other than Perl itself, making it
  67 | easy to install in any Perl environment.
  68 | 
  69 | =head2 *Variable Notation
  70 | 
  71 | A template with simple place-holders is easy to define. Just create a
  72 | text file (or even a string) and curly bracesN<< If you do not like to
  73 | have curly braces as delimiters you can configure C<Text::Template> to
  74 | use some other characters. For example, C<< $tmpl->fill_in(DELIMITERS
  75 | => [ '[%', ']%' ]) >> would change the delimiters to C<[%> and C<%]>
  76 | respectively. >> to delimit the predefined text from the place-holders
  77 | variables:
  78 | 
  79 |    Dear { $name }:
  80 |    
  81 |    I am sorry to inform that you are fired. Your compensation
  82 |    is { $compensation{$name} } euro.
  83 |    
  84 |    Best regards, your boss.
  85 | 
  86 | As the example illustrates, you can insert any type of variable
  87 | between the curly braces. If the above text is saved in a file named
  88 | "C<fire.tmpl>" you can generate the text for a list of employees with
  89 | the following code:
  90 | 
  91 | =begin Perl
  92 | 
  93 |  use Text::Template;
  94 | 
  95 |  my $tmpl = Text::Template->new(SOURCE => 'fire.tmpl') or die;
  96 | 
  97 |  my %compensation = (John => 100, Mary => 300 );
  98 | 
  99 |  for my $employee (keys %compensation) {
 100 |    my $text = $tmpl->fill_in( HASH => {
 101 |                              name => $employee,
 102 |                      compensation => \%compensation });
 103 |    print $text;
 104 |  }
 105 | 
 106 | =end Perl
 107 | 
 108 | Line 3 creates a new C<Text::Template> object, specifying where the
 109 | template file it. If it fails returns an undefined variable. You can
 110 | use the C<$Text::Template::ERROR> variable in the C<die> command to
 111 | consult what happens when it fails.
 112 | 
 113 | Line 8 fills the template for each employee. The C<fill_in> method can
 114 | receive the variables to be filled in the template in two different
 115 | ways. In this case we are passing a hash reference, where keys are
 116 | variable names and their values the respective variable values.
 117 | 
 118 | Another option would be to specify a package where the variables will
 119 | come from. A variable C<$x> will be replaced by the C<$Package::x>.
 120 | 
 121 |   $tmpl->fill_in( PACKAGE => "Foo::Bar");
 122 | 
 123 | You can even suppress the package name, and C<Text::Template> will use
 124 | the current package. In this case the variables being shared with the
 125 | template engine should not be declared with C<my> but C<our>:
 126 | 
 127 | =begin Perl
 128 | 
 129 |  use Text::Template;
 130 | 
 131 |  my $tmpl = Text::Template->new(SOURCE => 'fire.tmpl') or die;
 132 | 
 133 |  our %compensation = (John => 100, Mary => 300);
 134 |  our $name;
 135 | 
 136 |  for  $name (keys %compensation) {
 137 |    my $text = $tmpl->fill_in();
 138 |    print $text;
 139 |  }
 140 | 
 141 | =end Perl
 142 | 
 143 | Take care when using the package approach. If you change variables'
 144 | values inside your template, they will be propagated back to your
 145 | code.
 146 | 
 147 | Another useful option to the C<fill_in> method is C<OUTPUT>. Its value
 148 | must be a file handle. The result of filling the template will be
 149 | printed to that file instead of being returned. The following code
 150 | will create a text file for each employee:
 151 | 
 152 | =begin Perl
 153 | 
 154 |  use Text::Template;
 155 | 
 156 |  my $tmpl = Text::Template->new(SOURCE => 'fire.tmpl') or die;
 157 | 
 158 |  our %compensation = (John => 100, Mary => 300);
 159 |  our $name;
 160 | 
 161 |  for  $name (keys %compensation) {
 162 |    open my $fh, ">", "$name.txt" or die;
 163 |    $tmpl->fill_in( OUTPUT => $fh );
 164 |    close $fh;
 165 |  }
 166 | 
 167 | =end Perl
 168 | 
 169 | =head2 *Complex structures
 170 | 
 171 | Did I tell you that you can write any Perl code inside
 172 | C<Text::Template> curly braces? But you can. And that is the way you
 173 | can add advanced functionality to your template. First, you can format
 174 | numbers calling the built-in command C<sprintf>:
 175 | 
 176 |   My current debt is { sprintf("%.2f", $value) } euro.
 177 | 
 178 | If you pass an array to the C<fill_in> method you can cycle the array
 179 | in your code:
 180 | 
 181 |   This is my wish list:
 182 |   { for $item (@wishlist) { $list .= " * $item\n"; } $list }
 183 | 
 184 | What this code does is cycle the C<wishlist> array and construct a
 185 | string with the text to be included in the template. At the end, we
 186 | return its content. C<Text::Template> makes a special variable C<$OUT>
 187 | available in your code, making the above code easier to read:
 188 | 
 189 |   This is my wish list:
 190 |   { for $item (@wishlist) { $OUT .= " * $item\n"; } $list }
 191 | 
 192 | With this variable and Perl code you can do mostly anything in your
 193 | template.
 194 | 
 195 | =head1 HTML::Template::Pro
 196 | 
 197 | X<Module, HTML::Template::Pro>X<HTML::Template::Pro>
 198 | X<Module, HTML::Template>X<HTML::Template>
 199 | 
 200 | =begin CPANinfo
 201 | 
 202 | B<Version:> 0.9504
 203 | 
 204 | B<CPAN:> L<http://search.cpan.org/dist/HTML-Template-Pro>
 205 | 
 206 | =end CPANinfo
 207 | 
 208 | C<HTML::Template::Pro> is an extended version of
 209 | C<HTML::Template>. Most of the functionalities are available on both,
 210 | but the C<::Pro> is faster as it is partially implemented in C<C>.
 211 | 
 212 | =head2 *Variable Notation
 213 | 
 214 | These modules were developed to generate HTML (although you can
 215 | generate anything with them). The syntax is similar to an HTML tagN<<<
 216 | With C<HTML::Template::Pro> is possible to write commands as if they
 217 | were XHTML tags: C<< <TMPL_VAR NAME='variable_name'/> >>. >>>:
 218 | 
 219 |    <TMPL_VAR NAME=variable_name>
 220 | 
 221 | The first part (C<TMPL_VAR>) is the command name (we'll see other
 222 | shortly) to include a variable value. Follows a key/value pair
 223 | pointing C<NAME> to the name of the place holder. Consider the
 224 | following HTML template:
 225 | 
 226 |    <p>Dear <TMPL_VAR NAME=name>:</p>
 227 |    
 228 |    <p>I am sorry to inform that you are fired. Your compensation
 229 |    is <TMPL_VAR NAME=compensation> euro.</p>
 230 |    
 231 |    <p>Best regards, your boss.</p>
 232 | 
 233 | This template can be filled with the following code:
 234 | 
 235 | =begin Perl
 236 | 
 237 |  use HTML::Template::Pro;
 238 | 
 239 |  my $tmpl = HTML::Template::Pro->new(filename => 'letter.tmpl');
 240 | 
 241 |  my %compensation = (John => 100, Mary => 300);
 242 | 
 243 |  for my $name (keys %compensation) {
 244 |    $tmpl->param( name         => $name ); 
 245 |    $tmpl->param( compensation => $compensation{$name} );
 246 |    print $tmpl->output();
 247 |  }
 248 | 
 249 | =end Perl
 250 | 
 251 | Changing the code above to generate a separate HTML file per letter:
 252 | 
 253 | =begin Perl
 254 | 
 255 |  use HTML::Template::Pro;
 256 | 
 257 |  my $tmpl = HTML::Template::Pro->new(filename => 'letter.tmpl');
 258 | 
 259 |  my %compensation = (John => 100, Mary => 300);
 260 | 
 261 |  for my $name (keys %compensation) {
 262 |    $tmpl->param( name         => $name,
 263 |                  compensation => $compensation{$name} );
 264 | 
 265 |    open my $fh, ">", "$name.html" or die;
 266 |    $tmpl->output(print_to => $fh);
 267 |    close $fh;
 268 |  }
 269 | 
 270 | =end Perl
 271 | 
 272 | As a final note, although the syntax is meant to simulate normal HTML
 273 | tags, you can use them inside HTML tags:
 274 | 
 275 |    <img src="<TMPL_VAR NAME=image_url>" />
 276 | 
 277 | This can even be simplified, if you prefer.
 278 | 
 279 |    <img src="<TMPL_VAR image_url>" />
 280 | 
 281 | =head2 *Complex structures
 282 | 
 283 | Complex data structures can be managed directly in the
 284 | template. C<HTML::Template::Pro> supports conditionals, loops or
 285 | complex Perl expressions.
 286 | 
 287 | Lists are typical structures in web pages (together with tables and
 288 | other information structuring elements). To generate a list using
 289 | C<HTML::Template::Pro> you use the C<TMPL_LOOP> tag, like in this
 290 | example:
 291 | 
 292 |    <ul>
 293 |       <TMPL_LOOP NAME=employees>
 294 |          <li>Name: <TMPL_VAR NAME=name> Age: <TMPL_VAR name=age></li>
 295 |       </TMPL_LOOP>
 296 |    </ul>
 297 | 
 298 | To make C<HTML::Template::Pro> unroll this loop you set a parameter
 299 | named C<employees> that is an array reference of hash references (one
 300 | hash reference per employee). Each hash reference will include two
 301 | keys, C<name> and C<age>, whose values would be used to fill in the
 302 | template:
 303 | 
 304 | =begin Perl 
 305 | 
 306 |   $tmpl->param( employees => [
 307 |                      { name => "John", age => 35 },
 308 |                      { name => "Mary", age => 27 },
 309 |                ]);
 310 | 
 311 | =end Perl
 312 | 
 313 | Nested loops work just as you expect:
 314 | 
 315 |    <ul>
 316 |       <TMPL_LOOP NAME=employees>
 317 |         <li><TMPL_VAR NAME=name> children:
 318 |             <ul>
 319 |                <TMPL_LOOP NAME=childs>
 320 |                    <li><TMPL_VAR NAME=name></li>
 321 |                </TMPL_LOOP>
 322 |             </ul>
 323 |         </li>
 324 |       </TMPL_LOOP>
 325 |    </ul>
 326 | 
 327 | To fill in this template use the following code:
 328 | 
 329 | =begin Perl
 330 | 
 331 |   $tmpl->param(
 332 |       employees => [
 333 |          { name => "John",
 334 |            childs => [ { name => "Peter" }, { name => "James" }] },
 335 |          { name => "Mary",
 336 |            childs => [ { name => "Anne" } ] },
 337 |       ]
 338 |   );
 339 | 
 340 | =end Perl
 341 | 
 342 | Conditional structures are easy as well. Conditional generation is
 343 | obtained with C<TMPL_IF> that checks if the variable whose name is
 344 | used in the tag is true or false. Also, the name of a loop can be used
 345 | in a C<TMPL_IF>, that will hold a true value if the array is not empty
 346 | (if the loop needs to be unroll).
 347 | 
 348 | The above example of employees' children can be rewritten to output
 349 | correctly employees who doesn't have a child:
 350 | 
 351 |    <ul>
 352 |      <TMPL_LOOP NAME=employees>
 353 |        <TMPL_IF NAME=childs>
 354 |          <li><TMPL_VAR NAME=name> children:
 355 |            <ul>
 356 |              <TMPL_LOOP NAME=childs>
 357 |                <li><TMPL_VAR NAME=name></li>
 358 |              </TMPL_LOOP>
 359 |            </ul>
 360 |          </li>
 361 |        <TMPL_ELSE>
 362 |          <li><TMPL_VAR NAME=name> does not have any child.</li>
 363 |        </TMPL_IF>
 364 |      </TMPL_LOOP>
 365 |    </ul>
 366 | 
 367 | The C<TMPL_ELSE> command can be omitted. C<TMPL_UNLESS> and
 368 | C<TMPL_ELSIF> can also be used, just like standard PerlN<< Note
 369 | however that C<TMPL_ELSIF> is currently not supported on
 370 | C<HTML::Template>. >>.
 371 | 
 372 | Templates can be included from other templates (up to a recursive
 373 | level of 10 includes). This is achieved using the C<TMPL_INCLUDE> tag:
 374 | 
 375 |      <TMPL_INCLUDE NAME="filename.tmpl"/>
 376 | 
 377 | If the file name starts with a slash, then it is considered an
 378 | absolute path. If not, the template file will be searched locally. The
 379 | C<new> constructor for the C<HTML::Template::Pro> object can receive
 380 | an optional argument to set an array of possible paths where templates
 381 | can lie. If a template file is not found in the current working
 382 | directory, these paths will be searched in order:
 383 | 
 384 | =begin Perl
 385 | 
 386 |   my $tmpl = HTML::Template::Pro->new(
 387 |                filename => 'file.tmpl',
 388 |                path => [ '/my/templates', '/some/other/templates' ]
 389 |              );
 390 | 
 391 | =end Perl
 392 | 
 393 | Finally, C<HTML::Template::Pro> supports simple expressions to be
 394 | used. They can be a security vulnerability. If you think you need
 395 | them, probably you want to give a look into C<Template::Toolkit>.
 396 | 
 397 | =head2 *Filters
 398 | 
 399 | C<HTML::Template::Pro> supports a very simple filtering
 400 | mechanism. When interpolating a template your variable can hold very
 401 | different kind of data, ranging from a simple string, to an URL, an
 402 | HTML block or even Java Script code. The way this data will be
 403 | interpolated will change, and probably you will need to escape some
 404 | special characters. This can be accomplished using the C<TMPL_VAR>
 405 | tag, and adding a C<ESCAPE> option:
 406 | 
 407 |   <input name="param" type="text"
 408 |          value="<TMPL_VAR ESCAPE=HTML NAME="param">"/>
 409 | 
 410 | This will ensure that all HTML characters will be properly
 411 | encoded. The C<ESCAPE> option accept the following values: C<NONE> to
 412 | disable escaping, C<URL> to encode non-standard URL characters (spaces
 413 | replaced by C<+>, C</> replaced by C<%2F>, etc), C<HTML> to encode
 414 | HTML special characters (C<< < >>, C<< > >> and C<< & >>), and C<JS>
 415 | to encode JavaScript. for further details read
 416 | C<HTML::Template::SYNTAX>.
 417 | 
 418 | =head1 Template::Toolkit
 419 | 
 420 | X<Module, Template::Toolkit>X<Template::Toolkit>
 421 | 
 422 | =begin CPANinfo
 423 | 
 424 | B<Version:> 2.22
 425 | 
 426 | B<CPAN:> L<http://search.cpan.org/dist/Template-Toolkit>
 427 | 
 428 | =end CPANinfo
 429 | 
 430 | C<Template::Toolkit> is a complex full featured and extensible
 431 | templating engine. Other than the documentation that gets installed in
 432 | your system and the documentation available from
 433 | L<http://template-toolkit.org/>, there is a good book from O'ReillyN<<
 434 | Perl Template Toolkit, by Darren Chamberlain, Dave Cross and Andy
 435 | Wardley. O'Reilly 2003. >> where you can find in depth details.
 436 | 
 437 | C<Template::Toolkit> (we will call it C<TT> during this section) is
 438 | mostly used for templating HTML documents, and although our examples
 439 | will be with HTML documents (as C<Template::Toolkit> is useful if you
 440 | want to learn a web framework), you can use it to generate all kind of
 441 | documents.
 442 | 
 443 | When installing, note that the distribution name is C<Template>.
 444 | 
 445 | =head2 *Variable Notation
 446 | 
 447 | The syntax to annotate C<TT> variables and commands is
 448 | configurable. By default they are enclosed in two delimiters: C<[%>
 449 | and C<%]>N<< They can be changed using C<START_TAG> and
 450 | C<END_TAG> attributes when creating the C<TT>
 451 | object. >>. Follows a simple C<TT> template, using only variablesN<<
 452 | Consider that the template file is saved in a file named
 453 | C<letter.tmpl>. >>:
 454 | 
 455 |    <p>Dear [% name %]:</p>
 456 |    
 457 |    <p>I am sorry to inform that you are fired. Your compensation
 458 |    is [% compensation %] euro.</p>
 459 |    
 460 |    <p>Best regards, your boss.</p>
 461 | 
 462 | The first thing to note is that the syntax is very clear. Second,
 463 | there are no dollar signs. This is a design feature of C<TT>, making
 464 | it easier to use by non Perl programmers (for example, Web designers).
 465 | 
 466 | The code needed to interpolate this template for two different
 467 | employees is quite simple: first create a C<Template> object (that can
 468 | be used to process more than one template), then ask this object to
 469 | interpolate a specific template with some variables.
 470 | 
 471 | =begin Perl
 472 | 
 473 |   use Template;
 474 |   my $tmpl = Template->new();
 475 |   
 476 |   my %compensations = ( John => 100, Mary => 300 );
 477 | 
 478 |   for my $employee (keys %compensations) {
 479 |      my $vars = { name         => $employee,
 480 |                   compensation => $compensations{$name}};
 481 |      $tmpl->process('letter.tmpl', $vars);
 482 |   }
 483 | 
 484 | =end Perl
 485 | 
 486 | Note that no output is specified or C<print> is used. This is because
 487 | C<process> prints by default t C<STDOUT>. To create a file for each
 488 | employee is simple as well, just add a third argument to the
 489 | C<process> method, as follows:
 490 | 
 491 |    $tmpl->process('letter.tmpl', $vars, "$name.html");
 492 | 
 493 | There are more than a dozen configuration options for the C<TT>
 494 | parser. Here we will just add that C<TT> can be configured to process
 495 | templates in different encodings.
 496 | 
 497 | If your variables have C<UTF-8> values, then add a C<binmode> option
 498 | at the end of the C<process> directive:
 499 | 
 500 |    $tmpl->process('letter.tmpl', $vars, "$name.html",
 501 |                   binmode => ':utf8');
 502 | 
 503 | In the other hand, if your template files are already in C<UTF-8> and
 504 | include C<UTF-8> characters, you can set the C<encode> option globally
 505 | in the C<TT> constructor:
 506 | 
 507 |    my $tmpl = Template->new( { ENCODING => 'utf8' });
 508 | 
 509 | C<TT> variables can be more complex than just the variable name. For
 510 | example, there is the possibility to get the C<n>G<th> element from a
 511 | list, the value from an hash with a specific key, call a method,
 512 | etc. Some of these will be presented in the next loop and conditional
 513 | examples.
 514 | 
 515 | =head2 *Complex structures
 516 | 
 517 | C<TT> supports a relatively large language, much more than just
 518 | conditional or loop constructs. This language lets the user insert
 519 | files, process sub-templates, wrap templates, use conditionals and
 520 | loops and even throw exceptions. We will focus some of them in this
 521 | section.
 522 | 
 523 | To start with the more natural constructs, C<TT> supports conditionals
 524 | just like Perl itself: C<if>, C<unless>, C<elsif> and
 525 | C<else>. Conditions are just like Perl, just remember that you do not
 526 | prefix variables with the dollar "C<$>" or at "C<@>" signs, and that
 527 | you should use numeric comparison operators always.
 528 | 
 529 |   Dear [% name %]:
 530 |   [% IF salary > 3000 %]
 531 |     <p>You are fired!</p>
 532 |   [% ELSIF salary > 1500 %]
 533 |     <p>Your salary will be raised by 10%.</p>
 534 |   [% ELSE %]
 535 |     <p>Do you still work here? Silly!</p>
 536 |   [% END %]
 537 | 
 538 | Just like in Perl, you can use lists and variables instead of
 539 | conditions. They will be evaluated as a boolean value.
 540 | 
 541 | Loops are supported both as C<while> or C<foreach> constructs. Follows
 542 | an example of using C<while>, to calculate a twelve month mortgage
 543 | table with a 5% flat tax, given a variable C<mortgage> with the
 544 | valueN<< If you try to use a C<while> loop and your code does not
 545 | output anything, probably you have an infinite loop or a loop with
 546 | more than 1000 iterations. >>:
 547 | 
 548 |   <p>Your mortgage payment in 12 months:</p>
 549 |   <ul>
 550 |   [% i = 0 %]
 551 |   [% WHILE i < 12 %]
 552 |     [% i=i+1 %]
 553 |     <li>[% i %] month: [% (mortgage / 12) * 1.05 %] euro</li>
 554 |   [% END %]
 555 |   </ul>
 556 | 
 557 | This example also presents the ability to compute values directly in
 558 | the template. All place holders with an assignment will compute the
 559 | supplied expression, and store the result in the variable. No value
 560 | will be interpolated in the template.
 561 | 
 562 | The C<foreach> construct is used to cycle through lists. Just like the
 563 | C<Perl> counterpart, a local variable is used, and it will iterate
 564 | over all the values in the list.
 565 | 
 566 |    <ul>
 567 |       [% FOREACH employee IN employees %]
 568 |          [% IF employee.children %]
 569 |          <li>[% employee.name %] children:
 570 |            <ul>
 571 |              [% FOREACH child IN employee.children %]
 572 |                <li>[% child %]</li>
 573 |              [% END %]
 574 |            </ul>
 575 |          </li>
 576 |          [% ELSE %]
 577 |          <li>[% employee.name %] does not have any child.</li>
 578 |          [% END %]
 579 |       [% END %]
 580 |    </ul>
 581 | 
 582 | Fill in this template with the following Perl code. Note how natural
 583 | it is to describe in the template how to traverse the data structure.
 584 | 
 585 | =begin Perl
 586 | 
 587 |   use Template;
 588 |   
 589 |   my $tmpl = Template->new;
 590 |   my $data = {
 591 |     employees => [
 592 |       { name => "Mary",
 593 |         children => [ "Ann" ] },
 594 |       { name => "John",
 595 |         children => [ "Paul", "Sebastien" ] },
 596 |     ],
 597 |   };
 598 |   
 599 |   $tmpl->process("emp.tmpl", $data);
 600 | 
 601 | =end Perl
 602 | 
 603 | C<TT> can include sub-templates or other files. Including other files
 604 | is easy, just use the C<insert> command. Note that the inserted file
 605 | will not be processed as a template.
 606 | 
 607 |    [% INSERT copyright.html %]
 608 | 
 609 | If you want to include a sub-template, you need to use C<process> or
 610 | C<include>. They are very similar. The main difference is that
 611 | C<include> consider all code in the sub-template to be local. All
 612 | changed variables will remain private to that sub-template. In the
 613 | other hand, C<process> will make all sub-template changes available in
 614 | the calling template.
 615 | 
 616 | When using any of these commands you can pass some extra variables
 617 | (separated by commas). These are two simple examples:
 618 | 
 619 |    [% PROCESS header %]
 620 |    [% PROCESS footer year=2011]
 621 | 
 622 | There is another including mechanism named C<wrapper>, that instead of
 623 | including an external template on a specific point of the current
 624 | template, wraps the current template in the external template. This
 625 | gets easier to understand with an example. You can have a web page
 626 | design (typical header and footer) in a document, named C<layout>,
 627 | like this:
 628 | 
 629 |    <html>
 630 |      <head><title>My brand new site</title></head>
 631 |      <body>
 632 |        [% content %]
 633 |        <div id="copyright">Copyright by me</div>
 634 |      </body>
 635 |    </html>
 636 | 
 637 | Now, instead of rendering this template directly with your Perl code,
 638 | interpolating C<content> with your web page, you can render a more
 639 | specific template that wraps this header and footer:
 640 | 
 641 |   [% WRAPPER layout %]
 642 |      <h1>About this site</h1>
 643 |      <p>Blah, blah [% somevar %] blah blh</p>
 644 |   [% END %]
 645 | 
 646 | This template can be rendered directly as a standard template, and
 647 | C<TT> will automatically insert the result of processing this template
 648 | in the C<layout> template.
 649 | 
 650 | =head2 *Filters
 651 | 
 652 | C<TT> supports a powerful filtering mechanism. Some filters are
 653 | available out of the box, but it lets the user define their own. In
 654 | this section we will look into some of the predefined filters.
 655 | 
 656 | Filters are functions that take your variables values or sections of
 657 | your document and process them in some way. A simple example is the
 658 | C<collapse> filter, that will remove all extra spaces and
 659 | newlines. Filters can be applied in a block with the C<filter>
 660 | keyword:
 661 | 
 662 |   [% FILTER collapse %]
 663 |      This     is   some
 664 |        spaced      text.
 665 |   [% END %]
 666 | 
 667 | C<TT> will ensure that the output rendersN<< Note that C<TT> is tailored
 668 | for HTML output. >> exactly the same, but does not have extra spaces
 669 | or new lines:
 670 | 
 671 |   This is some spaced text.
 672 | 
 673 | Filters can also be applied to the result of a specific C<TT>
 674 | command. For instance, we can uppercase the name of a person stored in
 675 | the C<name> variable with:
 676 | 
 677 |   [% name FILTER uppercase %]
 678 | 
 679 | C<TT> makes in-line filtering, just like the shown, easier, trying to
 680 | mimic the behavior of shell filters. For instance, quoting HTML
 681 | special characters from a variable C<code> is as simple as:
 682 | 
 683 |   [% code | html %]
 684 | 
 685 | This will ensure that all special HTML characters used in the C<code>
 686 | variable are correctly protected. Other useful filter for web
 687 | applications is named C<uri>. It filters the text protecting special
 688 | characters accordingly with RFC 2396, that is, replacing them by a
 689 | percent sign followed by the hex code of the character being replaced
 690 | (for example, the usual replacement of space by C<%20>). However, note
 691 | that you should not apply this filter to the full URL. For that use
 692 | the C<url> filter:
 693 | 
 694 |   <a href="[% page_url | url %]">Check this page.</a>
 695 | 
 696 | There are a lot of other filters, ranging from simple text
 697 | transformation, trimming strings, truncating string, to full Perl code
 698 | evaluation. Just be caution on where you use them. A complete
 699 | reference is available at
 700 | L<http://template-toolkit.org/docs/manual/Filters.html>
 701 | 
 702 | =head2 *Virtual Methods
 703 | 
 704 | As you might have noticed in the previous sections, C<TT> is a complex
 705 | language by itself. This language supports some methods to be called
 706 | into variables. As they are not methods directly available on your
 707 | code, they are named I<Virtual Methods>. C<TT> includes a set of
 708 | predefined ones, but the user can extend this language with his own
 709 | methods. This section will present a few of the predefined virtual
 710 | methods, so you can start understanding how they work, and later
 711 | search for reference on other documents.
 712 | 
 713 | These methods are called just as most OO languages, put a dot after
 714 | the variable, and the method name. The available methods depend on the
 715 | variable type (scalar, hash or array). A full list can be consulted at
 716 | L<http://template-toolkit.org/docs/manual/VMethods.html>. Some of the
 717 | more relevant method are presented bellow.
 718 | 
 719 | =over
 720 | 
 721 | =item B<Scalar methods>
 722 | 
 723 | The most useful methods are C<defined> to check if the value for a
 724 | specific variable is set:
 725 | 
 726 |    [% IF var.defined %]  ...  [% END %]
 727 | 
 728 | The C<length> returns the length of a string. The C<repeat> method
 729 | repeats a string I<n> times, like the following code that renders
 730 | I<hohoho>:
 731 | 
 732 |    [% name = 'ho' %] [% name.repeat(3) %]
 733 | 
 734 | There are methods to C<replace>, C<remove> a regular expression
 735 | (substitute it by nothing), or even C<match> and then access each of
 736 | the match capture zones, C<split> to divide a string by some
 737 | separator, etc.
 738 | 
 739 | =item B<Array or lists methods>
 740 | 
 741 | For lists, you can use C<first> or C<last> to access the first and
 742 | last elements from the array. The C<size> returns the number of
 743 | elements, while C<max> returns the index for the last element (size
 744 | minus 1).
 745 | 
 746 | For lists, the C<defined> method receives the element number to be
 747 | tested:
 748 | 
 749 |    [% list.defined(4) ? "Yes, defined" : "No, not defined" %]
 750 | 
 751 | Other Perl-like methods are also available, like C<reverse>, C<grep>
 752 | (receives the regular expression as first parameter), C<join>
 753 | (receives the join string as first parameter), C<sort> for string
 754 | sort, and C<nsort> for numeric comparisons, C<push>, C<unshift>,
 755 | C<shift>, C<pop>, C<slice>, C<splice>, etc.
 756 | 
 757 | One interesting feature very useful is that C<sort> or C<nsort> can
 758 | receive a list of strings that are used as keys for hash
 759 | references. So, if you have a list of hash references, and each hash
 760 | reference has a key named C<id>, you can sort those elements with:
 761 | 
 762 |    [% FOREACH book IN books.sort('id') %] ... [% END %]
 763 | 
 764 | If you use more than one key, they will be used for second level
 765 | sorting (if the values are equal for the first key).
 766 | 
 767 | =item B<Hash methods>
 768 | 
 769 | For hash values you can issue C<keys> to get the keys list, or
 770 | C<values> for the values list. The C<items> virtual method returns a
 771 | list where each position is a pair (a small list with the key and the
 772 | value). Similar is the C<pairs> method:
 773 | 
 774 |   [% FOREACH book IN books.pairs %]
 775 |     <td> [% book.key %] </td><td> [% book.value %] </td>
 776 |   [% END %]
 777 | 
 778 | C<sort> and C<nsort> can be used to gather a list of the keys sorted
 779 | alphabetically or numerically. Note that you do not need to use the
 780 | C<keys> method:
 781 | 
 782 |   [% FOREACH bookId IN books.nsort %] ... [% END %]
 783 | 
 784 | The C<defined> and C<exists> methods do exactly what you are
 785 | expecting. Pass them a key, and they will return a true value if that
 786 | key is defined or exists in the hash. It is also possible to define
 787 | items form the hash, using the C<delete> method. Pass it any number of
 788 | keys you like. They will be removed from the hash (together with their
 789 | respective values).
 790 | 
 791 | You can access hash values using the key name as if it were a virtual
 792 | method C<< [% hash.key1 %] >> or use the C<item> method, with C<< [%
 793 | hash.item('key1') %] >>.
 794 | 
 795 | =back
 796 | 
 797 | This was a quick and condensed look into the existing virtual
 798 | methods. Give a look into the documentation for a in depth look with
 799 | examples. You can also define your own virtual methods (check
 800 | C<Template::Stash> for documentation).
 801 | 
 802 | =head1 Text::Xslate
 803 | 
 804 | X<Module, Text::Xslate>X<Text::Xslate>
 805 | 
 806 | =begin CPANinfo
 807 | 
 808 | B<Version:> 1.3000
 809 | 
 810 | B<CPAN:> L<http://search.cpan.org/dist/Text-Xslate>
 811 | 
 812 | =end CPANinfo
 813 | 
 814 | C<Text::Xslate> is inspired in some existing template engines, like
 815 | C<Template::Toolkit>, C<Text::MicroTemplate>, C<HTML::Template> and
 816 | others. Although inspired by these modules, the author claims that
 817 | C<Text::Xslate> has a completely different philosophy: the template
 818 | logic, that is, the template code should not be able to access/change
 819 | data outside the template without permission.
 820 | 
 821 | The notation described in this section is the I<Kolon> syntax, that
 822 | uses as delimiters C<< <: >> and C<< :> >>. There is a I<Metakolon>
 823 | syntax, that uses C<< [% >> and C<< %] >>, and a I<TTerse> syntax,
 824 | that implements a subset of C<Template::Toolkit> syntax.
 825 | 
 826 | =head2 *Variable Notation
 827 | 
 828 | Place holders are enclosed in C<< <: >> and C<< :> >> as already
 829 | mentioned. Variables are written as in Perl, preceded by a dollar
 830 | sign:
 831 | 
 832 |    <: $name :>
 833 | 
 834 | After the variable name you can add a method name (if the variable is
 835 | an object), a key value (if the variable is a hash reference) or an
 836 | array position (if the variable is an array reference):
 837 | 
 838 |    <: $array.2 :>
 839 |    <: $hash.key :>
 840 |    <: $obj.method :>
 841 | 
 842 | If you prefer the array syntax, you can use it as well:
 843 | 
 844 |    <: $array[2] :>
 845 |    <: $hash["key"] :>
 846 |    <: $obj["method"] :>
 847 | 
 848 | Using the same template that has being used in the previous sections,
 849 | saved as C<letter.tx>:
 850 | 
 851 |    <p>Dear <: $name :>:</p>
 852 |    
 853 |    <p>I am sorry to inform that you are fired. Your compensation
 854 |    is <: $compensation[$name] :> euro.</p>
 855 |    
 856 |    <p>Best regards, your boss.</p>
 857 | 
 858 | To fill-in this template we can use the following Perl code, that will
 859 | generate a different HTML file per employee:
 860 | 
 861 | =begin Perl
 862 | 
 863 |   use Text::Xslate;
 864 |   my $tx = Text::Xslate->new();
 865 |   my %compensation = (John => 100, Mary => 300);
 866 | 
 867 |   for my $name (keys %compensation) {
 868 |       open OUT, ">", "$name.html" or die;
 869 |       print OUT $tx->render('letter.tx',
 870 |                             { name         => $name,
 871 |                               compensation => \%compensation});
 872 |       close OUT;
 873 |   }
 874 | 
 875 | =end Perl
 876 | 
 877 | =head2 *Complex structures
 878 | 
 879 | C<Text::Xslate> has the concept of code line, that is, a line in the
 880 | template that is completely interpreted as a template command. In the
 881 | I<Kolon> syntax they start with a colon (C<:>).
 882 | 
 883 | For example, a conditional is written mostly like you would write in Perl:
 884 | 
 885 |    : if ($employee.children) {
 886 |        <: $employee.name :> has some children!
 887 |    : }
 888 |    : else {
 889 |        <: $employee.name :> does not have any children!
 890 |    : }
 891 | 
 892 | There are C<for> loops as well, but they have a syntax slightly
 893 | different from Perl:
 894 | 
 895 |    : for $employees -> $employee {
 896 |    :   if ($employee.children) {
 897 |        <: $employee.name :> has some children!
 898 |    :   } else {
 899 |        <: $employee.name :> does not have any children!
 900 |    :   }
 901 |    : }
 902 | 
 903 | Interpolate this template with the following Perl code:
 904 | 
 905 | =begin Perl
 906 | 
 907 |   use Text::Xslate;
 908 |   my $tx = Text::Xslate->new();
 909 | 
 910 |   print $tx->render('letter.tx', {
 911 |          employees => [
 912 |              { name => "Mary", children => ["Anne"] },
 913 |              { name => "John" },
 914 |          ] } );
 915 | 
 916 | =end Perl
 917 | 
 918 | C<Text::Xslate> also supports C<while> loops and C<given/when>
 919 | conditional structures. Be sure to read the documentation with
 920 | caution, as the syntax is tricky, and not exactly like Perl.
 921 | 
 922 | There are two distinct ways to include sub-templates. The first is
 923 | using the C<include> command, followed by the name of the sub-template
 924 | to process. Optionally a hash of further variables to be defined in
 925 | the sub-template can be supplied:
 926 | 
 927 |    : include "header.tx"
 928 |    : include "footer.tx" { date => 'Christmas', copyright => 'me' }
 929 | 
 930 | The other approach is to use template cascading. This feature can be
 931 | seen as some kind of inheritance between templates, together with the
 932 | possibility to use rolesN<< For a better description on roles read the
 933 | chapter A<chap:OO> or the documentation of any new Perl
 934 | object-oriented framework. >>.
 935 | 
 936 | It all starts with the definition of blocks using the C<block>
 937 | keyword. Think of blocks as place holders, where some text (or
 938 | anything else, in fact) will be placed. Each block has a name and
 939 | optionally a default content.
 940 | 
 941 | For example, for a web site we can define the basic layout in a
 942 | C<base.tx> document, as follows:
 943 | 
 944 |   : block header -> {
 945 |       Welcome to my Website!
 946 |   : }
 947 |   : block contents -> { }
 948 |   : block footer -> {
 949 |       Copyright by me!
 950 |   : }
 951 | 
 952 | This code defines three zones, and specifies default content for the
 953 | header and footer blocks. Note that the content should be placed in
 954 | different lines from the commands. If you render this template the
 955 | result will be the two lines defined as default content.
 956 | 
 957 | We can extend (C<cascade>) this template into another, for example,
 958 | C<about.tx> that sets the I<contents> block text:
 959 | 
 960 |   : cascade "base.tx"
 961 |   : around contents -> {
 962 |       My name is Homer Simpson and I like beer.
 963 |   : }
 964 | 
 965 | The C<cascade> command is telling the template engine this template is
 966 | a I<child> from C<base.tx>, and C<around> is redefining the
 967 | I<contents> block with some other text. Also relevant is that there is
 968 | a C<super> method to call the previous defined block. For instance, to
 969 | surround the I<header> block with a new C<div> element we can write
 970 | the following template:
 971 | 
 972 |   : cascade "base.tx"
 973 |   : around header -> {
 974 |      <div id='header'>
 975 |         :super
 976 |      </div>
 977 |   : }
 978 | 
 979 | The line with the C<super> command will cascade into C<base.tx> and
 980 | use its default value.
 981 | 
 982 | Similar with C<around> there are the C<before> and C<after> commands
 983 | that, instead of redefining the full block, define content to be
 984 | placed I<before> or I<after> the block. As an example, the following
 985 | template cascades on C<base.tx>, adding an year before the copyright
 986 | notice, in the I<footer> block.
 987 | 
 988 |   : cascade "base.tx"
 989 |   : before footer -> {
 990 |         <: $year :>
 991 |   : }
 992 | 
 993 | 
 994 | Always remember that from your Perl code you must render the more
 995 | specific template, the one that cascades into other templates.
 996 | 
 997 | Templates cascading is one of the main features from
 998 | C<Text::Xslate>. It still supports roles and macros, but these topics
 999 | will not be covered in this book.
1000 | 
1001 | =head2 *Filters
1002 | 
1003 | C<Text::Xslate> has some built-in filters defined, but the definition
1004 | of user filters is also simple (unlike, for instance,
1005 | C<Template::Toolkit>, that forces to create a new package with the
1006 | filter definition).
1007 | 
1008 | The two main filters available are C<html> and C<dump>:
1009 | 
1010 |     : $var | html       # html-escape the variable content
1011 |     : $var | dump       # dump the variable with Data::Dumper
1012 | 
1013 | These filters are implemented as functions. This makes it possible to
1014 | use them as a standard function call:
1015 | 
1016 |     : html($var)
1017 | 
1018 | For an example on defining your own filters please refer to
1019 | C<Text::Xslate> documentation.
1020 | 
1021 | =head2 *Virtual Methods
1022 | 
1023 | The C<Text::Xslate> documentation doesn't refer to the methods as
1024 | virtual. This section is named this way for homogeneity with the
1025 | previous module. Also, there aren't really much methods defined as it
1026 | supports a big subset of the Perl language.
1027 | 
1028 | Nevertheless, there are three methods that are crucial when cycling
1029 | through hashes: C<keys>, C<values> and C<kv>. The first two are quite
1030 | straightforward, make it possible to cycle through keys of values:
1031 | 
1032 |   : for $data.keys() -> $key {
1033 |       * <: $key :> - <: $data[$key] :>
1034 |   : }
1035 | 
1036 | The C<kv> variant is similar to the C<each> command from Perl. In each
1037 | iteration returns a pair, with a key and a value:
1038 | 
1039 |   : for $data.kv() -> $pair {
1040 |       * <: $pair.key :> - <: $pair.value :>
1041 |   : }
1042 | 
1043 | For arrays and hashes there is a C<size> method that returns their
1044 | number of elements. For arrays there are the typical C<reverse>,
1045 | C<join>, C<sort> and C<map>, together with a C<reduce> method.
1046 | 
1047 | =begin SeeAlso
1048 | 
1049 | Note that this chapter intends to be a gentle introduction to the
1050 | described template systems. Each of them has much more that can be
1051 | achieved using built-in features, or extending it (especially
1052 | C<Template::Toolkit> and C<Text::Xslate>). Use the information in this
1053 | chapter as a start point but refer to their documentation for in-depth
1054 | information.
1055 | 
1056 | C<Mason> X<Mason> X<Module, Mason> is a web framework that
1057 | incorporates its own template engine. Some applications support
1058 | C<Mason> syntax for templating via plug-ins.
1059 | 
1060 | If your C<HTML::Template> templates are slow check X<Module,
1061 | HTML::Template::Compiled>X<HTML::Template::Compiled>
1062 | C<HTML::Template::Compiled>, that compiles a template into a Perl
1063 | program making it faster.
1064 | 
1065 | X<Module, Template::Simple> X<Template::Simple> C<Template::Simple> is
1066 | a simple and fast template engine. It is written entirely in Perl and
1067 | has a modern interface, unlink C<Text::Template> or even
1068 | C<HTML::Template>.
1069 | 
1070 | X<Module, Text::Template::Simple> X<Text::Template::Simple>
1071 | C<Text::Template::Simple> uses the same philosophy from
1072 | C<Text::Simple> making Perl itself the templating language. Its main
1073 | difference from C<Text::Template> is that the mark-up language has
1074 | some extra sugar to configure whether they are place-holders or simple
1075 | code blocks with no return text.
1076 | 
1077 | =end SeeAlso
1078 | 
1079 | =cut
1080 | 
1081 | ## Local Variables:
1082 | ##  ispell-local-dictionary: "english"
1083 | ##  mode: flyspell
1084 | ## End:
1085 | 


--------------------------------------------------------------------------------
/CPAN/chapters/30-web.pod:
--------------------------------------------------------------------------------
  1 | =head0 Web Frameworks
  2 | 
  3 | Web development in Perl started with the X<CGI> X<Module, CGI> C<CGI>
  4 | module. It includes mechanisms to generate HTML from Perl statements,
  5 | and to access CGI parameters, sessions and cookies. Although it is a
  6 | quite powerful method it is showing signs of age, and there are a wide
  7 | variety of other tools that make Web development easier, more
  8 | structured and faster. These are the main reasons why the C<CGI>
  9 | module will not be the focus of this chapter. Yet another reason is the
 10 | quantity of books and tutorials that are available that teach how to
 11 | develop with C<CGI>.
 12 | 
 13 | There are many Web Frameworks in Perl, and with the advent of
 14 | C<PSGI> and C<Plack> X<PSGI> X<Module, PSGI> X<Plack> X<Module, Plack>
 15 | the interface between web servers and Perl has become more user friendly,
 16 | which has in turn lead to even more frameworks.
 17 | 
 18 | This book does not intend to be a full reference to CPAN modules, or
 19 | to be a in-depth book on extremely technical aspects. These reasons made us
 20 | decide not to discuss C<PSGI> or C<Plack> directly, but present
 21 | frameworks that use them, like C<Dancer> or C<Mojolicious>. With this
 22 | same idea in mind, we will not cover deployment, as there are too many
 23 | options (from Apache C<mod_perl>, FastCGI running under Apache or
 24 | nginx, using Starman, and others). Instead, we describe how to get
 25 | code running for in development. We recommend you then read the
 26 | documentation for the specific deployment method you plan to use.
 27 | 
 28 | This section will B<introduce> Web programming using four different
 29 | web frameworks:
 30 | 
 31 | =over
 32 | 
 33 | =item B<Catalyst>
 34 | 
 35 | The X<Module, Catalyst> X<Catalyst> C<Catalyst> web framework is
 36 | probably the most well known nowadays. It is a complete and efficient
 37 | web framework. Its main drawback if the complexity of projects for new
 38 | developers. There are some book about it, which explain why our
 39 | section on it is quite reduced.
 40 | 
 41 | =item B<Mason>
 42 | 
 43 | The success of PHP lead to some similar approaches for other
 44 | languages. There are different tries to get a module with a similar
 45 | philosophy, but C<Mason> X<Module, Mason> X<Mason> is probably the
 46 | only one that was widely used. Not because of following a PHP-like
 47 | approach, but for taking it a step forward.
 48 | 
 49 | =item B<Mojoliciou>
 50 | 
 51 | C<Mojolicious> was developed after C<Catalyst>, by the same main
 52 | author. The idea was to simplify it, making it easier to use and
 53 | lighter. 
 54 | 
 55 | =item B<Dancer>
 56 | 
 57 | Heavily inspired by Ruby's Sinatra, C<Dancer> has gained adherents over
 58 | recent months. The fact that one of the authors of this book is a C<Dancer>
 59 | developer was a good enough reason to include it here.
 60 | 
 61 | =back
 62 | 
 63 | =head1 Catalyst
 64 | 
 65 | X<Module, Catalyst> X<Catalyst>
 66 | 
 67 | =head1 Mason
 68 | 
 69 | X<Module, Mason> X<Mason>
 70 | 
 71 | =head1 Mojolicious
 72 | 
 73 | X<Module, Mojolicious> X<Mojolicious>
 74 | 
 75 | =head1 Dancer
 76 | 
 77 | X<Module, Dancer> X<Dancer> C<Dancer> has a nice command that eases
 78 | the task of creating the required files to run a C<Dancer> web
 79 | site. In fact, the C<dancer> application creates not just the required files,
 80 | but also a typical Perl module structure and a simple
 81 | running web site. Use the following command:
 82 | 
 83 |     dancer -a MyApp
 84 | 
 85 | A folder named C<MyApp> will be created, with a number of files. In the
 86 | next section we will analyze this folder structure.
 87 | 
 88 | =head2 *Default Dancer Application Structure
 89 | 
 90 | The structure scaffolded by C<Dancer> is presented bellow, together
 91 | with some comments on their meaning. Note that this structure already
 92 | includes code that already runs and presents a simple web page with
 93 | some C<Dancer> configuration variables. To make this page nicer,
 94 | C<Dancer> authors added some style sheets and images. This decision
 95 | explains why the C<dancer> script creates this kind of files.
 96 | 
 97 | Also, C<Dancer> applications are full Perl modules. This second
 98 | decision explains why there is a C<Makefile.PL> (where you should add
 99 | all your application dependencies), a C<MANIFEST> and C<MANIFEST.SKIP>
100 | files, that list the files that should and should not be included in
101 | the Perl module, a C<lib> folder with a module (with the same name of
102 | your application) and a C<t> folder with some basic tests for your
103 | application.
104 | 
105 | =begin figure Structure of a C<Dancer> scaffolded application.
106 | 
107 | =for latex
108 | 
109 | \begin{minipage}{\textwidth}
110 | \renewcommand*\DTstylecomment{\it}
111 | \dirtree{%
112 |  .1 MyApp/. 
113 |  .2 Makefile.PL\DTcomment{Dancer applications are Perl Modules!}. 
114 |  .2 MANIFEST. 
115 |  .2 MANIFEST.SKIP. 
116 |  .2 config.yml\DTcomment{Generic application configuration}. 
117 |  .2 environments/. 
118 |  .3 development.yml\DTcomment{Specific development configuration}. 
119 |  .3 production.yml\DTcomment{Specific production configuration}. 
120 |  .2 bin/. 
121 |  .3 app.pl\DTcomment{Stand-alone PSGI development server}. 
122 |  .2 views/. 
123 |  .3 index.tt\DTcomment{Template used on the index route}. 
124 |  .3 layouts/. 
125 |  .4 main.tt\DTcomment{Global layout template}. 
126 |  .2 lib/. 
127 |  .3 MyApp.pm\DTcomment{Where you route code lays}. 
128 |  .2 public/. 
129 |  .3 500.html\DTcomment{Page to show on 500 error}. 
130 |  .3 404.html\DTcomment{Page to show on 404 error}. 
131 |  .3 dispatch.cgi\DTcomment{Dispatcher to use with CGI}. 
132 |  .3 dispatch.fcgi\DTcomment{Dispatcher to use with FastCGI}. 
133 |  .3 javascripts/. 
134 |  .4 jquery.js\DTcomment{Yes, Dancer ships with jquery}.
135 |  .3 css/. 
136 |  .4 \ldots\DTcomment{A couple of style sheets}.
137 |  .3 images/. 
138 |  .4 \ldots\DTcomment{And a couple of image files}. 
139 |  .2 t/. 
140 |  .3 001\_base.t\DTcomment{Tests if your application loads}. 
141 |  .3 002\_index\_route.t\DTcomment{Tests if your application has a root route handler}. 
142 | }
143 | \end{minipage}
144 | 
145 | =end
146 | 
147 | =end figure
148 | 
149 | We will dissect some of these files in the next paragraphs.
150 | 
151 | =cut
152 | 
153 | ## Local Variables:
154 | ##  ispell-local-dictionary: "english"
155 | ##  mode: flyspell
156 | ## End:
157 | 


--------------------------------------------------------------------------------
/CPAN/chapters/40-database.pod:
--------------------------------------------------------------------------------
 1 | 
 2 | =head0 Database Interfaces
 3 | 
 4 | =head1 DBI
 5 | 
 6 | =head1 DBIx::Class
 7 | 
 8 | 
 9 | =cut
10 | 
11 | ## Local Variables:
12 | ##  ispell-local-dictionary: "english"
13 | ##  mode: flyspell
14 | ## End:
15 | 


--------------------------------------------------------------------------------
/CPAN/chapters/50-xml.pod:
--------------------------------------------------------------------------------
 1 | 
 2 | =head0 XML Processing
 3 | 
 4 | =head1 XML::DOM
 5 | 
 6 | =head1 XML::DT
 7 | 
 8 | =head1 XML::LibXML
 9 | 
10 | =head1 XML::Parser
11 | 
12 | =head1 XML::Rules
13 | 
14 | =head1 XML::Simple
15 | 
16 | =head1 XML::Twig
17 | 
18 | =head1 XML::Writer::Simple
19 | 
20 | =head1 XML::XPath
21 | 
22 | =cut
23 | 
24 | ## Local Variables:
25 | ##  ispell-local-dictionary: "english"
26 | ##  mode: flyspell
27 | ## End:
28 | 


--------------------------------------------------------------------------------
/CPAN/chapters/60-serialization.pod:
--------------------------------------------------------------------------------
 1 | 
 2 | =head0 Data Serialization
 3 | 
 4 | =head1 Dumper
 5 | 
 6 | ...
 7 | 
 8 | =head1 YAML
 9 | 
10 | X<YAML::XS>
11 | 
12 | =head1 JSON
13 | 
14 | X<JSON::XS>
15 | 
16 | =head1 Storable
17 | 
18 | ??
19 | 
20 | =head1 FreezeThaw
21 | 
22 | ??
23 | 
24 | =cut
25 | 
26 | ## Local Variables:
27 | ##  ispell-local-dictionary: "english"
28 | ##  mode: flyspell
29 | ## End:
30 | 


--------------------------------------------------------------------------------
/CPAN/chapters/70-testing.pod:
--------------------------------------------------------------------------------
  1 | 
  2 | =head0 Testing
  3 | 
  4 | X<Testing> Testing is a indispensable stage in every modern software
  5 | development cycle. Tests can help asserting that software is
  6 | working properly, and also to make sure that software behavior is
  7 | kept when major re-factors to the code are performed.
  8 | 
  9 | In this chapter we introduce some important modules that can be used
 10 | to create and maintain a suite of heterogeneous tests. These
 11 | modules can be used to write tests for most of the common situations,
 12 | but there are a lot more. Search CPAN for a module to help test your
 13 | code before starting to write your own, most probably someone has already
 14 | been in the same situation.
 15 | 
 16 | Most of the module starter tools will create a directory for tests, with
 17 | some simple tests, and also a way to run your test suite. It's up to the
 18 | developers to write and maintain further test files to cover as much as
 19 | possible of the code. We hope that the modules described in the following
 20 | sections help to perform this task.
 21 | 
 22 | Except some comparisons and simple situations, most of the test cases fall
 23 | in this philosophy: execute some snippet of code, and compare the result
 24 | with the correct answer. The way you provide this snippet of code and
 25 | capture the result may vary, and that is one of the main reasons to have
 26 | such a great panoply of modules to implement tests. That, and the tools
 27 | that provide shortcuts to more common tests.
 28 | 
 29 | =head1 Test::Simple
 30 | 
 31 | X<Module, Test::Simple>X<Test::Simple>
 32 | 
 33 | =begin CPANinfo
 34 | 
 35 | B<Version:> 0.98
 36 | 
 37 | B<CPAN:> L<http://search.cpan.org/dist/Test-Simple>
 38 | 
 39 | =end CPANinfo
 40 | 
 41 | This module provides a simple and intuitive framework to start creating
 42 | tests. This can be the place to start. The simple test you can have is
 43 | something in the lines of:
 44 | 
 45 | =begin Perl
 46 | 
 47 |   use Test::Simple tests => 1;
 48 |   ok('true' eq 'true', 'the test of truth');
 49 | 
 50 | =end Perl
 51 | 
 52 | The first line loads the C<Test::Simple> X<Test::Simple>
 53 | X<Module, Test::Simple> module, and defines how many tests will run.
 54 | The number of tests to run is a mandatory requirement
 55 | of this module. The second line of this small snippet implements a test.
 56 | This test uses the C<ok> function that has two arguments: first is
 57 | the expression validating the requirement, in this simple case a simple
 58 | string comparison is performed, and a second optional argument which
 59 | is the name of the test. Variables can be used has in any other common
 60 | expression, for example:
 61 | 
 62 | =begin Perl
 63 | 
 64 |   use Test::Simple tests => 2;
 65 | 
 66 |   my $age = 24;
 67 |   my $day = 35;
 68 | 
 69 |   ok($age > 0, 'valid age');
 70 |   ok($day <= 31, 'valid day');
 71 | 
 72 | =end Perl
 73 | 
 74 | In this later case variables and binary operators are being used in the
 75 | expression passed to the C<ok> function. Bottom line, if the result of
 76 | evaluating the expression given as argument is true the result of the
 77 | test is ok, otherwise the test is not ok. Running the above script you
 78 | would get:
 79 | 
 80 |   1..2
 81 |   ok 1 - valid age
 82 |   not ok 2 - valid day
 83 |   #   Failed test 'valid day'
 84 |   #   at t.pl line 7.
 85 |   # Looks like you failed 1 test of 2.
 86 | 
 87 | Remember that the second argument passed to the C<ok> function is simply
 88 | the name of the test for easy reference, and is optional.
 89 | 
 90 | The main goal of this module is to get you started writing tests.
 91 | C<Test::More> X<Test::More> X<Module, Test::More> in the next section is
 92 | the next typical step for building a test suite.
 93 | 
 94 | =head1 Test::More
 95 | 
 96 | X<Module, Test::More>X<Test::More>
 97 | 
 98 | =begin CPANinfo
 99 | 
100 | B<Version:> 0.98
101 | 
102 | B<CPAN:> L<http://search.cpan.org/dist/Test-Simple>
103 | 
104 | =end CPANinfo
105 | 
106 | If it is your first time writing tests you should start by taking a
107 | look at C<Test::Simple> X<Test::Simple> X<Module, Test::Simple>.
108 | After C<Test::Simple> X<Test::Simple> X<Module, Test::Simple> this is the
109 | next place to go. This module is a drop in replacement for C<Test::Simple>
110 | X<Test::Simple> X<Module, Test::Simple> which means that you can start
111 | 
112 | The first major difference is that sometimes you are not sure how many
113 | tests you are going to run. To circumvent this problem you can use the
114 | following approach:
115 | 
116 | =begin Perl
117 | 
118 |   use Test::More;
119 |   # do tests
120 |   done_testing;
121 | 
122 | =end Perl
123 | 
124 | Has you can see no plan (number of tests) are defined we the module is used
125 | in line 1. After all the tests are executed the C<done_testing> function
126 | is called to let the testing framework know that all the tests have been
127 | executed. You can provide an extra argument to this function which is
128 | the number of tests that were executed if you can calculate it easily.
129 | 
130 | Some new useful functions are also introduced in this module, and has
131 | stated earlier the C<ok> function is still provided and has the same
132 | behavior as in C<Test::Simple> X<Test::Simple> X<Module, Test::Simple>.
133 | C<is> is another function that can be used, for example:
134 | 
135 | =begin Perl
136 | 
137 |   my $got = 12;
138 |   my $expected = 12;
139 | 
140 |   is( $got, $expected, 'simple test' );
141 | 
142 | =end Perl
143 | 
144 | The C<is> function requires at least two arguments, and when is called
145 | performs a comparison between these two arguments, if this comparison
146 | evaluates as a true value then the test passed. There is a dual for this
147 | function called C<isnt> that will consider the test as passed if the
148 | result of evaluating the expression of comparing the two first arguments
149 | is not true.
150 | 
151 | The C<like> function works in a similar way but instead of doing an equals
152 | comparison between the first two arguments if tries to match the first
153 | argument to the second, being the second argument a regular expression, for
154 | example:
155 | 
156 |     like( $day, qr/\d+/, 'day ok' );
157 | 
158 | The C<unlike> function has a similar behavior but the test passes if
159 | the first argument does not match the regular expression given as second
160 | argument. Common to all these functions is the third argument, which is
161 | the name of the test and is optional.
162 | 
163 | Scalar variables can hold references for complex that structures, if you
164 | wish to compare these data structure you should use the C<is_deeply> function
165 | 
166 |      is_deeply( $data, $reference, 'data is equal' );
167 | 
168 | For a more complete way for comparing complete data structures that a
169 | look at the C<Test::Deep> X<Test::Deep> X<Module, Test::Deep> module.
170 | 
171 | Another useful function is the C<use_ok> function, that can be used
172 | to verify if a module can be loaded correctly. For example:
173 | 
174 |       use_ok( 'Test::more' );
175 | 
176 | This can be used that a module is syntax error free and that the Perl
177 | compiler can load this module.
178 | 
179 | We only described some of the features that this module provides for
180 | maintaing a test suite, for a complete list of functions read the module
181 | documentation.
182 | 
183 | =head1 Test::Deep
184 | 
185 | X<Module, Test::Deep>X<Test::Deep>
186 | 
187 | =begin CPANinfo
188 | 
189 | B<Version:> 0.108
190 | 
191 | B<CPAN:> L<http://search.cpan.org/dist/Test-Deep>
192 | 
193 | =end CPANinfo
194 | 
195 | =head1 Test::Output
196 | 
197 | X<Module, Test::Output>X<Test::Output>
198 | 
199 | =begin CPANinfo
200 | 
201 | B<Version:> 1.01
202 | 
203 | B<CPAN:> L<http://search.cpan.org/dist/Test-Output>
204 | 
205 | =end CPANinfo
206 | 
207 | C<Test::Output> X<Test::Output> X<Module, Test::Output> is another handy
208 | module for testing. Sometimes you want to be able to test if your code
209 | is producing the correct output. So, we would like to capture the output
210 | of executing this code and compare it with the correct result. We can use
211 | this module to achieve this, for example, imagine you have a function that
212 | prints something to the standard output  and we want to test if this function
213 | is working properly. For this we can use the C<stdout_is> function provided
214 | by this module has shown in the following snippet:
215 | 
216 | =begin Perl
217 | 
218 |   use Test::More tests => 1;
219 |   use Test::Output;
220 | 
221 |   sub function {
222 |     print "testing is good!";
223 |   }
224 | 
225 |   stdout_is(\&function, 'testing is good!', 'simple test');
226 | 
227 | =end Perl
228 | 
229 | C<stderr_is> can be used to validate the output sent to the standard error
230 | pipe in a similar way. If you wish to test the full output of your code,
231 | combining the standard and error output (typically C<STDERR> and C<STDOUT>)
232 | the C<combined_is> function can be used. For example:
233 | 
234 | =begin Perl
235 | 
236 |   use Test::More tests => 1;
237 |   use Test::Output;
238 | 
239 |   sub function {
240 |     print STDOUT "hello";
241 |     print STDERR "World";
242 |   }
243 | 
244 |   combined_is(\&function, 'helloWorld', 'simple test');
245 | 
246 | =end Perl
247 | 
248 | Another very commonly used function in this module is the C<output_is>
249 | function, which has ax extra argument, so that you can explicitly test
250 | what is being written to C<STDERR> and C<STDOUT>. Using a similar example
251 | to the ones already shown we could have something like:
252 | 
253 | =begin Perl
254 | 
255 |   use Test::More tests => 1;
256 |   use Test::Output;
257 | 
258 |   sub function {
259 |     print STDOUT "hello";
260 |     print STDERR "World";
261 |   }
262 | 
263 |   output_is(\&function, 'hello', 'World', 'simple test');
264 | 
265 | =end Perl
266 | 
267 | In this case we are using the C<output_is> function to validate that the
268 | output from running the code to C<STDOUT> is C<hello> and to C<STDERR> is
269 | C<World>.
270 | 
271 | Similar to the functions described earlier this module also provides 
272 | the typical variants: C<*_isnt>, C<*_like> and C<*_unlike>. For more
273 | information on these specific functions refer to the modules' documentation.
274 | 
275 | =head1 Test::TCP
276 | 
277 | X<Module, Test::TCP>X<Test::TCP>
278 | 
279 | =begin CPANinfo
280 | 
281 | B<Version:> 1.13
282 | 
283 | B<CPAN:> L<http://search.cpan.org/dist/Test-TCP>
284 | 
285 | =end CPANinfo
286 | 
287 | =head1 Devel::Cover
288 | 
289 | X<Module, Test::Output>X<Test::Output>
290 | 
291 | =begin CPANinfo
292 | 
293 | B<Version:> 0.78
294 | 
295 | B<CPAN:> L<http://search.cpan.org/dist/Devel-Cover>
296 | 
297 | =end CPANinfo
298 | 
299 | =cut
300 | 
301 | =begin SeeAlso
302 | 
303 | If it is your first time writing tests C<Test::Tutorial> X<Test::Tutorial>
304 | is the place to start.
305 | 
306 | C<Test> is the namespace dedicated to modules related with testing in
307 | CPAN.
308 | 
309 | =end SeeAlso
310 | 
311 | =cut
312 | 
313 | ## Local Variables:
314 | ##  ispell-local-dictionary: "english"
315 | ##  mode: flyspell
316 | ## End:
317 | 


--------------------------------------------------------------------------------
/CPAN/chapters/80-protocols.pod:
--------------------------------------------------------------------------------
 1 | 
 2 | =head0 Working With Internet Protocols
 3 | 
 4 | =head1 LWP
 5 | 
 6 | =head1 WWW::Mechanize
 7 | 
 8 | =head1 Email::Sender
 9 | 
10 | or Email::Simple::Creator?
11 | 
12 | 
13 | =cut
14 | 
15 | ## Local Variables:
16 | ##  ispell-local-dictionary: "english"
17 | ##  mode: flyspell
18 | ## End:
19 | 


--------------------------------------------------------------------------------
/CPAN/chapters/90-uncategorized.pod:
--------------------------------------------------------------------------------
 1 | 
 2 | =head0 Uncategorized
 3 | 
 4 | Some modules are very specific for a given task, and although there is not
 5 | a chapter devoted to theses tasks, they are still worth mention. This
 6 | chapter enumerates some relevant and important modules that do not have
 7 | place in any of the previous chapters.
 8 | 
 9 | =head1 MIME::Base64
10 | 
11 | =head1 Modern::Perl
12 | 
13 | =head1 Perl::Critic
14 | 
15 | =head1 Smart::Comments
16 | 
17 | 
18 | 
19 | 
20 | 
21 | 
22 | 
23 | =cut
24 | 
25 | ## Local Variables:
26 | ##  ispell-local-dictionary: "english"
27 | ##  mode: flyspell
28 | ## End:
29 | 


--------------------------------------------------------------------------------
/CPAN/tex/asbook.sty:
--------------------------------------------------------------------------------
  1 | \usepackage{polyglossia}
  2 | \usepackage{fontspec}
  3 | \usepackage{multicol}
  4 | \usepackage{xltxtra}
  5 | \usepackage{url}
  6 | \usepackage{framed}
  7 | \usepackage{fancyvrb}
  8 | \RequirePackage[colorlinks,hyperindex,plainpages=false,linkcolor=black,citecolor=black,filecolor=black,urlcolor=black]{hyperref}
  9 | \usepackage{nameref}
 10 | 
 11 | \defaultfontfeatures{Scale=MatchLowercase}
 12 | \setmainfont[Mapping=tex-text]{Baskerville}
 13 | \setsansfont[Mapping=tex-text]{Skia}
 14 | \setmonofont{Courier}
 15 | \usepackage{dirtree}
 16 | 
 17 | \usepackage{color}
 18 | 
 19 | 
 20 | 
 21 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 22 | %%
 23 | %% 0. Headings and Footers
 24 | 
 25 | \usepackage{fancyhdr}
 26 | \pagestyle{fancy}
 27 | \fancyhead[LE,RO]{\small\thepage}
 28 | \fancyfoot[R,L]{}
 29 | %%\fancyfoot[C]{\today}
 30 | \renewcommand{\headrulewidth}{0pt}
 31 | \renewcommand{\footrulewidth}{0pt}
 32 | \fancyfoot[C]{}
 33 | \renewcommand{\chaptermark}[1]{\markboth{ \thechapter.\ #1}{}}
 34 | \renewcommand{\sectionmark}[1]{\markright{ \thesection.\ #1}}
 35 | %\rhead{\nouppercase{\rightmark}}
 36 | %\lhead{\nouppercase{\leftmark}}
 37 | \fancyhead[LO]{\nouppercase{\small\rightmark}}
 38 | \fancyhead[RE]{\nouppercase{\small\leftmark}}
 39 | %\fancyhead[RE,LO]{}      
 40 | \pagestyle{plain}
 41 | 
 42 | 
 43 | 
 44 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 45 | %%
 46 | %% 1. Set Chapter style
 47 | 
 48 | \def\@makechapterhead#1{%
 49 |   \vspace*{10\p@}%
 50 |   {\parindent \z@ \raggedright \normalfont
 51 |     \ifnum \c@secnumdepth >\m@ne
 52 |       \if@mainmatter
 53 |       {\huge\bfseries\fontspec[Variant=2,Color=DDDDDDFF,Scale=2]{Zapfino}\@chapapp\space \thechapter}\\[-30\p@]
 54 |       
 55 |       \fi
 56 |     \fi
 57 |     \interlinepenalty\@M
 58 |     {
 59 |       \fontspec[Contextuals={WordInitial,WordFinal},Color=00000055,Scale=2.5]{Hoefler Text Italic}  #1\par\nobreak
 60 |     }
 61 |     \vskip 15\p@
 62 |   }}
 63 | 
 64 | \def\@makeschapterhead#1{%
 65 |   \vspace*{50\p@}%
 66 |   {\parindent \z@ \raggedright
 67 |     \normalfont
 68 |     \interlinepenalty\@M
 69 |     {
 70 |       \fontspec[Contextuals={WordInitial,WordFinal},Color=00000055,Scale=2.5]{Hoefler Text Italic}  #1\par\nobreak
 71 |     }
 72 |     \vskip 15\p@
 73 |   }}
 74 | 
 75 | 
 76 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 77 | %%
 78 | %% 2. Set Section style
 79 | 
 80 | \def\section{\@ifstar\unnumberedsection\numberedsection}
 81 | 
 82 | \def\numberedsection{\@ifnextchar[%]
 83 |   \numberedsectionwithtwoarguments\numberedsectionwithoneargument}
 84 | 
 85 | \def\unnumberedsection{\@ifnextchar[%]
 86 |   \unnumberedsectionwithtwoarguments\unnumberedsectionwithoneargument}
 87 | 
 88 | \def\numberedsectionwithoneargument#1{\numberedsectionwithtwoarguments[#1]{#1}}
 89 | 
 90 | \def\unnumberedsectionwithoneargument#1{\unnumberedsectionwithtwoarguments[#1]{#1}}
 91 | 
 92 | \def\numberedsectionwithtwoarguments[#1]#2{%
 93 |   \ifhmode\par\fi
 94 |   \removelastskip
 95 |   \vskip 3ex\goodbreak
 96 |   \refstepcounter{section}%
 97 |   \noindent
 98 |   \begingroup
 99 |   \leavevmode\Large\raggedright
100 |   \llap{\fontspec[Variant=2,Color=BBBBBBFF,Scale=1]{Zapfino}\thesection}%
101 |   {\ \ \fontspec[Contextuals={WordInitial,WordFinal},Color=00000055,Scale=1.25]{Hoefler Text Italic} #2}
102 |   \par
103 |   \endgroup
104 |   \vskip 2ex\nobreak
105 |   \addcontentsline{toc}{section}{%
106 |     \protect\numberline{\thesection}%
107 |     #1}%
108 |   \sectionmark{#1}
109 |   }
110 | 
111 | \def\unnumberedsectionwithtwoarguments[#1]#2{%
112 |   \ifhmode\par\fi
113 |   \removelastskip
114 |   \vskip 3ex\goodbreak
115 | %  \refstepcounter{section}%
116 |   \noindent
117 |   \begingroup
118 |   \leavevmode\Large\bfseries\raggedright
119 |   \leavevmode\Large\bfseries\raggedright
120 | %  \thesection\quad 
121 |   {\fontspec[Contextuals={WordInitial,WordFinal},Color=00000055,Scale=1.25]{Hoefler Text Italic} #2}
122 |   \par
123 |   \endgroup
124 |   \vskip 2ex\nobreak
125 |   \addcontentsline{toc}{section}{%
126 | %    \protect\numberline{\thesection}%
127 |     #1}%
128 |   \sectionmark{#1}
129 | }
130 | 
131 | 
132 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
133 | %%
134 | %% 3. Title page
135 | 
136 | \newcommand{\subtitle}[1]{\def\@subtitle{#1}}
137 | \renewcommand{\and}{\\[2mm]}
138 | 
139 | \renewcommand{\maketitle}{
140 |   \thispagestyle{empty}
141 |   \mbox{}
142 |   \vfill
143 |   \begin{center}
144 |     \noindent{\huge\bfseries \fontspec[Color=33333355,Scale=2]{Hoefler Text Italic}\@title}\\    
145 | 
146 |     \vskip 1cm
147 | 
148 |     {\fontspec[Contextuals={WordInitial,WordFinal},Color=999999FF,Scale=1.5]{Hoefler Text Italic} \@subtitle}
149 |   \vfill
150 |     {\fontspec[Contextuals={WordInitial,WordFinal},Color=33333355,Scale=1.5]{Hoefler Text Italic} \@date}
151 |   \end{center}
152 |   \vfill
153 |   \begin{leftbar}
154 |     \fontspec[Contextuals={WordInitial,WordFinal},Color=33333355,Scale=1.5]{Hoefler Text Italic}
155 |     \noindent    \@author
156 |   \end{leftbar}
157 |   \cleardoublepage
158 | }
159 | 
160 | 
161 | 
162 | 
163 | 
164 | 
165 | \newenvironment{cpaninfo}{\begin{flushright}\parskip 0pt}{\end{flushright}}
166 | 
167 | \newenvironment{smallenv}{ \small }{ }
168 | 
169 | \usepackage{listings}
170 | 
171 | \lstset{ %
172 |   language=Perl,                % choose the language of the code
173 |   basicstyle=\setmonofont{Courier}\ttfamily\small,            % the size of the fonts that are used for the code
174 |   numbers=left,                 % where to put the line-numbers
175 |   numberstyle=\tiny,            % the size of the fonts that are used for the line-numbers
176 |   % stepnumber=2,                   % the step between two line-numbers.
177 |   % numbersep=5pt,                  % how far the line-numbers are from the code
178 |   % backgroundcolor=\color{white},  % choose the background color. You must add \usepackage{color}
179 |   showspaces=false,             % show spaces adding particular underscores
180 |   showstringspaces=false,       % underline spaces within strings
181 |   showtabs=false,               % show tabs within strings adding particular underscores
182 |   frame=single,                 % adds a frame around the code
183 |   frameround=tfff,              % what round corners. Start in top right, clockwise
184 |   % tabsize=2,	                % sets default tabsize to 2 spaces
185 |   % captionpos=b,                   % sets the caption-position to bottom
186 |   % breaklines=true,                % sets automatic line breaking
187 |   % breakatwhitespace=false,        % sets if automatic breaks should only happen at whitespace
188 |   % title=\lstname,                 % show the filename of files included with \lstinputlisting;
189 |   % escapeinside={\%*}{*)},         % if you want to add a comment within your code
190 |   morekeywords={given,when}     % if you want to add more keywords to the set
191 |   identifierstyle=\bfseries,
192 |   keywordstyle=\bfseries,
193 |   commentstyle=\it,
194 |   stringstyle=\sf,
195 | }
196 | 
197 | 
198 | 
199 | \newlength{\seealsol}
200 | \newenvironment{SeeAlso}{~\\*[-1ex]
201 |   \protect{
202 |     {
203 |       \setlength{\seealsol}{\leftmargin}
204 |       {\mbox{}\hfill\fontspec[Variant=2,Color=DDDDDDFF,Scale=2]{Zapfino} \bfseries See Also \hfill\mbox{}}\\[-20pt]
205 |       \mbox{}\hfill {\fontspec[Contextuals={WordInitial,WordFinal},Color=00000055,Scale=1.4]{Hoefler Text Italic} See Also}\hfill\mbox{}
206 |     }
207 |     \addcontentsline{toc}{section}{\textit{See Also}}
208 |     \vskip -5mm
209 |     \noindent\rule{\textwidth}{.5pt}\\[-1pt]
210 |     \rule{.5pt}{15pt}\hfill\rule{.5pt}{15pt}\\
211 |   }
212 |   \list{}{
213 |     \addtolength{\rightmargin}{.03\textwidth}
214 |     \setlength{\leftmargin}{\seealsol}
215 |     \addtolength{\leftmargin}{.03\textwidth}
216 |   }  
217 |   \item\relax
218 |     \vskip -36pt
219 | }{
220 |   \endlist
221 |   \vskip -17pt
222 |   \rule{.5pt}{15pt}\rule{\textwidth}{.5pt}\rule{.5pt}{15pt}%\\[-14pt]
223 | %  \rule{\textwidth}{.5pt}
224 | }
225 | 
226 | 


--------------------------------------------------------------------------------
/README:
--------------------------------------------------------------------------------
 1 | 
 2 | Books
 3 | -----
 4 | 
 5 | My repo of book being.. written.
 6 | 
 7 | PLEASE DO NOT READ THE BOOKS DIRECTLY ON GITHUB POD RENDERER!
 8 | 
 9 | Folders:
10 |  CPAN - CPAN Book
11 | 


--------------------------------------------------------------------------------