=head1 NAME

Apache::Cookie - HTTP Cookies Class

=head1 SYNOPSIS

    use Apache::Cookie ();
    my $r = Apache->request;
    my $cookie = Apache::Cookie->new($r, ...);

=head1 DESCRIPTION

The Apache::Cookie module is a Perl interface to the cookie routines
in I<libapreq>.  The interface is based on Lincoln Stein's CGI::Cookie
module.

=head1 Apache::Cookie METHODS

I<Apache::Cookie> does not export any symbols to the caller's namespace.
Except for the request object passed to C<Apache::Cookie::new>, the OO
interface is identical to I<CGI::Cookie>.  Please consult the L<CGI::Cookie>
documentation for more details.

=head2 new

Just like CGI::Cookie::new, but requires an I<Apache> request object:

        my $cookie = Apache::Cookie->new($r,
                             -name    =>  'foo', 
                             -value   =>  'bar', 
                             -expires =>  '+3M', 
                             -domain  =>  '.capricorn.com', 
                             -path    =>  '/cgi-bin/database',
                             -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.

=head2 bake

Add a I<Set-Cookie> header to the outgoing headers table.

    $cookie->bake;

=head2 bake2

Add a I<Set-Cookie2> header to the outgoing headers table.

    $cookie->bake2;

=head2 fetch

Fetch and parse the incoming I<Cookie> header:

    my $cookies = Apache::Cookie->fetch($r); #hash ref

    my %cookies = Apache::Cookie->fetch($r);

=head2 as_string

Format the cookie object as a string:

 #same as $cookie->bake
 $r->headers_out->add("Set-Cookie" => $cookie->as_string);

=head2 name

Get the name of the cookie:

 my $name = $cookie->name;

=head2 value

Get the value of the cookie:

 my $value = $cookie->value;
 my @values = $cookie->value;

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 
Apache::Cookie with a package that provides the associated C<thaw> sub:

  package My::Cookie;
  use base 'Apache::Cookie';
  sub thaw { ... }
  bless $cookie, __PACKAGE__;

  my $obj = $cookie->value;  # same as $cookie->thaw($cookie->raw_value);

=head2 raw_value

Gets the raw (opaque) value string as it appears in the incoming
"Cookie" header.

=head2 domain

Get or set the domain for the cookie:

 my $domain = $cookie->domain;
 $cookie->domain(".cp.net");

=head2 path

Get or set the path for the cookie:

 my $path = $cookie->path;
 $cookie->path("/");

=head2 expires

Get or set the expire time for the cookie:

 my $expires = $cookie->expires;
 $cookie->expires("+3h");

=head2 secure

Get or set the secure flag for the cookie:

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

=head1 CHANGES to the v1 API:

=over 4

=item * C<Apache::Cookie::fetch> requires an C<$r> object as (second) argument.

=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<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.

=back

=head1 BUGS

=head1 SEE ALSO

Apache(3), Apache::Request(3), CGI::Cookie(3)

=head1 AUTHORS

Doug MacEachern, Joe Schaefer, Issac Goldstand

=head1 MISSING DOCS

Apache::Cookie::Jar, Apache::Cookie::Table