Basic Usage

  <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 submitted the data will come in 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.

Arrays

 First cousin:  <input type="text" name="cousins[0]">
 Second cousin: <input type="text" name="cousins[1]">
 Third cousin:  <input type="text" name="cousins[2]">

Run it through CGI to get the parameters, run through "build_cgi_struct", and we get

  $struct = {
      'cousins' => [
        'Jill',
        'Joe',
        'Judy'
      ]
  }

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:

 First cousin:  <input type="text" name="cousins[1]">
 Second cousin: <input type="text" name="cousins[2]">
 Third cousin:  <input type="text" name="cousins[3]">

  $struct = {
      'cousins' => [
        undef,
        'Jill',
        'Joe',
        'Judy'
      ]
  }

See also the "Auto-arrays" section.

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

  <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

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.

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

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

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