Author: joes
Date: Sat Apr 23 12:50:01 2005
New Revision: 164415
URL: http://svn.apache.org/viewcvs?rev=164415&view=rev
Log:
Move perl docs to their corresponding perl modules.
Modified:
httpd/apreq/trunk/glue/perl/Makefile.PL
httpd/apreq/trunk/glue/perl/lib/Apache2/Cookie.pm
httpd/apreq/trunk/glue/perl/lib/Apache2/Request.pm
httpd/apreq/trunk/glue/perl/lib/Apache2/Upload.pm
Modified: httpd/apreq/trunk/glue/perl/Makefile.PL
URL:
http://svn.apache.org/viewcvs/httpd/apreq/trunk/glue/perl/Makefile.PL?rev=164415&r1=164414&r2=164415&view=diff
==============================================================================
--- httpd/apreq/trunk/glue/perl/Makefile.PL (original)
+++ httpd/apreq/trunk/glue/perl/Makefile.PL Sat Apr 23 12:50:01 2005
@@ -180,6 +180,8 @@
my @lines;
my $dfs = '$(DIRFILESEP)';
+ return; # XXX FIXME when APR::Request gets documentation
+
foreach my $file (@_) {
my @dirs;
$file =~ /(\w+\.pod)$/ or next;
Modified: httpd/apreq/trunk/glue/perl/lib/Apache2/Cookie.pm
URL:
http://svn.apache.org/viewcvs/httpd/apreq/trunk/glue/perl/lib/Apache2/Cookie.pm?rev=164415&r1=164414&r2=164415&view=diff
==============================================================================
--- httpd/apreq/trunk/glue/perl/lib/Apache2/Cookie.pm (original)
+++ httpd/apreq/trunk/glue/perl/lib/Apache2/Cookie.pm Sat Apr 23 12:50:01 2005
@@ -114,3 +114,626 @@
}
1;
+
+__END__
+
+Apache::Cookie, Apache::Cookie::Jar - HTTP Cookies Class
+
+=for testing
+ use Apache::Cookie;
+ use APR::Pool;
+ # use $r instead of $p here, so doc examples reflect mp2 env, not CGI/test
env
+ $r = APR::Pool->new;
+ $j = Apache::Cookie::Jar->new($r);
+ $j->cookies->{foo} = Apache::Cookie->new($r, name => "foo", value => "1");
+ $j->cookies->add( Apache::Cookie->new($r, name => "bar", value => "2") );
+ # We must disable bake and bake2 in the api tests,
+ # since they write directly to fd 1 via apr_file_write().
+ *Apache::Cookie::bake = *Apache::Cookie::bake2 =
*Apache::Cookie::as_string;
+
+
+
+
+=head1 SYNOPSIS
+
+
+=for example begin
+
+ use Apache::Cookie;
+
+ $j = Apache::Cookie::Jar->new($r);
+ $c_in = $j->cookies("foo"); # get cookie from request headers
+
+ $c_out = Apache::Cookie->new($r,
+ -name => "mycookie",
+ -value => $c_in->name );
+
+ $c_out->path("/bar"); # set path to "/bar"
+ $c_out->bake; # send cookie in response headers
+
+=for example end
+
+=for example_testing
+ ok "foo bar" eq join " ", keys %{$j->cookies};
+ ok $c_out->as_string eq "mycookie=foo; path=/bar";
+ ok $c_in->value == 1;
+
+
+
+
+=head1 DESCRIPTION
+
+
+The 2.X Apache::Cookie module is based on the original 1.X versions, which
mimic
+the CGI::Cookie API. The current version of this module includes several
packages
+and methods which are patterned after Apache::Request, yet remain largely
+backwards-compatible with the original 1.X API (see the L<PORTING from 1.X>
section
+below for known issues).
+
+This manpage documents the Apache::Cookie and Apache::Cookie::Jar packages.
+Apache::Cookie::Error, Apache::Cookie::Jar::Error and Apache::Cookie::Table
+are also provided by this module but documented elsewhere (related manpages
+listed in L<SEE ALSO>).
+
+
+
+
+=head1 Apache::Cookie::Jar
+
+This class collects Apache::Cookie objects into a lookup table. It plays
+the same role for accessing the incoming cookies as Apache::Request does for
+accessing the incoming params and file uploads.
+
+
+
+
+=head2 new
+
+ Apache::Cookie::Jar->new($env, %args)
+
+Class method that retrieves the parsed cookie jar from the current
+environment. An optional VALUE_CLASS => $class argument instructs
+the jar to bless any returned cookies into $class instead
+of Apache::Cookie. This feature is meant to be useful in situations
+where C<Apache::Cookie::thaw()> is unable to correctly interpret an incoming
+cookie's serialization. Users can simply override C<thaw> in an
+application-specific subclass and pass that subclass's name as the
+VALUE_CLASS argument:
+
+=for example begin
+
+ {
+ package FOO;
+ @ISA= 'Apache::Cookie';
+ }
+ my $jar = Apache::Cookie::Jar->new($r, VALUE_CLASS => "FOO");
+ ok $jar->cookies("foo")->isa("FOO");
+ ok $jar->cookies->{bar}->isa("FOO");
+
+=for example end
+
+=for example_testing
+ ok $jar->isa("Apache::Cookie::Jar");
+ $jar->cookies->do(sub { ok $_[1]->isa("FOO"); });
+ map { ok $_->isa("FOO") } values %{$jar->cookies};
+
+
+
+
+=head2 cookies
+
+ $jar->cookies()
+ $jar->cookies($key)
+
+Retrieve cookies named $key with from the jar object. In scalar
+context the first such cookie is returned, and in list context the
+full list of such cookies are returned.
+
+If the $key argument is omitted, C<< scalar $jar->cookies() >> will
+return an Apache::Cookie::Table object containing all the cookies in
+the jar. Modifications to the this object will affect the jar's
+internal I<cookies> table in C<apreq_jar_t>, so their impact will
+be noticed by all libapreq2 applications during this request.
+
+In list context C<< $jar->cookies() >> returns the list of names
+for all the cookies in the jar. The order corresponds to the
+order in which the cookies appeared in the incoming "Cookie" header.
+
+This method will throw an Apache::Cookie::Jar::Error object into $@ if
+the returned value(s) may be unreliable. In particular, note that
+C<< scalar $jar->cookies("foo") >> will not croak if it can locate
+the a "foo" cookie within the jar's parsed cookie table, even if the
+cookie parser has failed (the cookies are parsed in the same order
+as they appeared in the "Cookie" header). In all other circumstances
+C<cookies> will croak if the parser failed to successfully parse the
+"Cookie" header.
+
+=for example begin
+
+ $c = Apache::Cookie->new($r, name => "foo", value => 3);
+ $j->cookies->add($c);
+
+ $cookie = $j->cookies("foo"); # first foo cookie
+ @cookies = $j->cookies("foo"); # all foo cookies
+ @names = $j->cookies(); # all cookie names
+
+=for example end
+
+=for example_testing
+ ok @cookies == 2;
+ is $_ -> name, "foo" for $cookie, @cookies;
+ ok $cookies[0]->value eq $cookie->value;
+ ok $cookies[0]->value == 1;
+ ok $cookies[1]->value == 3;
+ is "@names", "foo bar";
+
+
+
+
+=head2 status
+
+ $jar->status()
+ $jar->status($set)
+
+Get or set the I<APR> status code of the cookie parser:
+APR_SUCCESS on success, error otherwise.
+
+=for example begin
+
+ $j->status(-1);
+ ok $j->status == -1;
+ eval { @cookies = $j->cookies("foo") }; # croaks
+ ok [EMAIL PROTECTED]>isa("Apache::Cookie::Jar::Error");
+ $j->status(0);
+
+=for example end
+
+=for example_testing
+ ok $j->status == 0, '$j->status == 0';
+ @cookies = $j->cookies("foo");
+ ok @cookies == 2, '@cookies == 2';
+
+
+
+
+=head2 env
+
+ Apache::Cookie::Jar->env()
+ $jar->env()
+
+As a class method C<< Apache::Cookie::Jar->env >> returns
+the environment class associated with Apache::Cookie::Jar.
+As an object method, C<< $jar->env >> returns the environment
+object which first created the $jar (via C<new>).
+
+=for example begin
+
+ ok $j->env->isa(Apache::Cookie::Jar->env);
+
+=for example end
+
+=for example_testing
+ ok (Apache::Cookie::Jar->env eq "APR::Pool", 'env() isa APR::Pool');
+
+
+
+
+=head1 Apache::Cookie
+
+
+
+
+=head2 new
+
+ Apache::Cookie->new($env, %args)
+
+Just like CGI::Cookie::new, but requires an additional environment argument:
+
+=for example begin
+
+ $cookie = Apache::Cookie->new($r,
+ -name => 'foo',
+ -value => 'bar',
+ -expires => '+3M',
+ -domain => '.capricorn.com',
+ -path => '/cgi-bin/database',
+ -secure => 1
+ );
+
+=for example end
+
+=for example_testing
+ ok $cookie->name eq "foo", 'name eq "foo"';
+ ok $cookie->value eq "bar", 'value eq "bar"';
+ ok $cookie->domain eq ".capricorn.com", 'domain eq ".capricorn.com"';
+ ok $cookie->path eq "/cgi-bin/database",'path eq "/cgi-bin/database"';
+ ok $cookie->secure == 1, '$cookie->secure == 1';
+
+The C<-value> argument may be either an arrayref, a hashref, or
+a string. C<Apache::Cookie::freeze> encodes this argument into the
+cookie's raw value.
+
+
+
+
+=head2 freeze
+
+ Apache::Cookie->freeze($value)
+
+Helper function (for C<new>) that serializes a new cookie's value in a
+manner compatible with CGI::Cookie (and Apache::Cookie 1.X). This class
+method accepts an arrayref, hashref, or normal perl string in $value.
+
+=for example begin
+
+ $value = Apache::Cookie->freeze(["2+2", "=4"]);
+
+=for example end
+
+=for example_testing
+ ok $value eq "2%2b2&%3d4", '$value eq "2%2b2&%3d4"';
+
+
+
+
+=head2 thaw
+
+ Apache::Cookie->thaw($value)
+ $cookie->thaw()
+
+
+This is the helper method (for C<value>) responsible for decoding the
+raw value of a cookie. An optional argument $value may be used in
+place of the cookie's raw value. This method can also decode cookie
+values created using CGI::Cookie or Apache::Cookie 1.X.
+
+=for example begin
+
+ print $cookie->thaw; # prints "bar"
+ @values = Apache::Cookie->thaw($value); # ( "2+2", "=4" )
+
+=for example end
+
+=for example_testing
+ ok $_STDOUT_ eq "bar", '$_STDOUT_ eq "bar"';
+ ok @values == 2, '@values == 2';
+ ok $values[0] eq "2+2", '$values[0] eq "2+2"';
+ ok $values[1] eq "=4", '$values[1] eq "=4"';
+
+
+
+
+=head2 as_string
+
+ $cookie->as_string()
+
+Format the cookie object as a string. The quote-operator for Apache::Cookie
+is overloaded to run this method whenever a cookie appears in quotes.
+
+
+=for example begin
+
+ ok "$cookie" eq $cookie->as_string;
+
+=for example end
+
+=for example_testing
+ ok substr("$cookie", 0, 8) eq "foo=bar;";
+
+
+
+
+=head2 name
+
+ $cookie->name()
+
+Get the name of the cookie.
+
+=for example_testing
+ ok $cookie->name eq "foo";
+
+
+
+
+=head2 value
+
+ $cookie->value()
+
+Get the (unswizzled) value of the cookie:
+
+=for example begin
+
+ my $value = $cookie->value;
+ my @values = $cookie->value;
+
+=for example end
+
+=for example_testing
+ ok @values == 1, '@values == 1';
+ ok $value eq "bar", '$value eq "bar"';
+ ok $values[0] eq "bar", '$values[0] eq "bar"';
+
+Note: if the cookie's value was created using a C<freeze> method,
+one way to reconstitute the object is by subclassing
+Apache::Cookie with a package that provides the associated C<thaw> sub:
+
+=for example begin
+
+ {
+ package My::COOKIE;
+ @ISA = 'Apache::Cookie';
+ sub thaw { my $val = shift->raw_value; $val =~ tr/a-z/A-Z/; $val }
+ }
+
+ bless $cookie, "My::COOKIE";
+
+ ok $cookie->value eq "BAR";
+
+=for example end
+
+
+
+
+=head2 raw_value
+
+ $cookie->raw_value()
+
+Gets the raw (opaque) value string as it appears in the incoming
+"Cookie" header.
+
+=for example begin
+
+ ok $cookie->raw_value eq "bar";
+
+=for example end
+
+=for example_testing
+ # run the example, don't just compile it
+
+
+
+
+=head2 bake
+
+ $cookie->bake()
+
+Adds a I<Set-Cookie> header to the outgoing headers table.
+
+
+
+
+=head2 bake2
+
+ $cookie->bake2()
+
+Adds a I<Set-Cookie2> header to the outgoing headers table.
+
+
+
+
+
+
+=head2 domain
+
+ $cookie->domain()
+ $cookie->domain($set)
+
+Get or set the domain for the cookie:
+
+=for example begin
+
+ $domain = $cookie->domain;
+ $cookie->domain(".cp.net");
+
+=for example end
+
+=for example_testing
+ ok $domain eq ".capricorn.com";
+ ok $cookie->domain eq ".cp.net";
+
+
+
+
+=head2 path
+
+ $cookie->path()
+ $cookie->path($set)
+
+Get or set the path for the cookie:
+
+=for example begin
+
+ $path = $cookie->path;
+ $cookie->path("/");
+
+=for example end
+
+=for example_testing
+ ok $path eq "/cgi-bin/database";
+ ok $cookie->path eq "/";
+
+
+
+
+=head2 version
+
+ $cookie->version()
+ $cookie->version($set)
+
+Get or set the cookie version for this cookie.
+Netscape spec cookies have version = 0;
+RFC-compliant cookies have version = 1.
+
+=for example begin
+
+ ok $cookie->version == 0;
+ $cookie->version(1);
+ ok $cookie->version == 1;
+
+=for example end
+
+=for example_testing
+ # run the example tests
+
+
+
+
+=head2 expires
+
+ $cookie->expires()
+ $cookie->expires($set)
+
+Get or set the future expire time for the cookie. When
+assigning, the new value ($set) should match /^\+?(\d+)([YMDhms]?)$/
+$2 qualifies the number in $1 as representing "Y"ears, "M"onths,
+"D"ays, "h"ours, "m"inutes, or "s"econds (if the qualifier is
+omitted, the number is interpreted as representing seconds).
+As a special case, $set = "now" is equivalent to $set = "0".
+
+=for example begin
+
+ my $expires = $cookie->expires;
+ $cookie->expires("+3h"); # cookie is set to expire in 3 hours
+
+=for example end
+
+=for example_testing
+ ok $expires == 3 * 30 * 24 * 3600; # 3 months
+ ok $cookie->expires == 3 * 3600;
+
+
+
+
+=head2 secure
+
+ $cookie->secure()
+ $cookie->secure($set)
+
+Get or set the secure flag for the cookie:
+
+=for example begin
+
+ $cookie->secure(1);
+ $is_secure = $cookie->secure;
+ $cookie->secure(0);
+
+=for example end
+
+=for example_testing
+ ok $is_secure;
+ ok (not $cookie->secure);
+
+
+
+
+=head2 comment
+
+ $cookie->comment()
+ $cookie->comment($set)
+
+Get or set the comment field of an RFC (Version > 0) cookie.
+
+=for example begin
+
+ $cookie->comment("Never eat yellow snow");
+ print $cookie->comment;
+
+=for example end
+
+=for example_testing
+ ok $_STDOUT_ eq "Never eat yellow snow";
+
+
+
+
+=head2 commentURL
+
+ $cookie->commentURL()
+ $cookie->commentURL($set)
+
+Get or set the commentURL field of an RFC (Version > 0) cookie.
+
+=for example begin
+
+ $cookie->commentURL("http://localhost/cookie.policy";);
+ print $cookie->commentURL;
+
+=for example end
+
+=for example_testing
+ ok $_STDOUT_ eq "http://localhost/cookie.policy";;
+
+
+
+
+=head2 fetch
+
+ Apache::Cookie->fetch($r)
+
+Fetch and parse the incoming I<Cookie> header:
+
+=for example begin
+
+ my $cookies = Apache::Cookie->fetch($r); # Apache::Cookie::Table ref
+
+ my %cookies = Apache::Cookie->fetch($r);
+
+=for example end
+
+=for example_testing
+ ok "foobarfoo" eq join "", keys %$cookies;
+ ok 123 == join "", map $_->value, values %$cookies;
+ ok "barfoo" eq join "", sort keys %cookies; # %cookies lost original foo
cookie
+ ok 23 == join "", sort map $_->value, values %cookies;
+
+
+
+
+=head1 PORTING from 1.X
+
+Changes to the 1.X API:
+
+=over 4
+
+=item * C<Apache::Cookie::fetch> now expects an C<$r> object as (second)
+ argument, although this isn't necessary in mod_perl 2 if
+ C<Apache::RequestUtil> is loaded.
+
+=item * C<Apache::Cookie::parse> is gone.
+
+=item * C<Apache::Cookie::new> no longer encodes the supplied cookie name.
+
+=item * C<name()> and C<value()> no longer accept a "set" argument. In other
words,
+ neither a cookie's name, nor its value, may be modified. A new cookie
+ should be made instead.
+
+=back
+
+
+
+
+=head1 SEE ALSO
+
+L<Apache::Cookie::Table>, L<Apache::Cookie::Error>,
+L<Apache::Cookie::Jar::Error>, L<Apache::Request>,
+CGI::Cookie(3)
+
+
+
+
+=head1 COPYRIGHT
+
+ Copyright 2003-2005 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.
+
Modified: httpd/apreq/trunk/glue/perl/lib/Apache2/Request.pm
URL:
http://svn.apache.org/viewcvs/httpd/apreq/trunk/glue/perl/lib/Apache2/Request.pm?rev=164415&r1=164414&r2=164415&view=diff
==============================================================================
--- httpd/apreq/trunk/glue/perl/lib/Apache2/Request.pm (original)
+++ httpd/apreq/trunk/glue/perl/lib/Apache2/Request.pm Sat Apr 23 12:50:01 2005
@@ -31,3 +31,569 @@
}
1;
+
+__END__
+=head1 NAME
+
+Apache::Request - Methods for dealing with client request data
+
+
+=for testing
+ use Apache::Request;
+ use Apache::Upload;
+ use APR::Pool;
+ $r = APR::Pool->new;
+ $req = Apache::Request->new($r);
+ $u = Apache::Upload->new($r, name => "foo", file => __FILE__);
+ $req->body_status(0);
+ $req->parse;
+ $req->body->add($u);
+ $req->args->add(foo => 1);
+ $req->args->add(bar => 2);
+ $req->args->add(foo => 3);
+
+
+
+=head1 SYNOPSIS
+
+
+=for example begin
+
+ use Apache::Request;
+ $req = Apache::Request->new($r);
+ @foo = $req->param("foo");
+ $bar = $req->args("bar");
+
+=for example end
+
+=for example_testing
+ ok $req->isa("Apache::Request");
+ is "@foo", join " ", 1, 3, __FILE__;
+ is $bar, 2;
+
+
+
+
+=head1 DESCRIPTION
+
+The Apache::Request module provides methods for parsing GET and POST parameters
+encoded with either I<application/x-www-form-urlencoded> or
I<multipart/form-data>.
+Although Apache::Request provides a few new APIs for accessing the parsed data,
+it remains largely backwards-compatible with the original 1.X API. See the
+L<PORTING from 1.X> section below for a list of known issues.
+
+This manpage documents the Apache::Request package. Apache::Request::Table
+and Apache::Request::Error are also provided by this module, but are
+documented elsewhere. Please read the L<SEE ALSO> section below for a list
+of related manpages.
+
+
+
+
+=head1 Apache::Request
+
+The interface is designed to mimic the CGI.pm routines for parsing
+query parameters. The main differences are
+
+=over 4
+
+=item * C<Apache::Request::new> takes an environment-specific
+ object C<$r> 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 retrieved from the table by using case-insensitive keys.
+
+=item * The query string is always parsed immediately, even for POST requests.
+
+=back
+
+
+
+
+=head2 new
+
+ Apache::Request->new($r, %args)
+
+Creates a new Apache::Request object.
+
+
+=for example begin
+
+ my $req = Apache::Request->new($r, POST_MAX => "1M");
+
+
+=for example end
+
+=for example_testing
+ ok ref $req;
+ ok $req->isa("Apache::Request");
+
+
+With mod_perl2, the environment object $r must be an Apache::RequestRec
+object. In that case, all methods from Apache::RequestRec are inherited.
+In the (default) CGI environment, $r must be an APR::Pool object.
+
+The following args are optional:
+
+=over 4
+
+
+=item * C<POST_MAX>, C<MAX_BODY>
+
+Limit the size of POST data (in bytes).
+
+
+=item * C<DISABLE_UPLOADS>
+
+Disable file uploads.
+
+
+=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
+file system as the final destination file:
+
+=for example begin
+
+ use Apache::Upload;
+ my $req = Apache::Request->new($r, TEMP_DIR => "/home/httpd/tmp");
+ my $upload = $req->upload('file');
+ $upload->link("/home/user/myfile");
+
+=for example end
+
+For more details on C<link>, see L<Apache::Upload>.
+
+
+=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>
+
+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.
+Apache will automatically continue writing the original data to
+$upload->fh after the hook exits.
+
+=for example begin
+
+ my $transparent_hook = sub {
+ my ($upload, $data, $data_len, $hook_data) = @_;
+ warn "$hook_data: got $data_len bytes for " . $upload->name;
+ };
+
+ my $req = Apache::Request->new($r,
+ HOOK_DATA => "Note",
+ UPLOAD_HOOK => $transparent_hook,
+ );
+
+=for example end
+
+
+=back
+
+
+
+
+=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
+the need for a separate C<instance()> method as existed in I<Apache::Request>
+for Apache 1.3 - all B<POST> data is always available from each and every
+I<Apache::Request> object created during the request's lifetime.
+
+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 param
+
+ $req->param()
+ $req->param($name)
+
+Get the request parameters (using case-insensitive keys) by
+mimicing the OO interface of C<CGI::param>.
+
+
+=for example begin
+
+ # similar to CGI.pm
+
+ my $foo_value = $req->param('foo');
+ my @foo_values = $req->param('foo');
+ my @param_names = $req->param;
+
+ # the following differ slightly from CGI.pm
+
+ # returns ref to Apache::Request::Table object representing
+ # all (args + body) params
+ my $table = $req->param;
+ @table_keys = keys %$table;
+
+=for example end
+
+=for example_testing
+ is $foo_value, 1;
+ is "@foo_values", join " ", 1, 3, __FILE__;
+ is "@param_names", "foo bar";
+ is "@table_keys", "foo bar foo foo";
+
+
+In list context, or when invoked with no arguments as
+C<< $req->param() >>, C<param> induces libapreq2 to read
+and parse all remaining data in the request body.
+However, C<< scalar $req->param("foo") >> is lazy: libapreq2
+will only read and parse more data if
+
+ 1) no "foo" param appears in the query string arguments, AND
+ 2) no "foo" param appears in the previously parsed POST data.
+
+In this circumstance libapreq2 will read and parse additional
+blocks of the incoming request body until either
+
+ 1) it has found the the "foo" param, or
+ 2) parsing is completed.
+
+Observe that C<< scalar $req->param("foo") >> will not raise
+an exception if it can locate "foo" in the existing body or
+args tables, even if the query-string parser or the body parser
+has failed. In all other circumstances C<param> will throw an
+Apache::Request::Error object into $@ should either parser fail.
+
+=for example begin
+
+ $req->args_status(1); # set error state for query-string parser
+ ok $req->param_status == 1;
+
+ $foo = $req->param("foo");
+ ok $foo == 1;
+ eval { @foo = $req->param("foo") };
+ ok [EMAIL PROTECTED]>isa("Apache::Request::Error");
+ undef $@;
+ eval { my $not_found = $req->param("non-existent-param") };
+ ok [EMAIL PROTECTED]>isa("Apache::Request::Error");
+
+ $req->args_status(0); # reset query-string parser state to "success"
+
+=for example end
+
+=for example_testing
+ # run example
+
+
+Note: modifications to the C<< scalar $req->param() >> table only
+affect the returned table object (the underlying C apr_table_t is
+I<generated> from the parse data by apreq_params()). Modifications
+do not affect the actual request data, and will not be seen by other
+libapreq2 applications.
+
+
+
+
+=head2 parms, params
+
+The functionality of these functions is assumed by C<param>,
+so they are no longer necessary. Aliases to C<param> are
+provided in this release for backwards compatibility,
+however they are deprecated and may be removed from a future
+release.
+
+
+
+
+=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.
+
+=for example begin
+
+ my $args = $req->args;
+
+=for example end
+
+=for example_testing
+ my $n = 0;
+ while (($a, $b) = each %$args) {
+ is $a, (qw/foo bar foo/)[$n];
+ is $b, ++$n;
+ }
+
+An optional name parameter can be passed to return the query string
+parameter associated with the given name:
+
+=for example begin
+
+ my $foo_arg = $req->args("foo");
+
+=for example end
+
+=for example_testing
+ is $foo_arg, 1;
+
+More generally, C<args()> follows the same pattern as C<param()>
+with respect to its return values and argument list. The main difference
+is that modifications to the C<< scalar $req->args() >> table affect
+the underlying apr_table_t attribute in apreq_request_t, so their impact
+will be noticed by all libapreq2 applications during this request.
+
+
+
+
+=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.
+
+=for example begin
+
+ my $body = $req->body;
+
+=for example end
+
+=for example_testing
+ is join(" ", keys %$body), "foo";
+ is join(" ", values %$body), __FILE__;
+
+
+An optional name parameter can be passed to return the POST data
+parameter associated with the given name:
+
+=for example begin
+
+ my $foo_body = $req->body("foo");
+
+=for example end
+
+=for example_testing
+ is $foo_body, __FILE__;
+
+More generally, C<body()> follows the same pattern as C<param()>
+with respect to its return values and argument list. The main difference
+is that modifications to the C<< scalar $req->body() >> table affect
+the underlying apr_table_t attribute in apreq_request_t, so their impact
+will be noticed by all libapreq2 applications during this request.
+
+
+
+
+=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:
+
+ my $upload = $req->upload($name);
+
+More generally, C<upload()> follows the same pattern as C<param()>
+with respect to its return values and argument list. The main difference
+is that its returned values are Apache::Upload object refs, not
+simple scalars.
+
+Note: modifications to the C<< scalar $req->upload() >> table only
+affect the returned table object (the underlying C apr_table_t is
+I<generated> by apreq_uploads()). They do not affect the actual request
+data, and will not be seen by other libapreq2 applications.
+
+
+
+
+=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.
+
+=for testing
+ is $req->args_status, 0; # APR_SUCCESS
+
+
+
+
+=head2 body_status
+
+ $req->body_status()
+ $req->body_status($set)
+
+Get/set the current I<APR> status code of the parsed POST data.
+APR_SUCCESS when parser has completed, APR_INCOMPLETE if parser
+has more data to parse, APR_EINIT if no post data has been parsed,
+error otherwise.
+
+=for testing
+ is $req->body_status, 0; # APR_SUCCESS
+
+
+
+=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>, ie
+
+ $req->args_status || $req->body_status
+
+In list context C<param_status> returns the list
+C<(args_status, body_status)>.
+
+=for testing
+ is scalar($req->param_status),
+ $req->args_status || $req->body_status;
+ is join(" ", $req->param_status),
+ join(" ", $req->args_status, $req->body_status);
+
+
+
+
+=head2 parse
+
+ $req->parse()
+
+Forces the request to be parsed immediately. In void context,
+this will throw an Apache::Request::Error should the either the
+query-string or body parser fail. In all other contexts it will
+return the two parsers' combined I<APR> status code
+
+ $req->body_status || $req->args_status
+
+=for testing
+ is $req->parse, $req->body_status || $req->args_status;
+
+
+However C<parse> should be avoided in most normal situations. For example,
+in a mod_perl content handler it is more efficient to write
+
+ sub handler {
+ my $r = shift;
+ my $req = Apache::Request->new($r);
+ $r->discard_request_body; # efficiently parses the request body
+ my $parser_status = $req->body_status;
+
+ #...
+ }
+
+Calling C<< $r->discard_request_body >> outside the content handler
+is generally a mistake, so use C<< $req->parse >> there, but
+B<only as a last resort>. The Apache::Request API is B<designed>
+around a lazy-parsing scheme, so calling C<parse> should not
+affect the behavior of any other methods.
+
+
+
+
+=head1 SUBCLASSING Apache::Request
+
+If the instances of your subclass are hash references then you can actually
+inherit from Apache::Request as long as the Apache::Request object is stored in
+an attribute called "r" or "_r". (The Apache::Request class effectively does
the
+delegation for you automagically, as long as it knows where to find the
+Apache::Request object to delegate to.) For example:
+
+ package MySubClass;
+ use Apache::Request;
+ our @ISA = qw(Apache::Request);
+ sub new {
+ my($class, @args) = @_;
+ return bless { r => Apache::Request->new(@args) }, $class;
+ }
+
+
+
+
+=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
+addressed when porting 1.X apps to the new 2.X API.
+
+
+=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 * 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.
+
+=back
+
+
+
+
+=head1 SEE ALSO
+
+L<Apache::Request::Table>, L<Apache::Request::Error>, L<Apache::Upload>,
+L<Apache::Cookie>, APR::Table(3).
+
+
+
+
+=head1 COPYRIGHT
+
+ Copyright 2003-2005 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.
Modified: httpd/apreq/trunk/glue/perl/lib/Apache2/Upload.pm
URL:
http://svn.apache.org/viewcvs/httpd/apreq/trunk/glue/perl/lib/Apache2/Upload.pm?rev=164415&r1=164414&r2=164415&view=diff
==============================================================================
--- httpd/apreq/trunk/glue/perl/lib/Apache2/Upload.pm (original)
+++ httpd/apreq/trunk/glue/perl/lib/Apache2/Upload.pm Sat Apr 23 12:50:01 2005
@@ -24,3 +24,390 @@
*bb = *APR::Request::Param::upload;
1;
+
+__END__
+
+=head1 NAME
+
+Apache::Upload - Methods for dealing with file uploads.
+
+=for testing
+ use APR::Pool;
+ use Apache::Upload;
+ $r = APR::Pool->new;
+ $req = Apache::Request->new($r);
+ $u = Apache::Upload->new($r, name => "foo", file => __FILE__);
+ $req->body_status(0);
+ $req->parse;
+ $req->body->add(foo => "bar"); # dummy param with same name as upload
+ $req->body->add($u);
+ open(my $fh, __FILE__) or die $!;
+ binmode $fh;
+ {
+ local $/;
+ $data = <$fh>;
+ }
+ close $fh;
+ ok length $data == -s __FILE__;
+ $data =~ s{\r}{}g;
+
+
+
+=head1 SYNOPSIS
+
+
+=for example begin
+
+ use Apache::Upload;
+
+ $req = Apache::Request->new($r);
+ $upload = $req->upload("foo");
+ $size = $upload->size;
+
+ # three methods to get at the upload's contents ... slurp, fh, io
+
+ $upload->slurp($slurp_data);
+
+ read $upload->fh, $fh_data, $size;
+ ok $slurp_data eq $fh_data;
+
+ my $io = $upload->io;
+ print while <$io>;
+
+=for example end
+
+=for example_testing
+ ok $upload->bb->length == $size;
+ $uploads = $req->upload();
+ is (scalar keys %{$uploads}, 1, "found upload");
+ is $_STDOUT_, $data;
+ is $fh_data, $data;
+ is $slurp_data, $data;
+
+
+
+
+
+=head1 DESCRIPTION
+
+Apache::Upload is a new module based on the original package included
+in Apache::Request 1.X. Users requiring the upload API must now
+C<use Apache::Upload>, which adds the C<upload> method to Apache::Request.
+Apache::Upload is largely backwards-compatible with the original 1.X API.
+See the L<PORTING from 1.X> section below for a list of known issues.
+
+This manpage documents the Apache::Upload and Apache::Upload::Brigade
packages.
+Apache::Upload::Table and Apache::Upload::Error are also provided by this
module,
+but are documented elsewhere. For a list of related manpages, read the L<SEE
ALSO>
+section below.
+
+
+
+
+=head1 Apache::Upload
+
+
+
+
+=head2 name
+
+ $upload->name()
+
+The name of the HTML form element which generated the upload.
+
+=for testing
+ is $u->name, "foo";
+
+
+
+
+=head2 filename
+
+ $upload->filename()
+
+The (client-side) filename as submitted in the HTML form. Note:
+some agents will submit the file's full pathname, while others
+may submit just the basename.
+
+=for testing
+ is $u->filename, __FILE__;
+
+
+
+
+=head2 fh
+
+ $upload->fh()
+
+Creates filehandle reference to the upload's spooled tempfile,
+which contains the full contents of the upload.
+
+
+
+
+=head2 io
+
+ $upload->io()
+
+Creates a tied IO handle. This method is a more efficient version
+of C<fh>, but with C<io> the handle ref returned is not seekable.
+It is tied to an Apache::Upload::Brigade object, so you may use the
+brigade API on the tied object if you want to manipulate the IO stream
+(beyond simply reading from it).
+
+The returned reference is actually an object which has C<read> and
+C<readline> methods available. However these methods are just
+syntactic sugar for the underlying C<READ> and C<READLINE> methods from
+Apache::Upload::Brigade.
+
+=for example begin
+
+ $io = $upload->io;
+ print while $io->read($_); # equivalent to: tied(*$io)->READ($_)
+
+=for example end
+
+=for example_testing
+ is $_STDOUT_, $data;
+ $io = $upload->io;
+ $io->read($h{io}, $upload->size);
+ is $h{io}, $data, "autovivifying read";
+
+See L<READ|read> and L<READLINE|readline> below for additional notes
+on their usage.
+
+
+
+=head2 bb
+
+ $upload->bb()
+ $upload->bb($set)
+
+Get/set the APR::Brigade which represents the upload's contents.
+
+
+
+
+=head2 size
+
+ $upload->size()
+
+Returns the size of the upload in bytes.
+
+=for testing
+ is $u->size, -s __FILE__;
+
+
+
+
+=head2 info
+
+ $upload->info()
+ $upload->info($set)
+
+Get/set the additional header information table for the
+uploaded file.
+Returns a hash reference tied to the I<APR::Table> class.
+An optional C<$table> argument can be passed to reassign
+the upload's internal (apr_table_t) info table to the one
+C<$table> represents.
+
+=for example begin
+
+ my $info = $upload->info;
+ while (my($hdr_name, $hdr_value) = each %$info) {
+ # ...
+ }
+
+ # fetch upload's Content-Type header
+ my $type = $upload->info->{"Content-type"};
+
+=for example end
+
+=for example_testing
+ is $type, "application/octet-stream";
+
+
+
+
+=head2 type
+
+ $upload->type()
+
+Returns the MIME type of the given I<Apache::Upload> object.
+
+=for example begin
+
+ my $type = $upload->type;
+
+ #same as
+ my $content_type = $upload->info->{"Content-Type"};
+ $content_type =~ s/;.*$//ms;
+
+=for example end
+
+=for example_testing
+ is $type, $content_type;
+
+
+
+
+=head2 link
+
+ $upload->link()
+
+To avoid recopying the upload's internal tempfile brigade on a
+*nix-like system, I<link> will create a hard link to it:
+
+=for example begin
+
+ my $upload = $req->upload('foo');
+ $upload->link("/path/to/newfile") or
+ die sprintf "link from '%s' failed: $!", $upload->tempname;
+
+=for example end
+
+Typically the new name must lie on the same device and partition
+as the brigade's tempfile. If this or any other reason prevents
+the OS from linking the files, C<link()> will instead
+copy the temporary file to the specified location.
+
+
+
+
+=head2 slurp
+
+ $upload->slurp($contents)
+
+
+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 $size, length $contents;
+ $upload->slurp($h{slurp});
+ is $h{slurp}, $contents, "autovivifying slurp";
+ $contents =~ s{\r}{}g;
+ is $contents, $data;
+
+
+
+
+=head2 tempname
+
+ $upload->tempname()
+
+Provides the name of the spool file.
+
+=for example begin
+
+ my $tempname = $upload->tempname;
+
+=for example end
+
+=for example_testing
+ like $tempname, qr/apreq.{6}$/;
+
+
+
+
+=head1 Apache::Upload::Brigade
+
+
+This class is derived from APR::Brigade, providing additional
+methods for TIEHANDLE, READ and READLINE. To be memory efficient,
+these methods delete buckets from the brigade as soon as their
+data is actually read, so you cannot C<seek> on handles tied to
+this class. Such handles have semantics similar to that of a
+read-only socket.
+
+
+
+
+=head2 TIEHANDLE
+
+ Apache::Upload::Brigade->TIEHANDLE($bb)
+
+Creates a copy of the bucket brigade represented by $bb, and
+blesses that copy into the Apache::Upload::Brigade class. This
+provides syntactic sugar for using perl's builtin C<read>, C<readline>,
+and C<< <> >> operations on handles tied to this package:
+
+ use Symbol;
+ $fh = gensym;
+ tie *$fh, "Apache::Upload:Brigade", $bb;
+ print while <$fh>;
+
+
+
+
+=head2 READ
+
+ $bb->READ($contents)
+ $bb->READ($contents, $length)
+ $bb->READ($contents, $length, $offset)
+
+Reads data from the brigade $bb into $contents. When omitted
+$length defaults to C<-1>, which reads the first bucket into $contents.
+A positive $length will read in $length bytes, or the remainder of the
+brigade, whichever is greater. $offset represents the index in $context
+to read the new data.
+
+
+
+
+=head2 READLINE
+
+ $bb->READLINE()
+
+Returns the first line of data from the bride. Lines are terminated by
+linefeeds (the '\012' character), but we may eventually use C<$/> instead.
+
+
+
+
+=head1 PORTING from 1.X
+
+=over 4
+
+=item * C<< $upload->next() >> is no longer available; please use the
+C<< Apache::Upload::Table >> API when iterating over upload entries.
+
+=item * C<info($header_name)> is replaced by C<info($set)>.
+
+=item * C<type()> returns only the MIME-type portion of the Content-Type
header.
+
+=back
+
+
+
+
+=head1 SEE ALSO
+
+L<Apache::Upload::Table>, L<Apache::Upload::Error>, L<Apache::Request>,
+APR::Table(3)
+
+
+
+
+=head1 COPYRIGHT
+
+ Copyright 2003-2005 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.
