X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FWeb%2FSimple.pm;h=70bb97fdb8dc7370a4b4a514d75ba59bb72a8419;hb=d57f3db440f7140beaebc64a77e34cbab14427e6;hp=3f7c62b615f897d8da1d464acf44d3f1e04c8422;hpb=58fd1f7faee53804aed291d17a25553cd6630aec;p=catagits%2FWeb-Simple.git diff --git a/lib/Web/Simple.pm b/lib/Web/Simple.pm index 3f7c62b..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 @@ -109,7 +101,7 @@ 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. -When we inherit from L we also use , which is +When we inherit from L we also use L, which is the the equivalent of: { @@ -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