use Moo ();
use Web::Dispatch::Wrapper ();
-our $VERSION = '0.004';
+our $VERSION = '0.008';
sub import {
my ($class, $app_package) = @_;
Web::Simple - A quick and easy way to build simple web applications
-=head1 WARNING
-
-This is really quite new. If you're reading this on CPAN, it means the stuff
-that's here we're probably happy with. But only probably. So we may have to
-change stuff. And if you're reading this from git, come check with irc.perl.org
-#web-simple that we're actually sure we're going to keep anything that's
-different from the CPAN version.
-
-If we do find we have to change stuff we'll add to the
-L<CHANGES BETWEEN RELEASES> section explaining how to switch your code across
-to the new version, and we'll do our best to make it as painless as possible
-because we've got Web::Simple applications too. But we can't promise not to
-change things at all. Not yet. Sorry.
=head1 SYNOPSIS
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 L<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.
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 setups up your package (in this case "NameOfApplication" is your package)
+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 you code use the C<strict> and
+Importing L<strictures> will automatically make your code use the C<strict> and
C<warnings> pragma, so you can skip the usual:
use strict;
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 <Moo>, which is
+When we inherit from L<Web::Simple::Application> we also use L<Moo>, which is
the the equivalent of:
{
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> dispite being straightforward to use, has a powerful system
+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>
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
sub (?<param spec>) { # match URI query
sub (%<param spec>) { # match body params
-The body is only matched if the content type is
-application/x-www-form-urlencoded (note this means that Web::Simple does
-not yet handle uploads; this will be addressed in a later release).
+The body spec will match if the request content is either
+application/x-www-form-urlencoded or multipart/form-data - the latter
+of which is required for uploads, which are now handled experimentally
+- see below.
The param spec is elements of one of the following forms -
order you defined them in the protoype, but all hashrefs will merge into a
single C<$params>, as in the example above.
+=head3 Upload matches (EXPERIMENTAL)
+
+Note: This feature is experimental. This means that it may not remain
+100% in its current form. If we change it, notes on updating your code
+will be added to the L</CHANGES BETWEEN RELEASES> section below.
+
+ sub (*foo=) { # param specifier can be anything valid for query or body
+
+The upload match system functions exactly like a query/body match, except
+that the values returned (if any) are C<Web::Dispatch::Upload> objects.
+
+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
+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
+
+ $upload->is_upload # returns 1 on a valid upload, 0 on a non-upload field
+
+and to get the reason why such an object is not an upload, call
+
+ $upload->reason # returns a reason or '' on a valid upload.
+
+Other than these two methods, the upload object provides the same interface
+as L<Plack::Request::Upload> with the addition of a stringify to the temporary
+filename to make copying it somewhere else easier to handle.
+
=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!
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