X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FWeb%2FSimple.pm;h=70bb97fdb8dc7370a4b4a514d75ba59bb72a8419;hb=d57f3db440f7140beaebc64a77e34cbab14427e6;hp=d12a12a36de32d0455ac7682e529c1881a8b12e8;hpb=a5006b257baac6e3ab663736896938f1461dd663;p=catagits%2FWeb-Simple.git
diff --git a/lib/Web/Simple.pm b/lib/Web/Simple.pm
index d12a12a..70bb97f 100644
--- a/lib/Web/Simple.pm
+++ b/lib/Web/Simple.pm
@@ -6,7 +6,7 @@ use warnings::illegalproto ();
use Moo ();
use Web::Dispatch::Wrapper ();
-our $VERSION = '0.008';
+our $VERSION = '0.010';
sub import {
my ($class, $app_package) = @_;
@@ -34,36 +34,20 @@ sub _export_into {
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 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
#!/usr/bin/env perl
- use Web::Simple 'HelloWorld';
-
- {
- package HelloWorld;
+ package HelloWorld;
+ use Web::Simple
- sub dispatch_request {
- sub (GET) {
- [ 200, [ 'Content-type', 'text/plain' ], [ 'Hello world!' ] ]
- },
- sub () {
- [ 405, [ 'Content-type', 'text/plain' ], [ 'Method not allowed' ] ]
- }
+ sub dispatch_request {
+ sub (GET) {
+ [ 200, [ 'Content-type', 'text/plain' ], [ 'Hello world!' ] ]
+ },
+ sub () {
+ [ 405, [ 'Content-type', 'text/plain' ], [ 'Method not allowed' ] ]
}
}
@@ -73,9 +57,17 @@ If you save this file into your cgi-bin as C and then visit:
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 L,
-please connect to the irc.perl.org IRC network and join #web-simple.
+you'll get the "Hello world!" string output to your browser. At the same time
+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
+module, since this additionally makes it valid as a .psgi file, which can
+be extremely useful during development.
+
+For more complex examples and non-CGI deployment, see
+L. To get help with L, please connect to
+the irc.perl.org IRC network and join #web-simple.
=head1 DESCRIPTION
@@ -95,7 +87,7 @@ C based one:
This sets up your package (in this case "NameOfApplication" is your package)
so that it inherits from L and imports L,
-as well as installs a C constant for convenience, as well as some
+as well as installs a C constant for convenience, as well as some
other subroutines.
Importing L will automatically make your code use the C and
@@ -343,6 +335,15 @@ 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) {
@@ -367,9 +368,10 @@ Query and body parameters can be match via
sub (?) { # match URI query
sub (%) { # 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 -
@@ -429,9 +431,39 @@ 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
+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 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 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 object, which will C 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 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.
@@ -545,7 +577,7 @@ Thus if you receive a POST to '/some/url' and return a redispatch to
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.
+rather it is a much more efficient internal process.
=head1 CHANGES BETWEEN RELEASES
@@ -596,6 +628,8 @@ As of 0.005, you can instead write simply:
)
}
+=back
+
=head2 Changes since Antiquated Perl
=over 4
@@ -647,11 +681,31 @@ Gitweb is on http://git.shadowcat.co.uk/ and the clone URL is:
=head1 AUTHOR
-Matt S. Trout
+Matt S. Trout (mst)
=head1 CONTRIBUTORS
-None required yet. Maybe this module is perfect (hahahahaha ...).
+Devin Austin (dhoss)
+
+Arthur Axel 'fREW' Schmidt
+
+gregor herrmann (gregoa)
+
+John Napiorkowski (jnap)
+
+Josh McMichael
+
+Justin Hunter
+
+Kjetil Kjernsmo
+
+markie
+
+Christian Walde (Mithaldu)
+
+nperez
+
+Robin Edwards
=head1 COPYRIGHT