use Moo ();
use Web::Dispatch::Wrapper ();
-our $VERSION = '0.004';
+our $VERSION = '0.008';
sub import {
my ($class, $app_package) = @_;
http://my.server.name/cgi-bin/hello-world.cgi/
you'll get the "Hello world!" string output to your browser. For more complex
-examples and non-CGI deployment, see below. To get help with Web::Simple,
+examples and non-CGI deployment, see below. To get help with L<Web::Simple>,
please connect to the irc.perl.org IRC network and join #web-simple.
=head1 DESCRIPTION
-The philosophy of Web::Simple is to keep to an absolute bare minimum, for
+The philosophy of L<Web::Simple> is to keep to an absolute bare minimum for
everything. It is not designed to be used for large scale applications;
the L<Catalyst> web framework already works very nicely for that and is
a far more mature, well supported piece of software.
However, if you have an application that only does a couple of things, and
-want to not have to think about complexities of deployment, then Web::Simple
+want to not have to think about complexities of deployment, then L<Web::Simple>
might be just the thing for you.
-The only public interface the Web::Simple module itself provides is an
-import based one:
+The only public interface the L<Web::Simple> module itself provides is an
+C<import> based one:
use Web::Simple 'NameOfApplication';
-This imports 'strict' and 'warnings FATAL => "all"' into your code as well,
-so you can skip the usual:
+This sets up your package (in this case "NameOfApplication" is your package)
+so that it inherits from L<Web::Simple::Application> and imports L<strictures>,
+as well as installs a C<PSGI_ENV> constant for convenience, as well as some
+other subroutines.
+
+Importing L<strictures> will automatically make your code use the C<strict> and
+C<warnings> pragma, so you can skip the usual:
use strict;
- use warnings;
+ 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
that you did 'use Web::Simple' in, then your application will die. This is,
so far, considered a feature.
-Calling the import also makes NameOfApplication isa Web::Simple::Application
-and sets your app class up as a L<Moo> class- i.e. does the equivalent of
+When we inherit from L<Web::Simple::Application> we also use L<Moo>, which is
+the the equivalent of:
{
package NameOfApplication;
extends 'Web::Simple::Application';
}
+So you can use L<Moo> features in your application, such as creating attributes
+using the C<has> subroutine, etc. Please see the documentation for L<Moo> for
+more information.
+
It also exports the following subroutines for use in dispatchers:
response_filter { ... };
=head1 DISPATCH STRATEGY
+L<Web::Simple> despite being straightforward to use, has a powerful system
+for matching all sorts of incoming URLs to one or more subroutines. These
+subroutines can be simple actions to take for a given URL, or something
+more complicated, including entire L<Plack> applications, L<Plack::Middleware>
+and nested subdispatchers.
+
=head2 Examples
sub dispatch_request {
You can also return a plain subroutine which will be called with just $env
- remember that in this case if you need $self you -must- close over it.
-If you return a normal object, Web::Simple will simply return it upwards on
-the assumption that a response_filter somewhere will convert it to something
-useful - this allows:
+If you return a normal object, L<Web::Simple> will simply return it upwards on
+the assumption that a response_filter (or some arbitrary L<Plack::Middleware>)
+somewhere will convert it to something useful. This allows:
sub dispatch_request {
my $self = shift;
sub (/user/*) { $self->users->get($_[1]) },
}
-to render a user object to HTML, for example.
+to render a user object to HTML, if there is an incoming URL such as:
+
+ http://myweb.org/user/111.html
+
+This works because as we descend down the dispachers, we first match
+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
+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 Plack::App object
-will have its ->to_app method called and be used as a dispatcher:
+will have its C<->to_app> method called and be used as a dispatcher:
sub dispatch_request {
my $self = shift;
}
And that's it - but remember that all this happens recursively - it's
-dispatchers all the way down.
+dispatchers all the way down. A URL incoming pattern will run all matching
+dispatchers and then hit all added filters or L<Plack::Middleware>.
=head2 Web::Simple match specifications
sub (/foo/...) {
-will match /foo/ on the beginning of the path -and- strip it, much like
-.html strips the extension. This is designed to be used to construct
-nested dispatch structures, but can also prove useful for having e.g. an
-optional language specification at the start of a path.
+Will match /foo/ on the beginning of the path -and- strip it. This is designed
+to be used to construct nested dispatch structures, but can also prove 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
specification will match like this:
/foo/ # match and strip path to '/'
/foo/bar/baz # match and strip path to '/bar/baz'
+Note: Since Web::Simple handles a concept of file extensions, * and **
+matchers will not by default match things after a final dot, and this
+can be modified by using *.* and **.* in the final position, i.e.:
+
+ /one/* matches /one/two.three and captures "two"
+ /one/*.* matches /one/two.three and captures "two.three"
+ /** matches /one/two.three and captures "one/two"
+ /**.* matches /one/two.three and captures "one/two.three"
+
=head3 Extension matches
sub (.html) {
-will match and strip .html from the path (assuming the subroutine itself
-returns something, of course). This is normally used for rendering - e.g.
+will match .html from the path (assuming the subroutine itself returns
+something, of course). This is normally used for rendering - e.g.
sub (.html) {
response_filter { $self->render_html($_[1]) }
sub (.*) {
-will match any extension and supplies the stripped extension as a match
-argument.
+will match any extension and supplies the extension as a match argument.
=head3 Query and body parameter matches
one per non-:/* parameter (scalar for normal, arrayref for multiple),
plus if any :/* specs exist a hashref containing those values.
-So, to match a page parameter with an optional order_by parameter one
+Please note that if you specify a multiple type parameter match, you are
+ensured of getting an arrayref for the value, EVEN if the current incoming
+request has only one value. However if a parameter is specified as single
+and multiple values are found, the last one will be used.
+
+For example to match a page parameter with an optional order_by parameter one
would write:
sub (?page=&order_by~) {
to implement paging and ordering against a L<DBIx::Class::ResultSet> object.
-Note that if a parameter is specified as single and multiple values are found,
-the last one will be used.
-
-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) = @_;
arrayref values for all parameters -not- mentioned and a scalar value for
the '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
+order you defined them in the protoype, but all hashrefs will merge into a
+single C<$params>, as in the example above.
+
=head3 Combining matches
Matches may be combined with the + character - e.g.
are equivalent, but
- sub ((GET + .html) | (POST + .html)) {
+ sub ((GET + /admin/...) | (POST + /admin/...)) {
and
- sub (GET + .html | POST + .html) {
+ sub (GET + /admin/... | POST + /admin/...) {
are not - the latter is equivalent to
- sub (GET + (.html|POST) + .html) {
+ sub (GET + (/admin/...|POST) + /admin/...) {
-which will never match.
+which will never match!
=head3 Whitespace
'/other/url', the dispatch behaviour will be exactly as if the same POST
request had been made to '/other/url' instead.
+Note, this is not the same as returning an HTTP 3xx redirect as a response;
+rather it is a much more efficient internal process.
+
=head1 CHANGES BETWEEN RELEASES
=head2 Changes between 0.004 and 0.005
drive me insane was rather nice and decided to spend my attempt at nanowrimo
for 2009 improving and documenting it to the point where others could use it.
-The Antiquated Perl talk can be found at L<http://www.shadowcat.co.uk/archive/conference-video/>.
+The Antiquated Perl talk can be found at L<http://www.shadowcat.co.uk/archive/conference-video/> and the slides are reproduced in this distribution under
+L<Web::Simple::AntiquatedPerl>.
=head1 COMMUNITY AND SUPPORT
=head1 COPYRIGHT
-Copyright (c) 2009 the Web::Simple L</AUTHOR> and L</CONTRIBUTORS>
+Copyright (c) 2010 the Web::Simple L</AUTHOR> and L</CONTRIBUTORS>
as listed above.
=head1 LICENSE
projects / catagits/Web-Simple.git / blobdiff