From: Christian Hansen <chansen@cpan.org>
Date: Fri, 21 Oct 2005 11:05:09 +0000 (+0000)
Subject: Added docs
X-Git-Tag: v1.0~44
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=2d51e42f8d035d42ccc9df4239b882e5bd8a0b59;p=catagits%2FHTTP-Request-AsCGI.git

Added docs
---

diff --git a/Changes b/Changes
new file mode 100644
index 0000000..3dc7261
--- /dev/null
+++ b/Changes
@@ -0,0 +1,4 @@
+This file documents the revision history for Perl extension HTTP::Request::AsCGI.
+
+0.01  2005-10-21 00:00:00 2005
+        - first release
diff --git a/MANIFEST b/MANIFEST
index 7a46449..f1ce85a 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -1,10 +1,12 @@
-lib/HTTP/Request/AsCGI.pm
+Changes
 examples/daemon.pl
 examples/mechanize.pl
 examples/synopsis.pl
+lib/HTTP/Request/AsCGI.pm
+Makefile.PL
+MANIFEST                     This list of files
+META.yml                     Module meta-data (added by MakeMaker)
+README
 t/01use.t
 t/04io.t
 t/05env.t
-Makefile.PL
-MANIFEST			       This list of files
-META.yml                   Module meta-data (added by MakeMaker)
diff --git a/META.yml b/META.yml
index 580d2b1..81b7d32 100644
--- a/META.yml
+++ b/META.yml
@@ -7,8 +7,9 @@ installdirs:  site
 requires:
     Carp:                          0
     Class::Accessor:               0
-    File::Temp:                    0.14
-    IO::Handle:                    0
+    HTTP::Request:                 0
+    HTTP::Response:                0
+    IO::File:                      0
 
 distribution_type: module
 generated_by: ExtUtils::MakeMaker version 6.17
diff --git a/Makefile.PL b/Makefile.PL
index b91523b..7d0fbb6 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -9,6 +9,7 @@ WriteMakefile(
         Carp             => 0,
         Class::Accessor  => 0,
         HTTP::Request    => 0,
+        HTTP::Response   => 0,
         IO::File         => 0
     }
 );
