This file is indexed.

/usr/share/perl5/Poet/Manual/Intro.pod is in libpoet-perl 0.16-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
__END__

=pod

=head1 NAME

Poet::Manual::Intro - A gentle introduction to Poet

=head1 WHAT IS POET?

Poet is a modern Perl web framework for Mason developers. It uses
L<PSGI|PSGI>/L<Plack|Plack> for server integration, L<Mason|Mason> for request
routing and templating, and a selection of best-of-breed CPAN modules for
caching, logging and configuration.

=head1 INSTALLATION

If you don't yet have cpanminus (C<cpanm>), get it
L<here|http://search.cpan.org/perldoc?App::cpanminus#INSTALLATION>. Then run

    cpanm -S --notest Poet

Omit the "-S" if you don't have root, in which case cpanminus will install Poet
and prereqs into C<~/perl5>.

Omit the "--notest" if you want to run all the installation tests. Note that
this will take about four times as long.

=head1 SETUP

You should now have a C<poet> app installed:

    % which poet
    /usr/local/bin/poet

Run this to create your initial environment:

    % poet new MyApp
    my_app/.poet_root
    my_app/bin/app.psgi
    my_app/bin/get.pl
    ...
    Now run 'my_app/bin/run.pl' to start your server.

The app name must be a valid Perl class name, generally either C<CamelCase>
(C<MyApp>) or an all-uppercase acronym (C<TLA>). The directory, if not
specified with -d, will be formed from the app name, but lowercased and
underscored.

=head1 ENVIRONMENT

In Poet, your entire web site lives within a single directory hierarchy called
the I<environment>. It contains subdirectories for configuration, libraries,
Mason components (templates), static files, etc.

Here are the subdirectories that are generated for you. If you don't need some
of these directories, feel free to delete them. The only ones really required
by Poet are C<conf>, C<comps> and C<lib>.

=over

=item *

C<bin> - executable scripts

=item *

C<comps> - Mason components (templates)

=item *

C<conf> - configuration files

=item *

C<data> - data not checked into version control, such as cache and object files

=item *

C<db> - database related files such as your schema

=item *

C<lib> - app-specific libraries and Poet subclasses

=item *

C<logs> - logs from web server and from explicit logging statements

=item *

C<static> - static web files - css, images, js

=item *

C<t> - unit tests

=back

=head2 Initializing Poet

Any web server or script must initialize Poet before it can use any of Poet's
features. This is accomplished by with C<Poet::Script>:

    #!/usr/local/bin/perl
    use Poet::Script qw($conf $poet);

You'll see this in C<bin/run.pl>, for example, the script you use to start your
webserver.  The C<use Poet::Script> line does several things:

=over

=item *

Searches upwards from the script for the environment root (as marked by the
C<.poet_root> file).

=item *

Reads and parses your configuration.

=item *

Unshifts onto @INC the lib/ subdirectory of your environment, so that you can
C<use> your application modules.

=item *

Imports the specified I<quick vars> - in this case C<$conf> and C<$poet> - as
well as some default utilities into the script namespace. More information
about these L<below|/QUICK VARS AND UTILITIES>.

=back

=head2 Relocatable environments

Ideally your environment will be I<relocatable> -- if you move your environment
to a different root, or checkout a second copy of it in a different root,
things should just work.

To achieve this you should never refer to exact environment directory paths in
your code; instead you'll call Poet methods that return them. e.g. instead of
this:

    system("/path/to/environment/bin/myscript.pl");

you'll do this:

    system($poet->bin_path("myscript.pl"));

(More information about this C<$poet> variable L<below|/QUICK VARS AND
UTILITIES>.)

=head2 App name

Your app name, e.g. C<MyApp>, is where you are expected to put app-specific
subclasses. For example if you have a L<DBIx::Class|DBIx::Class> schema, you'd
create it under C<MyApp::Schema> in the file C<lib/MyApp/Schema.pm>.

The app name is also where Poet will look for
L<subclasses|Poet::Manual::Subclassing> of its own classes.

=head1 CONFIGURATION AND LAYERS

Poet configuration files are kept in the C<conf> subdirectory. The files are in
L<YAML|http://www.yaml.org/> form and are merged in a particular order to
create a single configuration hash. (If you want to use something other than
YAML you can L<customize this|Poet::Manual::Subclassing>.)

Configuration files come in three varieties: C<global>, C<layer>, and C<local>,
in order from least to highest precedence.

=over

=item Global

I<Global> configuration applies to all instances of your environment, and is
typically checked into version control.

