/ 
CGI-Cookie-Jam-0.02
/ CGI::Cookie::Jam

NAME

CGI::Cookie::Jam - Jam a large number of cookies to a small.

SYNOPSIS

use CGI::Cookie::Jam;

my $jam = CGI::Cookie::Jam->new('cookie_jammed');

my @cookie = $jam->enjam(
   name    => 'Masanori HATA'           ,
   mail    => 'lovewing@geocities.co.jp',
   sex     => 'male'                    ,
   birth   => '2003-04-09'              ,
   nation  => 'Japan'                   ,
   pref    => 'Saitama'                 ,
   city    => 'Kawaguchi'               ,
   tel     => '+81-48-2XX-XXXX'         ,
   fax     => '+81-48-2XX-XXXX'         ,
   job     => 'student'                 ,
   role    => 'president'               ,
   hobby   => 'exaggeration'            ,
);

my %param = CGI::Cookie::Jam::dejam($ENV{'HTTP_COOKIE'});

DESCRIPTION

This module provides jam-ming method about WWW cookie. Cookie is convenient but there are limitations on the number of cookies that a client can store at any one time:

300 total cookies
4KB per cookie, where the NAME and the VALUE combine to form the 4KB limit.
20 cookies per server or domain.

Especially, 20 cookies limitation could be a bottle neck. So this module try to jam some cookies to a cookie at maximum size of 4KB, that you can save the total number of cookies to a minimum number.

METHODS and FUNCTIONS

new($cookie_name [, size => $byte])

Constructor class method. $cookie_name will be coupled with numbering _XX (XX: 00~99) and be used as the NAME of NAME=VALUE string in Set-Cookie: HTTP header.

When you put size attribute, the size of a cookie (that is the size of NAME=VALUE string) will be less than $byte Bytes. The default value of size is 4096 Bytes (4KB). If you set 0 Byte, no size limitation will issue and only one cookie will be generated without filename numbering.

enjam( $name1 => $value1 [, $name2 => $value2, ...] )

This object-class method jams a lot number of multiple NAME=VALUE strings for Set-Cookie: HTTP header to a minimum number of NAME=VALUE strings for Set-Cookie: HTTP header. Then returns a list of multiple en-jam-med strings.

The en-jam-ming algorithm is realized by twice uri-escaping. At first, each cookie's NAME and VALUE pairs are uri-escaped and joined with = (an equal mark). Then, multiple NAME=VALUE pairs are joined with & (an ampersand mark). This procedure is the very uri-encoding (see http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4.1).

Still a cookie has only one NAME=VALUE pair, the uri-encoded string must be re-uri-escaped at the second procedure. As a result:

'=' is converted to '%3D'
'&' is converted to '%26'
'%' is converted to '%25'

At last, this module uses the jam's $cookie_name (which is, of course, uri-escaped, and coupled with a serial number like $cookie_name_XX) as cookie NAME and uses the twice uri_escaped string as cookie VALUE, then join both with = to make a NAME=VALUE string. The final product is the very en-jam-med cookie.

When you use en-jam-med cookie, you may de-jam to reverse the above procedure:

1: Extract VALUEs
   and join the splitted en-jam-med VALUE strings to a string.
2: uri-unescape '%3D' to '=', '%26' to '&', '%25' to '%'.
3: uri-decode the uri-encoded string to multiple NAME and VALUE pairs.

This module implements above the function as dejam() method except for the first procedure. Otherwise, you may implement dejam() function by client side using with JavaScript and so on.

dejam($cookie_string)

This function de-jams an en-jam-med cookie string. It returns NAME and VALUE pairs as a list. You could use those de-jam-med data to put into an hash.

Note that this method does not care multiple spanning en-jam-med cookies.

SEE ALSO

Netscape: http://wp.netscape.com/newsref/std/cookie_spec.html (Cookie)
RFC2965: http://www.ietf.org/rfc/rfc2965.txt (Cookie)
HTML4.01: http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4.1 (uri-encode)

AUTHOR

Masanori HATA <lovewing@dream.big.or.jp> (Saitama, JAPAN)

COPYRIGHT

Copyright (c) 2003-2005 Masanori HATA. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.