joes 2004/07/24 22:25:38
Modified: . CHANGES
glue/perl/docs Cookie.pod Upload.pod
glue/perl/xsbuilder/Apache/Cookie Cookie_pm
glue/perl/xsbuilder/Apache/Upload Apache__Upload.h
Log:
Clean up and document Apache::Cookie's freeze/thaw methods
Revision Changes Path
1.58 +7 -0 httpd-apreq-2/CHANGES
Index: CHANGES
===================================================================
RCS file: /home/cvs/httpd-apreq-2/CHANGES,v
retrieving revision 1.57
retrieving revision 1.58
diff -u -r1.57 -r1.58
--- CHANGES 23 Jul 2004 17:22:53 -0000 1.57
+++ CHANGES 25 Jul 2004 05:25:38 -0000 1.58
@@ -4,6 +4,13 @@
@section v2_04_dev Changes with libapreq2-2.04-dev
+- Perl API [joes]
+ Apache::Cookie::Jar->new accepts a VALUE_CLASS argument, which effectively
+ blesses all the jar's cookies into that class, which simplifies subclassing
+ Apache::Cookie. Accordingly Apache::Cookie->freeze($value) no longer
accepts
+ a freeze()-able object in $value.
+
+
- C API [Markus Wichitill, randyk, joes]
Drop APR_DELONCLOSE from apreq_file_mktemp implementation and install
apreq_file_cleanup. When passed to apr_file_open on Win32, APR_DELONCLOSE
1.7 +69 -24 httpd-apreq-2/glue/perl/docs/Cookie.pod
Index: Cookie.pod
===================================================================
RCS file: /home/cvs/httpd-apreq-2/glue/perl/docs/Cookie.pod,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- Cookie.pod 25 Jul 2004 02:18:32 -0000 1.6
+++ Cookie.pod 25 Jul 2004 05:25:38 -0000 1.7
@@ -63,19 +63,22 @@
=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 C<< new($env, %settings) >>
+=head2 C<< new($env, %args) >>
Class method that retrieves the parsed cookie jar from the current
-environment. The optional VALUE_CLASS => $cookie_class setting instructs
-the jar to bless any returned cookies into $cookie_class, instead
-of Apache::Cookie. This feature could be most 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 a subclass
-and pass that subclass's name in the VALUE_CLASS argument.
+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
{
@@ -103,10 +106,10 @@
full list of such cookies are returned.
If the $key argument is omitted, C<< scalar $jar->cookies() >> will
-return a reference to a tied Apache::Cookie::Table containing all the
-cookies in the jar. Modifications to the returned table 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.
+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
@@ -189,9 +192,9 @@
-=head2 C<< new($env, %attributes) >>
+=head2 C<< new($env, %args) >>
-Just like CGI::Cookie::new, but requires an environment argument $r:
+Just like CGI::Cookie::new, but requires an additional environment argument:
=for example begin
@@ -213,11 +216,50 @@
ok $cookie->path eq "/cgi-bin/database";
ok $cookie->secure == 1;
-The C<-value> attribute may be either an arrayref, a hashref, or
-an object with a C<freeze> method. The <freeze> method must serialize
-the object in a manner compatible with the "value" portion of the
-Cookie specs. Specifically, it must take care to avoid header tokens [;,]
-and whitespace characters in its output.
+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 C<< 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";
+
+
+
+
+=head2 C<< thaw(), thaw($value) >>
+
+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 msthod 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";
+ ok @values == 2;
+ ok $values[0] eq "2+2";
+ ok $values[1] eq "=4";
@@ -425,7 +467,7 @@
-=head2 C<< fetch($env) >>
+=head2 C<< fetch($env) >> DEPRECATED
Fetch and parse the incoming I<Cookie> header:
@@ -452,14 +494,17 @@
=over 4
-=item * C<Apache::Cookie::fetch> requires an C<$r> object as (second)
argument.
+=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> can take an object as its -value arg, assuming
- the object has a valid C<freeze> method.
+=item * C<Apache::Cookie::new> no longer encodes the supplied cookie name,
and it
+ now accepts an objects as cookie values, assuming the object has a
valid
+ C<freeze> method.
-=item * C<name> and <value> no longer accept a "set" argument. In other
words,
+=item * C<name()> and <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.
1.2 +9 -0 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.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Upload.pod 22 Jul 2004 03:07:44 -0000 1.1
+++ Upload.pod 25 Jul 2004 05:25:38 -0000 1.2
@@ -2,6 +2,15 @@
Apache::Upload - Methods for dealing with file uploads.
+=for future testing
+ use Apache2;
+ use APR::Pool;
+ use Apache::Upload;
+ $r = APR::Pool->new;
+ $req = Apache::Request->new($r);
+ $upload = Apache::Upload->new($r, name => "foo", value => __FILE__);
+ $req->body->add($upload);
+
=head1 SYNOPSIS
use Apache::Upload;
1.23 +10 -11 httpd-apreq-2/glue/perl/xsbuilder/Apache/Cookie/Cookie_pm
Index: Cookie_pm
===================================================================
RCS file:
/home/cvs/httpd-apreq-2/glue/perl/xsbuilder/Apache/Cookie/Cookie_pm,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -r1.22 -r1.23
--- Cookie_pm 24 Jul 2004 21:09:18 -0000 1.22
+++ Cookie_pm 25 Jul 2004 05:25:38 -0000 1.23
@@ -73,26 +73,25 @@
sub freeze {
my ($class, $value) = @_;
- return encode($value) if not ref $value;
- if (my $freeze = UNIVERSAL::can($value, "freeze")) {
- my $val = $freeze->($value);
- return $val if $val =~ /^".+"$/ or $val !~ tr/\r\n\t ;,//;
- die "Unsafe encoding of cookie value $value: $val";
+ die "Usage: Apache::Cookie->freeze($value)" unless @_ == 2;
+
+ if (not ref $value) {
+ return encode($value);
}
- if (UNIVERSAL::isa($value, "ARRAY")) {
+ elsif (UNIVERSAL::isa($value, "ARRAY")) {
return join '&', map encode($_), @$value;
}
elsif (UNIVERSAL::isa($value, "HASH")) {
return join '&', map encode($_), %$value;
}
- else {
- die "Can't freeze '$value'";
- }
+
+ die "Can't freeze reference: $value";
}
sub thaw {
- my @rv = map decode($_), split /&/, shift->raw_value;
- return wantarray ? @rv : $rv[0];
+ my $self = shift;
+ my @rv = split /&/, @_ ? shift : $self->raw_value;
+ return wantarray ? map decode($_), @rv : decode($rv[0]);
}
sub value { shift->thaw }
1.30 +1 -1
httpd-apreq-2/glue/perl/xsbuilder/Apache/Upload/Apache__Upload.h
Index: Apache__Upload.h
===================================================================
RCS file:
/home/cvs/httpd-apreq-2/glue/perl/xsbuilder/Apache/Upload/Apache__Upload.h,v
retrieving revision 1.29
retrieving revision 1.30
diff -u -r1.29 -r1.30
--- Apache__Upload.h 24 Jul 2004 15:10:12 -0000 1.29
+++ Apache__Upload.h 25 Jul 2004 05:25:38 -0000 1.30
@@ -115,7 +115,7 @@
APREQ_XS_DEFINE_TABLE_METHOD_N(param,set);
APREQ_XS_DEFINE_TABLE_NEXTKEY(upload_table);
-APR_INLINE
+
static XS(apreq_xs_upload_link)
{
dXSARGS;
