/ 
CGI-Struct-1.10
River stage three • 1 direct dependent • 682 total dependents
/ CGI::Struct

NAME

CGI::Struct - Build structures from CGI data

VERSION

Version 1.10

SYNOPSIS

This module allows transforming CGI GET/POST data into intricate data structures. It is reminiscent of PHP's building arrays from form data, but with a perl twist.

DESCRIPTION

CGI::Struct lets you transform CGI data keys that look like perl data structures into actual perl data structures.

CGI::Struct makes no attempt to actually read in the variables from the request. You should be using CGI or some equivalent for that. CGI::Struct expects to by handed a reference to a hash containing all the keys/values you care about. The common way is to use something like CGI->Vars or (as the author does) Plack::Request->parameters->mixed.

Anything that gives you a hash with the keys being the request variable names, and the values the values. Any of the major CGIish modules will have such a method; consult the documentation for yours if you don't know it offhand.

Of course, this isn't tied directly to CGI; you could use it to build data structures from any other source with similar syntax. However, it's aimed at CGI uses, so it may or may not work for something else.

EXAMPLES

<form action="request.cgi">
 Name:    <input type="text" name="uinfo{name}">
 Address: <input type="text" name="uinfo{addr}">
 Email:   <input type="text" name="uinfo{email}">
</form>

When filled out and send to request.cgi, which will use something like CGI->Vars to parse it out into a hash

use CGI;
my $cgi = CGI->new;
my %params = $cgi->Vars;

You'll wind up with something like

%params = (
    'uinfo{name}'  => 'Bob',
    'uinfo{addr}'  => '123 Main Street',
    'uinfo{email}' => 'bob@bob.bob',
)

Now we use CGI::Struct to parse that out

use CGI::Struct;
my $struct = build_cgi_struct \%params;

and we wind up with a structure that looks more like

$struct = {
    'uinfo' => {
        name  => 'Bob',
        addr  => '123 Main Street',
        email => 'bob@bob.bob',
    }
}

which is much simpler to use in your code.

CGI::Struct also has the ability to build out arrays, and arbitrarily deep structures.

<select name="users{bob}{cousins}[5]{firstname}">

After a quick trip through build_cgi_struct(), that'll turn into $struct{users}{bob}{cousins}[5]{firstname} just like you'd expect.

Also supported is dot notation for hash keys. This saves you a few keystrokes, and can look neater. Hashes may be specified with either {} or with .. Arrays can only be written with [].

The above select could be written using dots for some or all of the hash keys instead, looking a little Javascript-ish

<select name="users.bob.cousins[5].firstname">
<select name="users.bob{cousins}[5].firstname">
<select name="users{bob}.cousins[5]{firstname}">

of course, you wouldn't really want to mix-and-match in one field in practice; it just looks silly.

SUBROUTINES/METHODS

build_cgi_struct

$struct = build_cgi_struct \%params;

$struct = build_cgi_struct \%params, \@errs;

$struct = build_cgi_struct \%params, \@errs, \%conf;

build_cgi_struct() is the only function provided by this module. It takes as an argument a reference to a hash of parameters name keys and parameter value values. It returns a reference to a hash with the fully built up structure. Any keys that can't be figured out are not present in the returned hash.

An optional array reference can be passed as the second argument, in which case the array will be filled in with any warnings or errors found in trying to build the structure. This should be taken as a debugging tool, not a source of friendly-looking warnings to hand to non-technical users.

A hash reference may be supplied as a third argument for passing config parameters. The only currently support parameter is 'nodot' which disables processing of . as a hash element separator. There may be cases where you want a . as part of a field name, so this lets you still use {} and [] structure in those cases.

SEE ALSO

CGI, CGI::Simple, CGI::Minimal, Plack, and many other choices for handling transforming a browser's request info a data structure suitable for parsing.

CGI::State is somewhat similar to CGI::Struct, but is very closely tied to CGI and doesn't have as much flexibility in the structures it can build.

AUTHOR

Matthew Fuller, <fullermd@over-yonder.net>

BUGS

Please report any bugs or feature requests to bug-cgi-struct at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Struct. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc CGI::Struct

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2010 Matthew Fuller.

This software is licensed under the 2-clause BSD license. See the LICENSE file in the distribution for details.