Your generated environment includes a C<conf/global.cfg>.  This is simplest to
start out with, but as a site scales in size and number of developers, you can
split out your global configuration into multiple files in
C<conf/global/*.cfg>.

=item Layer

I<Layers> allow you to have different configuration for different contexts.
With all but the simplest site you'll have at least two layers: I<development>
(the internal environment where you develop) and I<production> (the live site).
Later on, you might want a I<staging> environment (which looks like production
except for a different data source, etc.).

In general you can have as many layers as you like.  Each layer has a
corresponding configuration file in C<conf/layer/*.cfg>; only one layer file
will be loaded per environment. We recommend that these files all be checked
into version control as well, so that changes to each layer are tracked.

Note: I<layer> is analagous to Plack's I<environment> concept. And in fact,
C<bin/run.pl> passes the layer to plackup's <-E> option.

=item Local

C<conf/local.cfg> contains configuration local to this specific environment
instance.  This is where the current layer must be defined. It is also the only
configuration file that must exist, and the only one that should I<not> be
checked into version control.

You can also specify an extra local file via C<$ENV{POET_EXTRA_CONF_FILE}>.

=back

There are a variety of ways to access configuration:

    my $value = $conf->get('key', 'default');
    my $value = $conf->get_or_die('key');

    my $listref = $conf->get_list('key', ['default']);
    my $hashref = $conf->get_hash('key', {'default' => 5});
    my $bool = $conf->get_boolean('key');

See L<below|/QUICK VARS AND UTILITIES> for more information about this C<$conf>
variable, and see L<Poet::Conf|Poet::Conf> for more information on specifying
and accessing configuration.

=head2 Development versus live mode

Although you may have as many layers as you like, Poet also maintains a more
limited binary notion of I<development mode> versus I<live mode>. By default,
you're in development mode iff layer equals 'development', and in live mode
otherwise.

You can use these boolean methods to determine which mode you're in at runtime:

    $conf->is_development
    $conf->is_live

These are mutually exclusive (exactly one is always true).

Poet uses development/live mode to determine things like

=over

=item *

whether to turn on L<automatic server restarting|/SERVER RUNNER AND MIDDLEWARE>

=item *

whether to L<display errors in the browser|/Success and failure results>

=item *

whether to enable L<debugging utilities|Poet::Util::Debug>

=back

You can customize how mode is determined by L<subclassing
Poet::Conf|Poet::Manual::Subclassing>.

=head1 SERVER RUNNER AND MIDDLEWARE

C<poet new> generates C<bin/run.pl> and C<bin/app.psgi> for you.

C<bin/run.pl> is a wrapper around L<plackup|plackup>, which starts your server.
It has a few sensible defaults, such as setting up autorestart in L<development
mode|/Development versus live mode> and using an access log in L<live
mode|/Development versus live mode>. It will also take a few options from
configuration, e.g.

    server:
       host: 127.0.0.1
       port: 5000

If you are using something other than plackup (e.g.
L<Server::Starter|Server::Starter>) then you'll have to adapt this into your
own startup script.

C<bin/app.psgi> defines your PSGI app. It's the place to add L<Plack
middleware|Plack/Plack::Middleware>, or change the configuration of the default
middleware. For example, to enable basic authentication with an
C<conf/.htpasswd> file, add this to app.psgi:

    enable "Auth::Htpasswd", file => $poet->conf_path('.htpasswd');

=head1 QUICK VARS AND UTILITIES

Poet makes it easy to import certain variables (known as "quick vars") and
utility sets into any module or script in your environment. You've seen two
examples of quick vars above: C<$conf>, the global configuration variable, and
C<$poet>, the global environment object.

In a script, this looks like:

    #!/usr/local/bin/perl
    use Poet::Script qw($conf :file);

In a module, this looks like:

    package MyApp::Foo;
    use Poet qw($cache $poet);

And every Mason component automatically gets this on top:

    use Poet qw($conf $poet :web);

L<Debug utilities|Poet::Util::Debug> are automatically imported without having
to specify a tag.

See L<Poet::Import|Poet::Import> for a complete list of quick vars and utility
sets.

=head1 HANDLING HTTP REQUESTS

HTTP requests are handled with L<PSGI|PSGI>/L<Plack|Plack> and L<Mason|Mason>.

A persistent L<Mason interpreter|Mason::Interp> is created at server startup,
with L<component root|Mason::Manual::Components/The component root and
component paths> set to the C<comps> subdirectory. (See
L<Poet::Mason|Poet::Mason> for other default settings and how to configure
them.)

When an HTTP request comes in, Poet

=over

=item *

Constructs a L<Poet::Plack::Request|Poet::Plack::Request> object from the plack
environment.  This is a thin subclass of L<Plack::Request> and provides
information such as the URL and incoming HTTP headers. It is made available in
Mason components as C<< $m->req >>.

=item *

Constructs an empty L<Poet::Plack::Response|Poet::Plack::Response> object. This
is a thin subclass of L<Plack::Response>, and you may use it to set things such
as the HTTP status and headers. It is made available in Mason components as C<<
$m->res >>.

=item *

Calls C<$interp-E<gt>run> with the URL and the GET/POST parameters. So for
example, a URL like

    /foo/bar?a=5&b=6

would result in

    $interp->run("/foo/bar", a=>5, b=>6);

From there Mason will choose a component to dispatch to - see
L<Mason::Manual::RequestDispatch|Mason::Manual::RequestDispatch> and
L<Mason::Plugin::RouterSimple|Mason::Plugin::RouterSimple>.

=back

=head2 Generating content with Mason

Mason is a full-featured templating system and beyond our ability to summarize
here. Recommended reading:

=over

=item *

L<Poet::Manual::Tutorial|Poet::Manual::Tutorial>, especially starting
L<here|Poet::Manual::Tutorial/MASON PAGES AND COMPONENTS>

=item *

L<Mason::Manual::Components|Mason::Manual::Components>

=item *

L<Mason::Manual::Syntax|Mason::Manual::Syntax>

=back

=head2 Success and failure results

If the Mason request finishes successfully, the Mason output becomes the plack
response body, the status code is set to 200 if it hasn't already been set, and
the content type is set to C<text/html> (or the specified L<default content
type|Poet::Manual::Configuring/server.default_content_type>) if it hasn't
already been set.

If the top-level component path cannot be found, the status code is set to 404.

If any other kind of runtime error occurs in L<development mode|/Development
versus live mode>, it will be nicely displayed in the browser via
L<StackTrace|Plack::Middleware::StackTrace> middleware. Outside of development
it will be logged and sent as a 500 error response.

You can call C<< $m->redirect >> and C<< $m->not_found >> to generate redirect
and not_found results from a component. These are documented in
L<Poet::Mason|Poet::Mason>.

=head2 Multiple values for parameters

If there are multiple values for a GET or POST parameter, generally only the
last value will be kept, as per L<Hash::MultiValue|Hash::MultiValue>. However,
if the corresponding attribute in the page component is declared an
C<ArrayRef>, then all values will be kept and passed in as an arrayref. For
example, if the page component C</foo/bar.mc> has these declarations:

    <%class>
    has 'a';
    has 'b' => (isa => "Int");
    has 'c' => (isa => "ArrayRef");
    has 'd' => (isa => "ArrayRef[Int]");
    </%class>

then this URL

    /foo/bar?a=1&a=2&b=3&b=4&c=5&c=6&d=7&d=8

would result in

    $interp->run("/foo/bar", a=>2, b=>4, c=>[5,6], d => [7,8]);

You can always get the original Hash::MultiValue object from C<<
$m->request_args >>. e.g.

    my $hmv = $m->request_args;
    # get all values for 'e'
    $hmv->get_all('e');

=head1 LOGGING

Poet uses the L<Log::Log4perl|Log::Log4perl> engine for logging, but with a
much simpler configuration for the common cases. (If you want to use something
other than Log4perl you can L<customize this|Poet::Manual::Subclassing>.)

Once you have a L<$log|/QUICK VARS AND UTILITIES> variable, logging looks like:

    $log->error("an error occurred");

    $log->debugf("arguments are: %s", \@_)
        if $log->is_debug();

By default, all logs go to C<logs/poet.log> with a reasonable set of metadata
such as timestamp.

See L<Poet::Log|Poet::Log> for more information.

=head1 CACHING

Poet uses L<CHI|CHI> for caching, providing access to a wide variety of cache
backends (memory, files, memcached, etc.) You can configure caching differently
for different namespaces.

Once you have a L<$cache|/QUICK VARS AND UTILITIES> variable, caching looks
like:

    my $customer = $cache->get($name);
    if ( !defined $customer ) {
        $customer = get_customer_from_db($name);
        $cache->set( $name, $customer, "10 minutes" );
    }

or

    my $customer2 = $cache->compute($name2, "10 minutes", sub {
        get_customer_from_db($name2)
    });

By default, everything is cached in files under C<data/chi>.

See L<Poet::Cache|Poet::Cache> for more information.

=head1 SEE ALSO

L<Poet|Poet>

=head1 AUTHOR

Jonathan Swartz <swartz@pobox.com>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Jonathan Swartz.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut