libapache2-request-perl 2.13-1build2 / usr / lib / perl5 / APR / Request / Cookie.pod

=head1 NAME

APR::Request::Cookie - wrapper for libapreq2's cookie API.


=for testing
    use APR::Pool;
    use APR::Brigade;
    use APR::Bucket;
    use APR::BucketAlloc;
    use APR::Request;
    use APR::Request::Parser;
    $pool = APR::Pool->new;
    $ba = APR::BucketAlloc->new($pool);
    $bb = APR::Brigade->new($pool, $ba);
    $bb->insert_tail(APR::Bucket->new($ba,
                                  "alpha=body1&beta=body2;foo=body3"));
    $parser = APR::Request::Parser->urlencoded($pool, $ba,
                                    "application/x-www-form-urlencoded");
    $req = APR::Request::Custom->handle($pool, "foo=bar",
                                                "cookie1=apache1;cookie2=apache2",
                                                $parser, 1e6, $bb);



=head1 SYNOPSIS


=for example begin

  use APR::Request::Cookie;

  # fetch inbound cookie
  $jar = $req->jar;
  $cookie1 = $jar->get("cookie1");

  # generate new cookie
  $cookie = APR::Request::Cookie->new($req->pool,
                                      name => "foo",
                                     value => "bar",
                                    domain => "capricorn.com");
  print "$cookie"; # prints "bar"

  $cookie->domain("example.com"); # change domains
  $cookie->version(1); # upgrade it to conform with RFC 2109/2965.

  # send a response header
  print sprintf "Set-Cookie: %s\n", $cookie->as_string;

=for example end

=for example_testing
  ok "$cookie1" eq "apache1";
  ok $jar->isa("APR::Request::Cookie::Table");
  is $_STDOUT_ , qq[barSet-Cookie: foo=bar; Version=1; domain="example.com"\n];




=head1 DESCRIPTION

The APR::Request::Cookie module provides base methods
for interfacing with libapreq2's cookie API.  It also provides
a few utility functions and constants.

This manpage documents version 2.13
of the APR::Request::Cookie package.




=head1 OVERLOADS

APR::Request::Cookie




=head2 ""

    "$cookie"

The double-quote interpolation operator maps to
C<< APR::Request::Cookie::value() >>.

=for example begin

    ok "$cookie" eq $cookie->value;

=for example end

=for example_testing
    1;


=head1 METHODS

APR::Request::Cookie




=head2 new

    APR::Request::Cookie->new($pool,
                               name => $name,
                              value => $value,
                              %args)


Creates a new cookie.  Here C<< $pool >> is an APR::Pool object,
and C<< $name >> is the cookie's name. The C<< $value >> is transformed
into the cookie's raw value through the class' C<< freeze() >> method.
The remaining arguments are optional:

=over 4

=item -secure

=item -httponly

=item -version

=item -path

=item -domain

=item -port

=item -expires

=item -comment

=item -commentURL

=back

For details on these arguments, please consult
the corresponding method's documentation.




=head2 freeze

    APR::Request::Cookie->freeze($value)

Class method representing the default serializer;
here it returns $value unmodified.

=for example begin

    ok "foo" eq APR::Request::Cookie->freeze("foo");

=for example end

=for example_testing
    1;




=head2 thaw

    $cookie->thaw()

Reverses C<< freeze() >>; here it simply returns 
$cookie->value since freeze() is a noop.

=for example begin

    ok $cookie->thaw eq $cookie->value;

=for example end

=for example_testing
    1;




=head2 name

    $cookie->name()

Fetch the cookie's name.  This attribute
cannot be modified and is never serialized;
ie freeze() and thaw() do not act on the
cookie's name.

=for example begin

=for example end

=for example_testing
    is $cookie->name, "foo", "name";




=head2 value

    $cookie->value()

Fetch the cookie's raw (frozen) value.
This attribute cannot be modified.

=for example begin

=for example end

=for example_testing
    is $cookie->value, "bar", "value";




=head2 secure

    $cookie->secure()
    $cookie->secure($set)


Get/set the cookie's secure flag.

=for example begin

    $cookie->secure(1);
    ok $cookie->secure == 1;

=for example end

=for example_testing
    $cookie->secure(0);
    is $cookie->secure, 0, "secure";




=head2 httponly

    $cookie->httponly()
    $cookie->httponly($set)


Get/set the cookie's HttpOnly flag.

=for example begin

    $cookie->httponly(1);
    ok $cookie->httponly == 1;

=for example end

=for example_testing
    $cookie->httponly(0);
    is $cookie->httponly, 0, "HttpOnly";




=head2 version

    $cookie->version()
    $cookie->version($set)

Get/set the cookie's version number.
Version 0 cookies conform to the Netscape
spec; Version 1 cookies conform to either
RFC 2109 or RFC 2965.

=for example begin

    $version = $cookie->version;
    $cookie->version(1);
    ok $cookie->version == 1;

=for example end

=for example_testing
    $cookie->version($version);
    is $cookie->version, $version, "version";




=head2 path

    $cookie->path()
    $cookie->path($set)

Get/set the cookie's path string.

=for example begin

    $path = $cookie->path;
    $cookie->path("/1/2/3/4");
    ok $cookie->path eq "/1/2/3/4";

=for example end

=for example_testing
    $cookie->path($path);
    is $cookie->path, $path, "path";




=head2 domain

    $cookie->domain()
    $cookie->domain($set)

Get/set the cookie's domain string.

=for example begin

    $domain = $cookie->domain;
    $cookie->domain("apache.org");
    ok $cookie->domain eq "apache.org";

=for example end

=for example_testing
    $cookie->domain($domain);
    is $cookie->domain, $domain, "domain";




=head2 port

    $cookie->port()
    $cookie->port($set)

Get/set the cookie's port string.
Only valid for Version 1 cookies.

=for example begin

    $port = $cookie->port;
    $cookie->port(8888);
    ok $cookie->port == 8888;

=for example end

=for example_testing
    $cookie->port($port);
    is $cookie->port, $port, "port";




=head2 comment

    $cookie->comment()
    $cookie->comment($set)

Get/set the cookie's comment string.
Only valid for Version 1 cookies.

=for example begin

    $comment = $cookie->comment;
    $cookie->comment("quux");
    ok $cookie->comment eq "quux";

=for example end

=for example_testing
    $cookie->comment($comment);
    is $cookie->comment, $comment, "comment";




=head2 commentURL

    $cookie->commentURL()
    $cookie->commentURL($set)

Get/set the cookie's commentURL string.
Only valid for Version 1 cookies.

=for example begin

    $commentURL = $cookie->commentURL;
    $cookie->commentURL("/foo/bar");
    ok $cookie->commentURL eq "/foo/bar";

=for example end

=for example_testing
    $cookie->commentURL($commentURL);
    is $cookie->commentURL, $commentURL, "commentURL";




=head2 is_tainted

    $cookie->is_tainted()
    $cookie->is_tainted($set)

Get/set the cookie's internal tainted flag.

=for example begin

    $tainted = $cookie->is_tainted;
    $cookie->is_tainted(1);
    ok $cookie->is_tainted == 1;

=for example end

=for example_testing
    $cookie->is_tainted($tainted);
    is $cookie->is_tainted, $tainted, "tainted";


=head2 make

    APR::Request::Cookie->make($pool, $name, $value)

Fast XS cookie constructor invoked by C<< new() >>.
The cookie's raw name & value are taken directly from the
passed in arguments; no freezing/encoding is done on the $value.




=head2 as_string

    $cookie->as_string()


String representation of the cookie, suitable for inclusion
in a "Set-Cookie" header.

=for example begin

    print "Set-Cookie: ", $cookie->as_string, "\n";

=for example end

=for example_testing
    is $_STDOUT_, qq/Set-Cookie: foo=bar; Version=1; domain="example.com"\n/,
        "as_string";


=head1 SUBROUTINES

  APR::Request::Cookie




=head2 expires


  expires($date_string)




=head1 SEE ALSO

L<< Apache2::Cookie >>, L<< APR::Request >>.




=head1 COPYRIGHT

  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You 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.