DESCRIPTION

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 be 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.

Whatever you use should give you a hash mapping the request variable names (keys) to the values sent in by the users (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 necessarily tied strictly to CGI; you could use it to build data structures from any other source with similar syntax. All CGI::Struct does is take one hash (reference) and turn it into another hash (reference). However, it's aimed at CGI uses, so it may or may not work for something else.

Of course, most CGIish modules will roll that up into an array if you just call it 'cousins' and have multiple inputs. But this lets you specify the indices. For instance, you may want to base the array from 1 instead of 0:

NULL delimited multiple values

When using CGI's ->Vars and similar, multiple passed values will wind up as a \0-delimited string, rather than an array ref. By default, CGI::Struct will split it out into an array ref. This behavior can by disabled by using the nullsplit config param; see the function doc below.

Deeper and deeper

Specifying arrays explicitly is also useful when building arbitrarily deep structures, since the array doesn't have to be at the end

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

Dotted hashes

Also supported is dot notation for hash keys. This saves you a few keystrokes, and can look neater. Hashes may be specified with either the . 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

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

Sometimes, though, you may want to have dots in field names, and you wouldn't want this parsing to happen then. It can be disabled for a run of "build_cgi_struct" by passing a config param in; see the function doc below.

Auto-arrays

CGI::Struct also builds 'auto-arrays', which is to say it turns parameters ending with an empty [] into arrays and pushes things onto them.

<select multiple="multiple" name="users[]">

turns into

$struct->{users} = ['lots', 'of', 'choices'];

This may seem unnecessary, given the ability of most CGI modules to already build the array just by having multiple users params given. Also, since "build_cgi_struct" only sees the data after your CGI module has already parsed it out, it will only ever see a single key in its input hash for any name anyway, since hashes can't have multiple keys with the same name anyway.

However, there are a few uses for it. PHP does this, so it makes for an easier transition. Also, it forces an array, so if you only chose one entry in the list, "build_cgi_struct" would still make that element in the structure a (single-element) array

$struct->{users} = ['one choice'];

which makes your code a bit simpler, since you don't have to expect both a scalar and an array in that place (though of course you should make sure it's what you expect for robustness).

FUNCTIONS

build_cgi_struct

build_cgi_struct() is the only function provided by this module. It takes as an argument a reference to a hash of parameter 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 for the developer's eyes to parse, not a source of friendly-looking warnings to hand to non-technical users or as strongly formatted strings for automated error mining.

A hash reference may be supplied as a third argument for passing config parameters. The currently supported parameters are:

nodot

This allows you to disable 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.

The default is false (i.e., do use . as separator). Pass a true value (like 1) to not do so.

nullsplit

CGI->Vars and compatible functions tend to, in hash form, wind up with a NULL-delimited list rather than an array ref when passed multiple values with the same key. CGI::Struct will check string values for embedded \0's and, if found, split the string on them and create an arrayref.

The nullsplit config param lets you disable this if you want strings with embedded \0 to pass through unmolested. Pass a false value (like 0) to disable the splitting.

dclone

By default, CGI::Struct uses Storable's dclone to do deep copies of incoming data structures. This ensures that whatever changes you might make to $struct later on don't change stuff in %params too. By setting dclone to a false value (like 0) you can disable this, and make it so deeper refs in the data structures point to the same items.

You probably don't want to do this, unless some data is so huge you don't want to keep 2 copies around, or you really do want to edit the original %params for some reason.

SUPPORTED VERSIONS

CGI::Struct should work on perl 5.6 and later. It includes a comprehensive test suite, so passing that should be an indicator that it works. If that's not the case, I want to hear about it so the testing can be improved!