/ 
CGI-Expand-1.03
River stage two • 5 direct dependents • 97 total dependents
/ CGI::Expand

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.

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 ordered, 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.

(This problem has appeared a few times in other forums, "SEE ALSO")

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 by $CGI::Expand::Max_Array, 100 by default.

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 upon request.

FUNCTIONS

$args = expand_cgi ( $CGI_object_or_similer )

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
# };
$args = expand_hash ( $hashref )

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] ] } }

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 $CGI::Expand::Max_Array (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)

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 cause a clash.

TODO

Allow another character as separator (not just '.') in case they want to use JS.

Another, potentially useful option would be to remove empty parameters. (I think I'll leave this to another tool..)

Glob style parameters (with SCALAR, ARRAY and HASH slots) would resolve the type clashes. I suspect it would be ungainly and memory hungry to use.

Look at using Template::Plugin::StringTree to avoid path clashes (eg .x)

SEE ALSO

  • HTTP::Rollup - Replaces CGI.pm completely, no list ordering.

  • CGI::State - Tied to CGI.pm, unclear error checking, has the inverse conversion.

  • 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 <cgi-expand@bereft.net>