NAME
   CGI::Expand - convert flat hash to nested data using TT2's dot
   convention

SYNOPSIS
       use CGI::Expand;
       use CGI; # or Apache::Request, etc.

       $args = expand_cgi( CGI->new('a.0=3&a.2=4&b.c.0=x') );
       # $args = { a => [3,undef,4], b => { c => ['x'] }, }

       # Or to catch exceptions:
       eval {
           $args = expand_cgi( CGI->new('a.0=3&a.2=4&b.c.0=x') );
       } or log_and_exit( $@ );

       #-----
       use CGI::Expand qw(expand_hash);

       $args = expand_hash({'a.0'=>77}); # $args = { a => [ 77 ] }

DESCRIPTION
   Converts a CGI query into structured data using a dotted name convention
   similar to TT2.

   "expand_cgi" works with CGI.pm, Apache::Request or anything with an
   appropriate "param" method. Or you can use "expand_hash" directly.

   If you prefer to use a different flattening convention then CGI::Expand
   can be subclassed.

Motivation
   The Common Gateway Interface restricts parameters to name=value pairs,
   but often we'd like to use more structured data. This module uses a name
   encoding convention to rebuild a hash of hashes, arrays and values.
   Arrays can either be indexed explicitly or from CGI's multi-valued
   parameter handling.

   The generic nature of this process means that the core components of
   your system can remain CGI ignorant and operate on structured data.
   Better for modularity, better for testing.

DOT CONVENTION
   The key-value pair "a.b.1=hi" expands to the perl structure:

     { a => { b => [ undef, "hi" ] }

   The key ("a.b.1") specifies the location at which the value ("hi") is
   stored. The key is split on '.' characters, the first segment ("a") is a
   key in the top level hash, subsequent segments may be keys in sub-hashes
   or indices in sub-arrays. Integer segments are treated as array indices,
   others as hash keys.

   Array size is limited to 100 by default. The limit can be altered by
   subclassing or using the deprecated $Max_Array package variable. See
   below.

   The backslash '\' escapes the next character in cgi parameter names
   allowing '.' , '\' and digits in hash keys. The escaping '\' is removed.
   Values are not altered.

 Key-Value Examples
     # HoHoL
     a.b.1=hi ---> { a => { b => [ undef, "hi" ] }

     # HoLoH
     a.1.b=hi ---> { a => [ undef, { b => "hi" } ] }

     # top level always a hash
     9.0=hi   ---> { "9" => [ "hi" ] }

     # can backslash escape to treat digits hash as keys
     a.\0=hi     ---> { "a" => { 0 => "hi"} }

     # or to put . and \ literals in keys
     a\\b\.c=hi  ---  { 'a\\b\.c' => "hi" }

EXPORTS
   "expand_cgi" by default, "expand_hash" and "collapse_hash" upon request.

FUNCTIONS
   " $deep_hash = expand_cgi ( $CGI_object_or_similar ) "
       Takes a CGI object and returns a hashref for the expanded data
       structure (or dies, see "EXCEPTIONS").

       Wrapper around expand_hash that uses the "param" method of the CGI
       object to collect the names and values.

       Handles multivalued parameters as array refs (although they can't be
       mixed with indexed arrays and will have an undefined ordering).

           $query = 'a.0=3&a.2=4&b.c.0=x&c.0=2&c.1=3&d=&e=1&e=2';

           $args = expand_cgi( CGI->new($query) );

           # result:
           # $args = {
           #   a => [3,undef,4],
           #   b => { c => ['x'] },
           #   c => ['2','3'],
           #   d => '',
           #   e => ['1','2'], # order depends on CGI/etc
           # };

   " $deep_hash = expand_hash ( $flat_hash ) "
       Expands the keys of the parameter hash according to the dot
       convention (or dies, see "EXCEPTIONS").

           $args = expand_hash({ 'a.b.1' => [1,2] });
           # $args = { a => { b => [undef, [1,2] ] } }

   " $flat_hash = collapse_hash ( $deep_hash ) "
       The inverse of expand_hash. Converts the $deep_hash data structure
       back into a flat hash.

           $flat = collapse_hash({ a => { b => [undef, [1,2] ] } });
           # $flat = { 'a.b.1.0' => 1, 'a.b.1.1' => 2 }

EXCEPTIONS
   WARNING the USERs of your site can cause these exceptions so you must
   decide how they are handled (possibly by letting the process die).

   "CGI param array limit exceeded..."
       If an array index exceeds the array limit (default: 100) then an
       exception is thrown.

   "CGI param clash for..."
       A cgi query like "a=1&a.b=1" would require the value of $args->{a}
       to be both 1 and { b => 1 }. Such type inconsistencies are reported
       as exceptions. (See test.pl for for examples)

SUBCLASSING
   Subclassing in now the preferred way to change the behaviour and
   defaults. (Previously package variables were used, see test.pl).

   The methods which may be overriden by subclasses are separator,
   max_array, split_name and join_name.

   $subclass->max_array()
       The limit for the array size, defaults to 100. The value 0 can be
       used to disable the use of arrays, everthing is a hash key.

   $subclass->separator()
       Returns the separator charaters used to split the keys of the flat
       hash. The default is '.' but multiple characters are allowed. The
       default join will use the first character.

       If there is no separator then '\' escaping does not occur. This is
       for use with split_name and join_name below.

   @segments = $subclass->split_name($name)
       The split_name method must break $name in to key segments for the
       nested data structure. The default version just splits on the
       separator characters with a bit of fiddling to handle escaping.

   $name = $subclass->join_name(@segments)
       The inverse of split_name, joins the segments back to the key for
       the flat hash. The default version uses the first character of the
       string returned by the separator method.

DEPRECATIONS
   $CGI::Expand::Separator and $CGI::Expand::Max_Array are deprecated. They
   still work for now but emit a warning (supressed with
   $CGI::Expand::BackCompat = 1)

   Using the functions by their fully qualified names ceased to work at
   around version 1.04. They're now class methods so just replace the last
   :: with ->.

LIMITATIONS
   The top level is always a hash. Consequently, any digit only names will
   be keys in this hash rather than array indices.

   Image inputs with name.x, name.y coordinates are ignored as they will
   class with the value for name.

TODO
   Thing about ways to keep $cgi and the expanded version in sync

   Glob style parameters (with SCALAR, ARRAY and HASH slots) would resolve
   the type clashes, probably no fun to use. Look at using
   Template::Plugin::StringTree to avoid path clashes

SEE ALSO
   *   HTTP::Rollup - Replaces CGI.pm completely, no list ordering.

   *   CGI::State - Tied to CGI.pm, unclear error checking

   *   Template::Plugin::StringTree

   *   Hash::Flatten - Pick your delimiters

   *   http://template-toolkit.org/pipermail/templates/2002-January/002368.
       html

   *   There's a tiny and beautiful reduce solution somewhere on perlmonks.

AUTHOR
   Brad Bowman <[email protected]>

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.