httpd-apreq-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From j...@apache.org
Subject cvs commit: httpd-apreq-2/glue/perl/docs Cookie.pod
Date Sun, 25 Jul 2004 19:56:44 GMT
joes        2004/07/25 12:56:44

  Modified:    glue/perl/docs Cookie.pod
  Log:
  Fix Cookie.pod docs
  
  Revision  Changes    Path
  1.11      +118 -70   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.10
  retrieving revision 1.11
  diff -u -r1.10 -r1.11
  --- Cookie.pod	25 Jul 2004 06:00:56 -0000	1.10
  +++ Cookie.pod	25 Jul 2004 19:56:44 -0000	1.11
  @@ -1,12 +1,13 @@
   =head1 NAME
   
  -Apache::Cookie - HTTP Cookies Class
  +Apache::Cookie, Apache::Cookie::Jar - HTTP Cookies Class
   
   =for testing
       use Apache2;
       use Apache::Cookie;
       use APR::Pool;
  -    $r = APR::Pool->new;
  +    # 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")
);
  @@ -70,8 +71,9 @@
   
   
   
  -=head2 C<< new($env, %args) >>
  +=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
  @@ -102,7 +104,10 @@
   
   
   
  -=head2 C<< cookies(), cookies($key) >>
  +=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
  @@ -129,49 +134,56 @@
   
   =for example begin
   
  -     $j->cookies->add(Apache::Cookie->new($r, name => "foo", value => 3));
  +    $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
  +    $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;
  -     ok $_ -> name eq "foo" for $cookie, @cookies;
  -     ok $cookies[0]->value eq $cookie->value;
  -     ok $cookies[0]->value == 1;
  -     ok $cookies[1]->value == 3;
  -     ok "foo bar foo" eq "@names";
  +    ok @cookies == 2;
  +    ok $_ -> name eq "foo" for $cookie, @cookies;
  +    ok $cookies[0]->value eq $cookie->value;
  +    ok $cookies[0]->value == 1;
  +    ok $cookies[1]->value == 3;
  +    ok "foo bar foo" eq "@names";
  +
   
   
   
  +=head2 status
   
  -=head2 C<< status(), status($set) >>
  +    $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 $@->isa("Apache::Cookie::Jar::Error");
  -   $j->status(0);
  +    $j->status(-1);
  +    ok $j->status == -1;
  +    eval { @cookies = $j->cookies("foo") };   # croaks
  +    ok $@->isa("Apache::Cookie::Jar::Error");
  +    $j->status(0);
   
   =for example end
   
   =for example_testing
  -   ok $j->status == 0;
  -   @cookies = $j->cookies("foo");
  -   ok @cookies == 2;
  +    ok $j->status == 0,            '$j->status == 0';
  +    @cookies = $j->cookies("foo");
  +    ok @cookies == 2,              '@cookies == 2';
   
   
   
   
  -=head2 C<< env() >>
  +=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. 
  @@ -180,12 +192,12 @@
   
   =for example begin
   
  -   ok $j->env->isa(Apache::Cookie::Jar->env);
  +    ok $j->env->isa(Apache::Cookie::Jar->env);
   
   =for example end
   
   =for example_testing
  -   ok (Apache::Cookie::Jar->env eq "APR::Pool");
  +    ok Apache::Cookie::Jar->env eq "APR::Pool", 'env() isa APR::Pool';
   
   
   
  @@ -195,7 +207,9 @@
   
   
   
  -=head2 C<< new($env, %args) >>
  +=head2 new
  +
  +    Apache::Cookie->new($env, %args)
   
   Just like CGI::Cookie::new, but requires an additional environment argument:
   
  @@ -213,11 +227,11 @@
   =for example end
   
   =for example_testing
  -    ok $cookie->name eq "foo";
  -    ok $cookie->value eq "bar";
  -    ok $cookie->domain eq ".capricorn.com";
  -    ok $cookie->path eq "/cgi-bin/database";
  -    ok $cookie->secure == 1;
  +    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 
  @@ -226,7 +240,9 @@
   
   
   
  -=head2 C<< freeze($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 
  @@ -239,16 +255,20 @@
   =for example end
   
   =for example_testing
  -    ok $value eq "2%2b2&%3d4";
  +    ok $value eq "2%2b2&%3d4", '$value eq "2%2b2&%3d4"';
  +
   
   
   
  +=head2 thaw
  +
  +    Apache::Cookie->thaw($value)
  +    $cookie->thaw()
   
  -=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 
  +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
  @@ -259,15 +279,17 @@
   =for example end
   
   =for example_testing
  -    ok $_STDOUT_ eq "bar";
  -    ok @values == 2;
  -    ok $values[0] eq "2+2";
  -    ok $values[1] eq "=4";
  +    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
   
  -=head2 C<< 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.
  @@ -285,23 +307,21 @@
   
   
   
  -=head2 C<< name() >>
  +=head2 name
   
  -Get the name of the cookie:
  -
  -=for example begin
  +    $cookie->name()
   
  -    my $name = $cookie->name;
  -
  -=for example end
  +Get the name of the cookie.
   
   =for example_testing
  -    ok $name eq "foo";
  +    ok $cookie->name eq "foo";
   
   
   
   
  -=head2 C<< value() >>
  +=head2 value
  +
  +    $cookie->value()
   
   Get the (unswizzled) value of the cookie:
   
  @@ -313,15 +333,16 @@
   =for example end
   
   =for example_testing
  -    ok @values == 1;
  -    ok $value eq "bar";
  -    ok $values[0] eq "bar";
  +    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 serialized from an object possessing a 
  -C<freeze> method, one way to reconstitute the object is by subclassing 
  +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'; 
  @@ -330,14 +351,16 @@
   
       bless $cookie, "My::COOKIE";
   
  -    ok ($cookie->value eq "BAR");
  +    ok $cookie->value eq "BAR";
   
   =for example end
   
   
   
   
  -=head2 C<< raw_value() >>
  +=head2 raw_value
  +
  +    $cookie->raw_value()
   
   Gets the raw (opaque) value string as it appears in the incoming
   "Cookie" header.  
  @@ -354,25 +377,30 @@
   
   
   
  -=head2 C<< bake() >>
  +=head2 bake
  +
  +    $cookie->bake()
   
   Adds a I<Set-Cookie> header to the outgoing headers table.
   
  -    $cookie->bake;
   
   
   
  +=head2 bake2
   
  -=head2 C<< bake2() >>
  +    $cookie->bake2()
   
   Adds a I<Set-Cookie2> header to the outgoing headers table.
   
  -    $cookie->bake2;
   
   
   
   
  -=head2 C<< domain(), domain($set) >>
  +
  +=head2 domain
  +
  +    $cookie->domain()
  +    $cookie->domain($set)
   
   Get or set the domain for the cookie:
   
  @@ -390,7 +418,10 @@
   
   
   
  -=head2 C<< path(), path($set) >>
  +=head2 path
  +
  +    $cookie->path()
  +    $cookie->path($set)
   
   Get or set the path for the cookie:
   
  @@ -408,7 +439,10 @@
   
   
   
  -=head2 C<< version(), version($set) >>
  +=head2 version
  +
  +    $cookie->version()
  +    $cookie->version($set)
   
   Get or set the cookie version for this cookie.
   Netscape spec cookies have version = 0; 
  @@ -428,7 +462,10 @@
   
   
   
  -=head2 C<< expires(), expires($set) >>
  +=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]?)$/
  @@ -451,7 +488,10 @@
   
   
   
  -=head2 C<< secure(), secure($set) >>
  +=head2 secure
  +
  +    $cookie->secure()
  +    $cookie->secure($set)
   
   Get or set the secure flag for the cookie:
   
  @@ -470,7 +510,10 @@
   
   
   
  -=head2 C<< comment(), comment($set) >>
  +=head2 comment
  +
  +    $cookie->comment()
  +    $cookie->comment($set)
   
   Get or set the comment field of an RFC (Version > 0) cookie.
   
  @@ -487,7 +530,10 @@
   
   
   
  -=head2 C<< commentURL(), commentURL($set) >>
  +=head2 commentURL
  +
  +    $cookie->commentURL()
  +    $cookie->commentURL($set)
   
   Get or set the commentURL field of an RFC (Version > 0) cookie.
   
  @@ -504,7 +550,9 @@
   
   
   
  -=head2 C<< fetch($env) >> DEPRECATED
  +=head2 fetch
  +
  +    Apache::Cookie->fetch($r)
   
   Fetch and parse the incoming I<Cookie> header:
   
  @@ -539,7 +587,7 @@
   
   =item * C<Apache::Cookie::new> no longer encodes the supplied cookie name.  
   
  -=item * C<name()> and <value()> no longer accept a "set" argument. In other
words,
  +=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.
   
  
  
  

Mime
View raw message