POD fix from gregoa of the debian team

[catagits/Web-Simple.git] / lib / Web / Simple.pm

diff --git a/lib/Web/Simple.pm b/lib/Web/Simple.pm
index 31fa56a..82f3e1c 100644 (file)
--- 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.009';
 
 sub import {
   my ($class, $app_package) = @_;
@@ -34,19 +34,6 @@ 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<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
 
@@ -376,9 +363,10 @@ Query and body parameters can be match via
   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 -
 
@@ -441,6 +429,36 @@ 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 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.
@@ -605,6 +623,8 @@ As of 0.005, you can instead write simply:
     )
   }
 
+=back
+
 =head2 Changes since Antiquated Perl
 
 =over 4
@@ -656,11 +676,11 @@ Gitweb is on http://git.shadowcat.co.uk/ and the clone URL is:
 
 =head1 AUTHOR
 
-Matt S. Trout <mst@shadowcat.co.uk>
+Matt S. Trout (mst) <mst@shadowcat.co.uk>
 
 =head1 CONTRIBUTORS
 
-None required yet. Maybe this module is perfect (hahahahaha ...).
+gregor herrmann (gregoa) <gregoa@debian.org>
 
 =head1 COPYRIGHT