You are viewing a plain text version of this content. The canonical link for it is here.
Posted to apreq-cvs@httpd.apache.org by jo...@apache.org on 2004/07/27 18:10:22 UTC

cvs commit: httpd-apreq-2/glue/perl/docs Request.pod Upload.pod

joes        2004/07/27 09:10:21

  Modified:    glue/perl/docs Request.pod Upload.pod
  Log:
  Minor doc fixes
  
  Revision  Changes    Path
  1.2       +138 -64   httpd-apreq-2/glue/perl/docs/Request.pod
  
  Index: Request.pod
  ===================================================================
  RCS file: /home/cvs/httpd-apreq-2/glue/perl/docs/Request.pod,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- Request.pod	22 Jul 2004 03:07:44 -0000	1.1
  +++ Request.pod	27 Jul 2004 16:10:21 -0000	1.2
  @@ -2,17 +2,30 @@
   
   Apache::Request - Methods for dealing with client request data
   
  +=for testing
  +    use Apache2;
  +    use Apache::Request;
  +    use Apache::Upload;
  +    use APR::Pool;
  +    ok 1;
  +
   =head1 SYNOPSIS
   
       use Apache::Request;
       my $req = Apache::Request->new($r);
   
  +
  +
  +
   =head1 DESCRIPTION
   
   C<Apache::Request> adds methods for parsing B<GET> requests and B<POST> 
   requests where I<Content-type> is one of I<application/x-www-form-urlencoded>
   or I<multipart/form-data>.
   
  +
  +
  +
   =head1 Apache::Request METHODS
   
   The interface is designed to mimic CGI.pm 's routines for parsing
  @@ -21,38 +34,44 @@
   =over 4
   
   =item * C<Apache::Request::new> takes an environment-specific
  -object as (second) argument.  Newer versions of CGI.pm also accept
  -this syntax within modperl.
  +        object as (second) argument.  Newer versions of CGI.pm also accept
  +        this syntax within modperl.
   
  -=item * The query parameters are stored in APR::Table derived objects,
  -and are therefore parsed using case-insensitive keys.
  +=item * The query parameters are stored in APR::Table derived objects, and
  +        are therefore retrieved from the table by using case-insensitive keys.
   
  -=item * The query string is always parsed first, even for POST requests.
  +=item * The query string is always parsed immediately, even for POST requests.
   
   =back
   
  -=head2 C<new>  
   
  -creates a new C<Apache::Request> object with an environment object $r:
  +
  +
  +=head2 new
  +
  +    Apache::Request->new($r, %args)
  +
  +Creates a new Apache::Request object.
   
       my $req = Apache::Request->new($r);
   
  -With mod_perl2, the environment object must be an C<Apache::RequestRec>
  -object.  All methods from the environment class are inherited.
  +With mod_perl2, the environment object $r must be an C<Apache::RequestRec>
  +object.  In that case, all methods from Apache::RequestRec are inherited.
   
  -The following attributes are optional:
  +The following args are optional:
   
   =over 4
   
  -=item C<POST_MAX>, C<MAX_BODY>
  +=item * C<POST_MAX>, C<MAX_BODY>
   
   Limit the size of POST data (in bytes).
   
  -=item C<DISABLE_UPLOADS>
  +=item * C<DISABLE_UPLOADS>
   
   Disable file uploads.
   
  -=item C<TEMP_DIR>
  +
  +=item * C<TEMP_DIR>
   
   Sets the directory where upload files are spooled.  On a *nix-like
   that supports I<link(2)>, the TEMP_DIR should be located on the same
  @@ -65,13 +84,13 @@
   
   For more details on C<link>, see the L<Apache::Upload> manpage.
   
  -=item C<HOOK_DATA>
  +=item * C<HOOK_DATA>
   
   Extra configuration info passed as the fourth argument 
   to an upload hook.  See the description for the next item, 
   C<UPLOAD_HOOK>.
   
  -=item C<UPLOAD_HOOK>
  +=item * C<UPLOAD_HOOK>
   
   Sets up a callback to run whenever file upload data is read. This
   can be used to provide an upload progress meter during file uploads.
  @@ -91,7 +110,11 @@
   =back
   
   
  -=head2 C<instance($r)> [DEPRECATED]
  +
  +
  +=head2 instance
  +
  +    Apache::Request->instance($r)
   
   The default (and only) behavior of I<Apache::Request> is to intelligently
   cache B<POST> data for the duration of the request.  Thus there is no longer
  @@ -102,7 +125,13 @@
   However an C<instance()> method is aliased to C<new()> in this release
   to ease the pain of porting from 1.X to 2.X.
   
  -=head2 C<param([$name])>
  +
  +
  +
  +=head2 param
  +
  +    $req->param()
  +    $req->param($name)
   
   Get the request parameters (using case-insensitive keys) by
   mimicing the OO interface of C<CGI::param>.
  @@ -145,10 +174,9 @@
   libapreq2 applications.
   
   
  -XXX  Need to document all Apache::*::Error classes  XXX
   
   
  -=head2 C<parms>, C<params> [DEPRECATED]
  +=head2 parms, params
   
   The functionality of these functions is assumed by C<param>,
   so they are no longer necessary.  Aliases to C<param> are
  @@ -156,7 +184,12 @@
   however they may be removed from a future release.
   
   
  -=head2 C<args([$name])>
  +
  +
  +=head2 args
  +
  +    $req->args()
  +    $req->args($name)
   
   Returns an I<Apache::Request::Table> object containing the query-string 
   parameters of the I<Apache::Request> object.
  @@ -175,7 +208,10 @@
   will be noticed by all libapreq2 applications during this request.
   
   
  -=head2 C<body([$name])>
  +=head2 body
  +
  +    $req->body()
  +    $req->body($name)
   
   Returns an I<Apache::Request::Table> object containing the POST data 
   parameters of the I<Apache::Request> object.
  @@ -194,11 +230,16 @@
   will be noticed by all libapreq2 applications during this request.
   
   
  -=head2 C<upload([$name])> (requires Apache::Upload)
   
  -With no arguments, this returns an I<Apache::Upload::Table> object in 
  -scalar context, or the names of all I<Apache::Upload> objects in
  -list context.
  +
  +=head2 upload
  +
  +    $req->upload()
  +    $req->upload($name)
  +
  +Requires C<Apache::Upload>.  With no arguments, this method
  +returns an I<Apache::Upload::Table> object in scalar context, 
  +or the names of all I<Apache::Upload> objects in list context.
   
   An optional name parameter can be passed to return the I<Apache::Upload>
   object associated with the given name:
  @@ -211,24 +252,42 @@
   data, and will not be seen by other libapreq2 applications.
   
   
  -=head2 C<args_status()>
   
  -Reports the final I<APR> status code of the query-string parser.
  +
  +=head2 args_status
  +
  +    $req->args_status()
  +    $req->args_status($set)
  +
  +Get/set the I<APR> status code of the query-string parser.
   APR_SUCCESS on success, error otherwise.
   
  -=head2 C<body_status()>
  +
  +
  +
  +=head2 body_status
  +
  +    $req->body_status()
   
   Reports the current I<APR> status code of the POST data parser.
   APR_SUCCESS when parser has completed, APR_INCOMPLETE if parser
   has more data to parse, error otherwise.
   
  -=head2 C<param_status()>
  +
  +
  +
  +=head2 param_status
  +
  +    $req->param_status()
   
   In scalar context, this returns C<args_status> if there was
   an error during the query-string parse, otherwise this returns
   C<body_status>.  In list context this returns the list 
   C<(args_status, body_status)>.
   
  +
  +
  +
   =head1 SUBCLASSING Apache::Request
   
   If the instances of your subclass are hash references then you can actually
  @@ -246,7 +305,9 @@
   	}
   
   
  -=head1 PORTING from 1.X to 2.X
  +
  +
  +=head1 PORTING from 1.X
   
   This is the complete list of changes to existing methods 
   from Apache::Request 1.X.  These issues need to be 
  @@ -254,52 +315,65 @@
   
   =over 4
   
  -=item Apache::Upload is now a separate module.  Applications
  -      requiring the upload API must C<use Apache::Upload> in 2.X.
  -      This is easily addressed by preloading the modules during 
  -      server startup.
  -
  -=item You must use the C<Apache::Request::Table> API via 
  -      C<< scalar $req->args >> or C<< scalar $req->body >> 
  -      to assign new parameters to the request.  You may 
  -      no longer use the two-argument method calls; e.g.
  -
  -        $req->param("foo" => "bar"); # NO: usage error in 2.X
  -        $req->args->{foo} = "bar";   # OK: assign to args table
  -        $req->body->add(foo => "bar");  # OK: add to body table
  -
  -        $req->param->add(foo => "bar"); # NO: this is an expensive noop, because
  -                                        # the param table is generated
  -                                        # by overlaying $req->args and $req->body.
  -
  -        my $params = $req->param;
  -        $params->set(foo => "bar"); # OK: sets "foo" entry in $params, which is a local
  -                                    # (args + body) table. Neither $req->args, $req->body,
  -                                    # nor future calls to $req->param, are affected by 
  -                                    # mods to $params.
  +=item * Apache::Upload is now a separate module.  Applications
  +        requiring the upload API must C<use Apache::Upload> in 2.X.
  +        This is easily addressed by preloading the modules during 
  +        server startup.
  +
  +=item * You must use the C<Apache::Request::Table> API via 
  +        C<< scalar $req->args >> or C<< scalar $req->body >> 
  +        to assign new parameters to the request.  You may 
  +        no longer use the two-argument method calls; e.g.
  +
  +          $req->param("foo" => "bar"); # NO: usage error in 2.X
  +          $req->args->{foo} = "bar";   # OK: assign to args table
  +          $req->body->add(foo => "bar");  # OK: add to body table
  +
  +          $req->param->add(foo => "bar"); # NO: this is an expensive noop,
  +                                          # because the param table is
  +                                          # generated by overlaying $req->args
  +                                          # and $req->body.
  +
  +          my $params = $req->param;
  +          $params->set(foo => "bar"); # OK: sets "foo" entry in $params, which
  +                                      # is a local (args + body) table. Neither
  +                                      # $req->args, $req->body, nor future calls
  +                                      # to $req->param, are affected by mods to
  +                                      # $params.
   
   
  -=item C<instance()> is now identical to C<new()>, and is now deprecated.  It 
  -      may be removed from a future 2.X release.
  +=item * C<instance()> is now identical to C<new()>, and is now deprecated.  It 
  +        may be removed from a future 2.X release.
   
  -=item C<param> includes the functionality of C<parms()> and C<params()>, so they
  -      are now deprecated and may be removed from a future 2.X release.
  +=item * C<param> includes the functionality of C<parms()> and C<params()>, so
  +        they are now deprecated and may be removed from a future 2.X release.
   
   =back
   
   
  +
  +
   =head1 SEE ALSO
   
  -L<Apache::Cookie>, L<Apache::Upload>, L<APR::Table>
  +L<Apache::Cookie>, L<Apache::Upload>,
  +L<Apache::Request::Table>, L<Apache::Request::Error>
   
  -=head1 CREDITS
   
  -This interface is based on the original pure Perl version by Lincoln Stein.
   
  -=head1 MISSING DOCS
   
  -$req->config, Apache::Request::Table
  +=head1 COPYRIGHT
   
  -=for testing
  -ok 1;
  +  Copyright 2003-2004  The Apache Software Foundation
  +
  +  Licensed under the Apache License, Version 2.0 (the "License");
  +  you may not use this file except in compliance with the License.
  +  You may obtain a copy of the License at
  +
  +      http://www.apache.org/licenses/LICENSE-2.0
  +
  +  Unless required by applicable law or agreed to in writing, software
  +  distributed under the License is distributed on an "AS IS" BASIS,
  +  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  +  See the License for the specific language governing permissions and
  +  limitations under the License.
   
  
  
  
  1.5       +17 -4     httpd-apreq-2/glue/perl/docs/Upload.pod
  
  Index: Upload.pod
  ===================================================================
  RCS file: /home/cvs/httpd-apreq-2/glue/perl/docs/Upload.pod,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- Upload.pod	26 Jul 2004 21:08:04 -0000	1.4
  +++ Upload.pod	27 Jul 2004 16:10:21 -0000	1.5
  @@ -13,7 +13,7 @@
       eval { POSIX::close(0); $req->parse };
       $req->body->add($u);
       $data = do { local (@ARGV, $/) = __FILE__; <> };
  -
  +    ok length $data == -s __FILE__;
   
   
   
  @@ -32,6 +32,7 @@
       $upload->slurp($slurp_data);
   
       read $upload->fh, $fh_data, $size;
  +    ok $slurp_data eq $fh_data;
   
       $io = $upload->io;
       print while <$io>;
  @@ -239,9 +240,15 @@
   Reads the full contents of a file upload into the scalar argument.
   The return value is the length of the file.
   
  +=for example begin
  +
  +    my $size = $upload->slurp($contents);
  +
  +=for example end
  +
   =for example_testing
  -   is $upload->slurp($contents), -s __FILE__;
  -   is $contents, $data;
  +    is $size, length $contents;
  +    is $contents, $data;
   
   
   
  @@ -252,8 +259,14 @@
   
   Provides the name of the spool file.
   
  +=for example begin
  +
  +    my $tempname = $upload->tempname;
  +
  +=for example end
  +
   =for example_testing
  -    like $upload->tempname, qr/apreq.{6}$/;
  +    like $tempname, qr/apreq.{6}$/;