CGI::ParamComposite - Convert .-delimited CGI parameters to Perl classes/objects


  use CGI;
  use CGI::ParamComposite;
  my $q = CGI->new();
  $q->param(-name=>'food.meat',     -value=>['pork','beef','fish']);

  my $c = CGI::ParamComposite->new( cgi => $q );

  #Dumper([$composite->roots()]) returns (minor formatting):
  $VAR1 = {
    'food' => {
      'meat' => [
      'vegetable' => [

  #either way, these calls now work:
  my($market) = %{ $composite->param() };
  ref($market);                                       #returns HASH
  keys(%{ $market->{food} });                         #returns ('meat','vegetable')

  #note that food.meat.pork with throw an error b/c a higher level key, food.meat,
  #has already had its value set.  the keys are evaluated from least to most
  #specific (measured by namespace depth, or number of dots)


I needed this for a fairly large single-CGI script application that I was working on. It was a script that had been actively, organically growing for 4+ years, and was getting very difficult to track the undocumented 50+ CGI parameters that were being passed, some of them dynamically generated, and almost all with very short names.

I wanted a way to organize the parameters, to make it easier to set up some simple guidelines for how to maintain parameters, and how to make sure they were accessable in a consistent manner. I decided to use a hierarchical, dot-delimited convention similar to what you seen in some programming languages. Now if I see a parameter like:


I can pretty quickly guess, after not looking at the code for days/weeks/months, that this value is somehow affecting the instructions on the Gbrowse navigation page. In my opinion, this is superior to:


which had the same effect in an earlier version of the code (negated logic :o).




Allen Day, <>


Copyright (C) 2004 by Allen Day

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.3 or, at your option, any later version of Perl 5 you may have available.



 Usage   : my $c = CGI::ParamComposite->new( populate => 1 , package => 'My::Param' );
           my @roots = $c->roots(); #these are what you're after
 Function: builds and returns a new CGI::ParamComposite object.  calls L</init()>,
           which is where all the action happens.
 Returns : a CGI::ParamComposite instance
 Args    : all optional:
             cgi         - a CGI object from which params() are retrieved.
             populate    - should the objects returned by L</roots()> be fleshed out?
                           defaults to false, this is fastest.
             package     - prefix to attach to new symbols.  see L</package()> for


 Usage   : $obj->init(%arg);
 Function: initializes a CGI::ParamComposite object.  this includes
           registration of new packages, package constructors, and
           package accessors into the Perl symbol table.
 Returns : true on success.
 Args    : none.  this is an internal method called by L</new()>.



 Usage   : $obj->cgi($newval)
 Function: holds a CGI instance.  this is instantiated by L</init()>,
           if you don't provide a value.
 Returns : value of cgi (a CGI object)
 Args    : on set, new value (a scalar or undef, optional)


 Usage   : $hashref = $obj->param($newval)
 Function: get a hahsref of the treeified CGI parameters
 Returns : a hashref
 Args    : none


You donn't need to touch these.


 Usage   : internal method, used for sorting CGI params based
           on the depth of their namespace.  this makes sure
           the created symbols return the right thing (child
           objects or simple scalars)


 Usage   : $obj->follow($value,$hashref,@path);
 Function: internal method.  recurses into $hashref foreach element of
           @path, and sets the value of $path[-1] to $value.  for

           @path  = qw(foo bar baz);
           $value  = 'boo';
           $result = {};
           $result->{foo}->{bar}->{baz}; #evaluates as 'boo'

 Returns : n/a
 Args    : 1. value to set
           2. hash to assign value into
           3. an array defining location of value in hash