[libhttp-entity-parser-perl] 04/11: pod

[gregor herrmann]

This is an automated email from the git hooks/post-receive script.

gregoa pushed a commit to tag 0.01
in repository libhttp-entity-parser-perl.

commit 5ea58c6f48aabfa45245a540989b4e55a8e2fc6a
Author: Masahiro Nagano <kazeburo at gmail.com>
Date:   Wed Feb 5 03:21:51 2014 +0900

    pod
---
 README.md                 |  94 +++++++++++++++++++++++++++++++++++++++-
 lib/HTTP/Entity/Parser.pm | 107 +++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 197 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 912fb88..7b9fb76 100644
--- a/README.md
+++ b/README.md
@@ -19,10 +19,100 @@ HTTP::Entity::Parser - PSGI compliant HTTP Entity Parser
 
 # DESCRIPTION
 
-HTTP::Entity::Parser is PSGI compliant HTTP Entity parser. It also have compatibility with [HTTP::Body](http://search.cpan.org/perldoc?HTTP::Body)
-HTTP::Entity::Parser reads HTTP entity from \`psgi.input\` and parse it.
+HTTP::Entity::Parser is PSGI compliant HTTP Entity parser. This module also has compatibility 
+with [HTTP::Body](http://search.cpan.org/perldoc?HTTP::Body). Unlike HTTP::Body, HTTP::Entity::Parser reads HTTP entity from 
+PSGI's env `$env-`{'psgi.input'}> and parse it.
 This module support application/x-www-form-urlencoded, multipart/form-data and application/json.
 
+
+
+# METHODS
+
+- new()
+
+    Create the instance.
+
+- register($content\_type:String, $class:String)
+
+    Register parser class.
+
+        $parser->register('application/x-www-form-urlencoded','HTTP::Entity::Parser::UrlEncoded');
+        $parser->register('multipart/form-data','HTTP::Entity::Parser::MultiPart');
+        $parser->register('application/json','HTTP::Entity::Parser::JSON');
+
+    If the request content\_type match registered type, HTTP::Entity::Parser uses registered 
+    parser class. If content\_type does not match any registered type, HTTP::Entity::Parser::OctetStream is used.
+
+- parse($env:HashRef)
+
+    parse HTTP entity from PSGI's env.
+
+        my ( $params:ArrayRef, $uploads:ArrayRef) = $parser->parse($env);
+
+    `$param` is key-value pair list.
+
+        my ( $params, $uploads) = $parser->parse($env);
+        my $body_parameters = Hash::MultiValue->new(@$params);
+
+    `$uploads` is ArrayRef of HashRef.
+
+        my ( $params, $uploads) = $parser->parse($env);
+        warn Dumper($uploads->[0]);
+        {
+            "name" => "upload", #field name
+            "headeres" => [
+                "Content-Type" => "application/octet-stream",
+                "Content-Disposition" => "form-data; name=\"upload\"; filename=\"hello.pl\""           
+            ],
+            "size" => 78, #size of upload content
+            "filename" => "hello.png", #original filename in the client
+            "tempname" => "/tmp/XXXXX", # path to the temporary file where uploaded file is saved
+        }
+
+    use with Plack::Request::Upload
+
+        my ( $params, $uploads) = $parser->parse($env);
+        my $upload = Hash::MultiValue->new();
+        for my $obj ( @$uploads ) {
+            my %copy = %$obj;
+            $copy{headers} = HTTP::Headers->new(%{$obj->{headers}});
+            $upload->add($$copy->{name}, Plack::Request::Upload->new(%copy));
+        }
+
+# PARSERS
+
+- OctetStream
+
+    Default parser, This parser does not parse entity, always return empty list. 
+
+- UrlEncoded
+
+    For `application/x-www-form-urlencoded`. It is used for HTTP POST without file upload
+
+- MultiPart
+
+    For `multipart/form-data`. It is used for HTTP POST contains file upload.
+
+    MultiPart parser use [HTTP::MultiPartParser](http://search.cpan.org/perldoc?HTTP::MultiPartParser).
+
+- JSON
+
+    For `application/json`. This parser decode JSON body automatically. 
+
+    It is convenient to use with Ajax form.
+
+# WHAT'S DIFFERENT FROM HTTP::Body
+
+HTTP::Entity::Parser accept PSGI's env and read body from it.
+
+HTTP::Entity::Parser is able to choose parsers by the instance, HTTP::Body requires to modify global variables.
+
+# SEE ALSO
+
+- [HTTP::Body](http://search.cpan.org/perldoc?HTTP::Body)
+- [HTTP::MultiPartParser](http://search.cpan.org/perldoc?HTTP::MultiPartParser).
+- [Plack::Request](http://search.cpan.org/perldoc?Plack::Request)
+
 # LICENSE
 
 Copyright (C) Masahiro Nagano.
diff --git a/lib/HTTP/Entity/Parser.pm b/lib/HTTP/Entity/Parser.pm
index befa094..3e111da 100644
--- a/lib/HTTP/Entity/Parser.pm
+++ b/lib/HTTP/Entity/Parser.pm
@@ -132,10 +132,113 @@ HTTP::Entity::Parser - PSGI compliant HTTP Entity Parser
 
 =head1 DESCRIPTION
 
-HTTP::Entity::Parser is PSGI compliant HTTP Entity parser. It also have compatibility with L<HTTP::Body>
-HTTP::Entity::Parser reads HTTP entity from `psgi.input` and parse it.
+HTTP::Entity::Parser is PSGI compliant HTTP Entity parser. This module also has compatibility 
+with L<HTTP::Body>. Unlike HTTP::Body, HTTP::Entity::Parser reads HTTP entity from 
+PSGI's env C<$env->{'psgi.input'}> and parse it.
 This module support application/x-www-form-urlencoded, multipart/form-data and application/json.
 
+
+=head1 METHODS
+
+=over 4
+
+=item new()
+
+Create the instance.
+
+=item register($content_type:String, $class:String)
+
+Register parser class.
+
+  $parser->register('application/x-www-form-urlencoded','HTTP::Entity::Parser::UrlEncoded');
+  $parser->register('multipart/form-data','HTTP::Entity::Parser::MultiPart');
+  $parser->register('application/json','HTTP::Entity::Parser::JSON');
+
+If the request content_type match registered type, HTTP::Entity::Parser uses registered 
+parser class. If content_type does not match any registered type, HTTP::Entity::Parser::OctetStream is used.
+
+=item parse($env:HashRef)
+
+parse HTTP entity from PSGI's env.
+
+  my ( $params:ArrayRef, $uploads:ArrayRef) = $parser->parse($env);
+
+C<$param> is key-value pair list.
+
+   my ( $params, $uploads) = $parser->parse($env);
+   my $body_parameters = Hash::MultiValue->new(@$params);
+
+C<$uploads> is ArrayRef of HashRef.
+
+   my ( $params, $uploads) = $parser->parse($env);
+   warn Dumper($uploads->[0]);
+   {
+       "name" => "upload", #field name
+       "headeres" => [
+           "Content-Type" => "application/octet-stream",
+           "Content-Disposition" => "form-data; name=\"upload\"; filename=\"hello.pl\""           
+       ],
+       "size" => 78, #size of upload content
+       "filename" => "hello.png", #original filename in the client
+       "tempname" => "/tmp/XXXXX", # path to the temporary file where uploaded file is saved
+   }
+
+use with Plack::Request::Upload
+
+   my ( $params, $uploads) = $parser->parse($env);
+   my $upload = Hash::MultiValue->new();
+   for my $obj ( @$uploads ) {
+       my %copy = %$obj;
+       $copy{headers} = HTTP::Headers->new(%{$obj->{headers}});
+       $upload->add($$copy->{name}, Plack::Request::Upload->new(%copy));
+   }
+
+=back
+
+=head1 PARSERS
+
+=over 4
+
+=item OctetStream
+
+Default parser, This parser does not parse entity, always return empty list. 
+
+=item UrlEncoded
+
+For C<application/x-www-form-urlencoded>. It is used for HTTP POST without file upload
+
+=item MultiPart
+
+For C<multipart/form-data>. It is used for HTTP POST contains file upload.
+
+MultiPart parser use L<HTTP::MultiPartParser>.
+
+=item JSON
+
+For C<application/json>. This parser decode JSON body automatically. 
+
+It is convenient to use with Ajax form.
+
+=back
+
+=head1 WHAT'S DIFFERENT FROM HTTP::Body
+
+HTTP::Entity::Parser accept PSGI's env and read body from it.
+
+HTTP::Entity::Parser is able to choose parsers by the instance, HTTP::Body requires to modify global variables.
+
+=head1 SEE ALSO
+
+=over 4
+
+=item L<HTTP::Body>
+
+=item L<HTTP::MultiPartParser>.
+
+=item L<Plack::Request>
+
+=back
+
 =head1 LICENSE
 
 Copyright (C) Masahiro Nagano.

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libhttp-entity-parser-perl.git