| Cookie.pm | 
CGI::Cookie - Interface to Netscape Cookies
    use CGI::Simple::Standard qw(header);
    use CGI::Simple::Cookie;
    # Create new cookies and send them
    $cookie1 = new CGI::Simple::Cookie( -name=>'ID', -value=>123456 );
    $cookie2 = new CGI::Simple::Cookie( -name=>'preferences',
                                        -value=>{ font => Helvetica,
                                                  size => 12 }
                                      );
    print header( -cookie=>[$cookie1,$cookie2] );
    # fetch existing cookies
    %cookies = fetch CGI::Simple::Cookie;
    $id = $cookies{'ID'}->value;
    # create cookies returned from an external source
    %cookies = parse CGI::Simple::Cookie($ENV{COOKIE});
CGI::Simple::Cookie is an interface to Netscape (HTTP/1.1) cookies, an innovation that allows Web servers to store persistent information on the browser's side of the connection. Although CGI::Simple::Cookie is intended to be used in conjunction with CGI::Simple.pm (and is in fact used by it internally), you can use this module independently.
For full information on cookies see:
    http://www.ics.uci.edu/pub/ietf/http/rfc2109.txt
CGI::Simple::Cookie is object oriented. Each cookie object has a name and a value. The name is any scalar value. The value is any scalar or array value (associative arrays are also allowed). Cookies also have several optional attributes, including:
    $c = new CGI::Simple::Cookie( -name    =>  'foo',
                                  -value   =>  'bar',
                                  -expires =>  '+3M',
                                  -domain  =>  '.capricorn.com',
                                  -path    =>  '/cgi-bin/database',
                                  -secure  =>  1
                                );
Create cookies from scratch with the new method. The -name and -value parameters are required. The name must be a scalar value. The value can be a scalar, an array reference, or a hash reference. (At some point in the future cookies will support one of the Perl object serialization protocols for full generality).
-expires accepts any of the relative or absolute date formats recognized by CGI::Simple.pm, for example ``+3M'' for three months in the future. See CGI::Simple.pm's documentation for details.
-domain points to a domain name or to a fully qualified host name. If not specified, the cookie will be returned only to the Web server that created it.
-path points to a partial URL on the current server. The cookie will be returned to all URLs beginning with the specified path. If not specified, it defaults to '/', which returns the cookie to all pages at your site.
-secure if set to a true value instructs the browser to return the cookie only when a cryptographic protocol is in use.
Within a CGI script you can send a cookie to the browser by creating one or more Set-Cookie: fields in the HTTP header. Here is a typical sequence:
    $c = new CGI::Simple::Cookie( -name    =>  'foo',
                                   -value   =>  ['bar','baz'],
                                   -expires =>  '+3M'
                                  );
    print "Set-Cookie: $c\n";
    print "Content-Type: text/html\n\n";
To send more than one cookie, create several Set-Cookie: fields. Alternatively, you may concatenate the cookies together with ``; '' and send them in one field.
If you are using CGI::Simple.pm, you send cookies by providing a -cookie
argument to the header() method:
print header( -cookie=>$c );
Mod_perl users can set cookies using the request object's header_out()
method:
  $r->header_out('Set-Cookie',$c);
Internally, Cookie overloads the ``'' operator to call its as_string()
method when incorporated into the HTTP header.  as_string() turns the
Cookie's internal representation into an RFC-compliant text
representation.  You may call as_string() yourself if you prefer:
    print "Set-Cookie: ",$c->as_string,"\n";
    %cookies = fetch CGI::Simple::Cookie;
fetch returns an associative array consisting of all cookies returned by the browser. The keys of the array are the cookie names. You can iterate through the cookies this way:
    %cookies = fetch CGI::Simple::Cookie;
    foreach (keys %cookies) {
        do_something($cookies{$_});
    }
In a scalar context, fetch() returns a hash reference, which may be more
efficient if you are manipulating multiple cookies.
CGI::Simple.pm uses the URL escaping methods to save and restore reserved
characters in its cookies.  If you are trying to retrieve a cookie set by
a foreign server, this escaping method may trip you up.  Use raw_fetch()
instead, which has the same semantics as fetch(), but performs no unescaping.
You may also retrieve cookies that were stored in some external
form using the parse() class method:
       $COOKIES = `cat /usr/tmp/Cookie_stash`;
       %cookies = parse CGI::Simple::Cookie($COOKIES);
Cookie objects have a series of accessor methods to get and set cookie attributes. Each accessor has a similar syntax. Called without arguments, the accessor returns the current value of the attribute. Called with an argument, the accessor changes the attribute and returns its new value.
    $name = $c->name;
    $new_name = $c->name('fred');
    $value = $c->value;
    @new_value = $c->value(['a','b','c','d']);
value() is context sensitive. In a list context it will return the current value of the cookie as an array. In a scalar context it will return the first value of a multivalued cookie.
Original version copyright 1997-1998, Lincoln D. Stein. All rights reserved.
This verson copyright 2001, Dr James Freeman.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Address bug reports and comments to: jfreeman@tassie.net.au
This section intentionally left blank :-)
the CGI::Carp manpage, the CGI::Simple manpage
| Cookie.pm |