File Coverage

blib/lib/MVC/Neaf.pm
Criterion Covered Total %
statement 48 49 97.9
branch 19 22 86.3
condition 12 21 57.1
subroutine 11 11 100.0
pod 2 2 100.0
total 92 105 87.6


line stmt bran cond sub pod time code
1             package MVC::Neaf;
2              
3 81     81   4679770 use 5.006;
  81         1009  
4 81     81   459 use strict;
  81         193  
  81         1924  
5 81     81   422 use warnings;
  81         178  
  81         5676  
6              
7             our $VERSION = '0.29';
8              
9             =head1 NAME
10              
11             MVC::Neaf - Not Even A (Web Application) Framework
12              
13             =head1 OVERVIEW
14              
15             Neaf C<[ni:f]> stands for Not Even A Framework.
16              
17             The B is assumed to be just a regular Perl module,
18             no restrictions are imposed on it.
19              
20             The B is an object with one method, C, receiving a hashref
21             and returning rendered content as string plus optional content-type header.
22              
23             The B is a prefix tree of subroutines called I.
24             Each such handler receives a L object
25             containing I it needs to know about the outside world,
26             and returns a simple C<\%hashref> which is forwarded to View.
27              
28             Alternatively, it can die. C is a valid way to return
29             a customizable "404 Not Found" page.
30              
31             Please see the C directory in this distribution
32             that demonstrates the features of Neaf.
33              
34             =head1 SYNOPSIS
35              
36             The following application, outputting a greeting, is ready to run
37             as a L script, L application, or Apache handler.
38              
39             use strict;
40             use warnings;
41             use MVC::Neaf;
42              
43             get+post '/hello' => sub {
44             my $req = shift;
45              
46             my $name = $req->param( name => qr/[-'\w\s]+/ ) || "Mystical stranger";
47             return {
48             name => $name,
49             };
50             }, default => {
51             -view => 'TT',
52             -type => "text/plain",
53             -template => \"Hello, [% name %]",
54             };
55              
56             neaf->run;
57              
58             A neaf application has some command-line interface built in:
59              
60             perl myapp.pl --list
61              
62             Will give a summary of available routes.
63              
64             perl myapp.pl --listen :31415
65              
66             Will start a default C server (C works as well)
67              
68             perl myapp.pl --post --upload foo=/path/to/file /bar?life=42 --view Dumper
69              
70             Will run just one request and stop right before template processing,
71             dumping stash instead.
72              
73             =head1 CREATING AN APPLICATION
74              
75             =head2 THE CONTROLLER
76              
77             The handler sub receives one and only argument, the B object,
78             and outputs a C<\%hashref>.
79              
80             It may also die, which will be interpreted as an error 500,
81             UNLESS error message starts with 3 digits and a whitespace,
82             in which case this is considered the return status.
83             E.g. C is a valid method to return
84             a configurable "Not Found" page right away.
85              
86             Handlers are set up using the L method discussed below.
87              
88             =head2 THE REQUEST
89              
90             L interface is
91             similar to that of L or L with some minor differences:
92              
93             # What was requested:
94             http(s)://server.name:1337/mathing/route/some/more/slashes?foo=1&bar=2
95              
96             # What is being returned:
97             $req->http_version; # = HTTP/1.0 or HTTP/1.1
98             $req->scheme ; # = http or https
99             $req->method ; # = GET
100             $req->hostname ; # = server.name
101             $req->port ; # = 1337
102             $req->path ; # = /mathing/route/some/more/slashes
103             $req->prefix ; # = /mathing/route
104             $req->postfix ; # = /some/more/slashes
105              
106             $req->param( foo => '\d+' ); # = 1
107             $req->get_cookie( session => '.+' ); # = whatever it was set to before
108              
109             One I difference is that there's no (easy) way to fetch
110             query parameters or cookies without validation.
111             Just use pattern C if you know better.
112             But see also L, forms are quite powerful.
113              
114             Also there are some methods that affect the reply,
115             mainly the headers, like C or C.
116             This is a step towards a know-it-all God object,
117             however, mapping those properties into a hashref turned out to be
118             too cumbersome.
119              
120             =head2 THE RESPONSE
121              
122             B may contain regular keys, typically alphanumeric,
123             as well as a predefined set of dash-prefixed keys to control
124             Neaf itself.
125              
126             return {
127             -view => 'TT',
128             -template => 'users.html',
129             users => \@list,
130             extras => \%hash,
131             };
132              
133             And that's it.
134              
135             I<-Note -that -dash-prefixed -options -look -antique
136             even to the author of this writing.
137             However, it is a concise and B way to separate
138             auxiliary parameters from users's data,
139             without requiring a more complex return structure
140             (two hashes, array of arrays etc).>
141              
142             The small but growing list of these -options is as follows:
143              
144             =over
145              
146             =item * -content - Return raw data and skip view processing.
147             E.g. display generated image.
148              
149             =item * -continue - A callback that receives the Request object.
150             It will be executed AFTER the headers and the first content chunk
151             are served to the client, and may use C<$req-Ewrite( $data );>
152             and C<$req-Eclose;> to output more data.
153              
154             =item * -headers - Pass a hash or array of values for header generation.
155             This is an alternative to L's C method.
156              
157             =item * -jsonp - Used by C view module as a callback name to produce a
158             L response.
159             Callback MUST be a set of identifiers separated by dots.
160             Otherwise it's ignored for security reasons.
161              
162             =item * -location - HTTP Location: header for 3xx statuses.
163             This is set by C<$request-Eredirect(...)>.
164              
165             B<[DEPRECATED]> This will be phased out at some point,
166             use C<-header =E [ location =E ... ]> instead.
167              
168             =item * -payload - if present, the C view will render this instead of
169             the whole response hash.
170             This can be used, for instance, to return non-hash data in a REST API.
171              
172             Also used to be C<-serial> which is now deprecated.
173              
174             B<[EXPERIMENTAL]> Name and meaning may change in the future.
175              
176             =item * -status - HTTP status (200, 404, 500 etc).
177             Default is 200 if the handler managed to live through, and 500 if it died.
178              
179             =item * -template - Set template name for a text processing view
180             (currently L based on L