this file will also act as a class module, so you can save it as HelloWorld.pm
and use it as-is in test scripts or other deployment mechanisms.
-Note that you should retain the ->run_if_script even if your app is a
+Note that you should retain the C<< ->run_if_script >> even if your app is a
module, since this additionally makes it valid as a .psgi file, which can
be extremely useful during development.
use warnings FATAL => 'aa';
provided you 'use Web::Simple' at the top of the file. Note that we turn
-on *fatal* warnings so if you have any warnings at any point from the file
+on B<fatal> warnings so if you have any warnings at any point from the file
that you did 'use Web::Simple' in, then your application will die. This is,
so far, considered a feature.
When we inherit from L<Web::Simple::Application> we also use L<Moo>, which is
-the the equivalent of:
+the equivalent of:
{
package NameOfApplication;
is encountered in other code.
+One important thing to remember when using
+
+ NameOfApplication->run_if_script;
+
+At the end of your app is that this call will create an instance of your app
+for you automatically, regardless of context. An easier way to think of this
+would be if the method were more verbosely named
+
+ NameOfApplication->run_request_if_script_else_turn_coderef_for_psgi;
+
=head1 DISPATCH STRATEGY
L<Web::Simple> despite being straightforward to use, has a powerful system
array ref.
sub dispatch_request {
- [ sub {
+ [ sub {
my $respond = shift;
# This is pure PSGI here, so read perldoc PSGI
} ]
C<sub (.html)>, which adds a C<response_filter> (basically a specialized routine
that follows the L<Plack::Middleware> specification), and then later we also
match C<sub (/user/*)> which gets a user and returns that as the response.
-This user object 'bubbles up' through all the wrapping middleware until it hits
+This user object "bubbles up" through all the wrapping middleware until it hits
the C<response_filter> we defined, after which the return is converted to a
true html response.
-However, two types of object are treated specially - a C<Plack::Component> object
+However, two types of objects are treated specially - a L<Plack::Component> object
will have its C<to_app> method called and be used as a dispatcher:
sub dispatch_request {
=head2 Web::Simple match specifications
+Even though the following examples all use subroutine prototypes, an
+alternative to declare a match specification for a given route is to provide a
+L<Dancer>-like key-value list:
+
+ sub dispatch_request {
+ my $self = shift;
+ (
+ '.html' => sub { ... },
+ 'GET + /user/*' => sub { ... },
+ ## equivalent to:
+ # sub (.html) { ... },
+ # sub (GET + /user/*) { ... },
+ )
+ }
+
+This can be useful in situations where you are generating a dispatch table
+programmatically, where setting a subroutine's protoype is difficult.
+
=head3 Method matches
sub (GET) {
sub (/login) {
-A match specification beginning with a / is a path match. In the simplest
+A match specification beginning with a C</> is a path match. In the simplest
case it matches a specific path. To match a path with a wildcard part, you
can do:
$self->handle_user($_[1])
This will match /user/<anything> where <anything> does not include a literal
-/ character. The matched part becomes part of the match arguments. You can
+C</> character. The matched part becomes part of the match arguments. You can
also match more than one part:
sub (/user/*/*) {
useful for having e.g. an optional language specification at the start of a
path.
-Note that the '...' is a "maybe something here, maybe not" so the above
+Note that the C<...> is a "maybe something here, maybe not" so the above
specification will match like this:
/foo # no match
"I match anything capturing { allofit => \$whole_path }"
}
-In the specific case of a simple single-* match, the * may be omitted, to
+In the specific case of a simple single-C<*> match, the C<*> may be omitted, to
allow you to write:
sub (/:one/:two/:three/:four) {
=head3 Query and body parameter matches
-Query and body parameters can be match via
+Query and body parameters can be matched via
sub (?<param spec>) { # match URI query
sub (%<param spec>) { # match body params
to implement paging and ordering against a L<DBIx::Class::ResultSet> object.
-Another Example: To get all parameters as a hashref of arrayrefs, write:
+Another example: To get all parameters as a hashref of arrayrefs, write:
sub(?@*) {
my ($self, $params) = @_;
sub (?foo=&@bar~&:coffee=&@*) {
my ($self, $foo, $bar, $params);
-where $bar is an arrayref (possibly an empty one), and $params contains
-arrayref values for all parameters B<not> mentioned and a scalar value for
-the 'coffee' parameter.
+where C<$bar> is an arrayref (possibly an empty one), and C<$params> contains
+arrayref values for all parameters B<not> mentioned and a scalar value for the
+C<coffee> parameter.
Note, in the case where you combine arrayref, single parameter and named
hashref style, the arrayref and single parameters will appear in C<@_> in the
Note that this match type will succeed in two circumstances where you might
not expect it to - first, when the field exists but is not an upload field
and second, when the field exists but the form is not an upload form (i.e.
-content type "application/x-www-form-urlencoded" rather than
-"multipart/form-data"). In either of these cases, what you'll get back is
+content type C<application/x-www-form-urlencoded> rather than
+C<multipart/form-data>). In either of these cases, what you'll get back is
a C<Web::Dispatch::NotAnUpload> object, which will C<die> with an error
pointing out the problem if you try and use it. To be sure you have a real
upload object, call
=head3 Combining matches
-Matches may be combined with the + character - e.g.
+Matches may be combined with the C<+> character - e.g.
sub (GET + /user/*) {
-to create an AND match. They may also be combined withe the | character - e.g.
+to create an AND match. They may also be combined with the C<|> character -
+e.g.
sub (GET|POST) {
-to create an OR match. Matches can be nested with () - e.g.
+to create an OR match. Matches can be nested with C<()> - e.g.
sub ((GET|POST) + /user/*) {
-and negated with ! - e.g.
+and negated with C<!> - e.g.
sub (!/user/foo + /user/*) {
-! binds to the immediate rightmost match specification, so if you want
+C<!> binds to the immediate rightmost match specification, so if you want
to negate a combination you will need to use
sub ( !(POST|PUT|DELETE) ) {
-and | binds tighter than +, so
+and C<|> binds tighter than C<+>, so
sub ((GET|POST) + /user/*) {
projects / catagits/Web-Simple.git / blobdiff