diff --git a/README b/README
new file mode 100644
index 0000000..2e3ad7d
--- /dev/null
+++ b/README
@@ -0,0 +1,81 @@
+NAME
+    HTTP::Request::AsCGI - Setup a CGI enviroment from a HTTP::Request
+
+SYNOPSIS
+        use CGI;
+        use HTTP::Request;
+        use HTTP::Request::AsCGI;
+    
+        my $request = HTTP::Request->new( GET => 'http://www.host.com/' );
+        my $stdout;
+    
+        {
+            my $c = HTTP::Request::AsCGI->new($request)->setup;
+            my $q = CGI->new;
+        
+            print $q->header,
+                  $q->start_html('Hello World'),
+                  $q->h1('Hello World'),
+                  $q->end_html;
+        
+            $stdout = $c->stdout;
+        
+            # enviroment and descriptors will automatically be restored 
+            # when $c is destructed.
+        }
+    
+        while ( my $line = $stdout->getline ) {
+            print $line;
+        }
+    
+DESCRIPTION
+    Provides a convinient way of setting up an CGI enviroment from a
+    HTTP::Request.
+
+METHODS
+    new ( $request [, key => value ] )
+        Contructor, first argument must be a instance of HTTP::Request
+        followed by optional pairs of environment keys and values.
+
+    enviroment
+        Returns a hashref containing the environment that will be used in
+        setup. Changing the hashref after setup has been called will have no
+        effect.
+
+    setup
+        Setups the environment and descriptors.
+
+    restore
+        Restores the enviroment and descriptors. Can only be called after
+        setup.
+
+    request
+        Returns the request given to constructor.
+
+    response
+        Returns a HTTP::Response. Can only be called after restore.
+
+    stdin
+        Accessor for handle that will be used for STDIN, must be a real
+        seekable handle with an file descriptor. Defaults to a tempoary
+        IO::File instance.
+
+    stdout
+        Accessor for handle that will be used for STDOUT, must be a real
+        seekable handle with an file descriptor. Defaults to a tempoary
+        IO::File instance.
+
+    stderr
+        Accessor for handle that will be used for STDERR, must be a real
+        seekable handle with an file descriptor.
+
+THANKS TO
+    Thomas L. Shinnick for his valuable win32 testing.
+
+AUTHOR
+    Christian Hansen, "ch@ngmedia.com"
+
+LICENSE
+    This library is free software. You can redistribute it and/or modify it
+    under the same terms as perl itself.
+
diff --git a/examples/mechanize.pl b/examples/mechanize.pl
index 2026cf7..d74f2df 100644
--- a/examples/mechanize.pl
+++ b/examples/mechanize.pl
@@ -23,7 +23,9 @@ sub cgi {
 sub _make_request {
     my ( $self, $request ) = @_;
 
-    $self->cookie_jar->add_cookie_header($request) if $self->cookie_jar;
+    if ( $self->cookie_jar ) {
+        $self->cookie_jar->add_cookie_header($request);
+    }
 
     my $c = HTTP::Request::AsCGI->new($request)->setup;
 
@@ -37,12 +39,16 @@ sub _make_request {
         $response->content( $response->error_as_HTML );
     }
     else {
-        $response = $c->restore->response;   
+        $response = $c->restore->response;
     }
 
     $response->header( 'Content-Base', $request->uri );
     $response->request($request);
-    $self->cookie_jar->extract_cookies($response) if $self->cookie_jar;
+
+    if ( $self->cookie_jar ) {
+        $self->cookie_jar->extract_cookies($response);
+    }
+
     return $response;
 }
 
diff --git a/lib/HTTP/Request/AsCGI.pm b/lib/HTTP/Request/AsCGI.pm
index e22f275..43ffaab 100644
--- a/lib/HTTP/Request/AsCGI.pm
+++ b/lib/HTTP/Request/AsCGI.pm
@@ -16,6 +16,10 @@ our $VERSION = 0.1;
 sub new {
     my $class   = shift;
     my $request = shift;
+    
+    unless ( @_ % 2 == 0 && eval { $request->isa('HTTP::Request') } ) {
+        croak(qq/usage: $class->new( \$request [, key => value] )/);
+    }
 
     my $self = {
         request  => $request,
@@ -274,7 +278,8 @@ HTTP::Request::AsCGI - Setup a CGI enviroment from a HTTP::Request
         
         $stdout = $c->stdout;
         
-        # enviroment and descriptors will automatically be restored when $c is destructed.
+        # enviroment and descriptors will automatically be restored 
+        # when $c is destructed.
     }
     
     while ( my $line = $stdout->getline ) {
@@ -283,33 +288,56 @@ HTTP::Request::AsCGI - Setup a CGI enviroment from a HTTP::Request
     
 =head1 DESCRIPTION
 
+Provides a convinient way of setting up an CGI enviroment from a HTTP::Request.
+
 =head1 METHODS
 
 =over 4 
 
-=item new
+=item new ( $request [, key => value ] )
+
+Contructor, first argument must be a instance of HTTP::Request
+followed by optional pairs of environment keys and values.
 
 =item enviroment
 
+Returns a hashref containing the environment that will be used in setup. 
+Changing the hashref after setup has been called will have no effect.
+
 =item setup
 
+Setups the environment and descriptors.
+
 =item restore
 
+Restores the enviroment and descriptors. Can only be called after setup.
+
 =item request
 
+Returns the request given to constructor.
+
 =item response
 
+Returns a HTTP::Response. Can only be called after restore.
+
 =item stdin
 
+Accessor for handle that will be used for STDIN, must be a real seekable
+handle with an file descriptor. Defaults to a tempoary IO::File instance.
+
 =item stdout
 
+Accessor for handle that will be used for STDOUT, must be a real seekable
+handle with an file descriptor. Defaults to a tempoary IO::File instance.
+
 =item stderr
 
-=back
+Accessor for handle that will be used for STDERR, must be a real seekable
+handle with an file descriptor.
 
-=head1 BUGS
+=back
 
-=item THANKS TO
+=head1 THANKS TO
 
 Thomas L. Shinnick for his valuable win32 testing.