/ 
CGI-ParamComposite-0.011
River stage zero No dependents
/ CGI::ParamComposite

NAME

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

SYNOPSIS

use CGI;
use CGI::ParamComposite;
my $q = CGI->new();
my $c = CGI::ParamComposite->new( populate => 0 , cgi => $q );

#Dumper([$composite->roots()]) returns (minor formatting):
$VAR1 = [
   bless( {}, 'CGI::ParamComposite' )
];


my $c = CGI::ParamComposite->new( populate => 1 , cgi => $q , package => 'market');

#Dumper([$composite->roots()]) returns (minor formatting):
$VAR1 = [
  bless( {
    'food' => bless( {
      'market::food::meat' => [
        'pork',
        'beef',
        'fish'
      ],
      'market::food::vegetable' => [
        'tomato',
        'spinach'
      ]
    }, 'market::food' )
  }, 'market' )
];

#either way, these calls now work:
my($market) = $composite->roots();
ref($market);                                       #returns "market"
ref($market->food);                                 #returns "market::food"
join(', ', map {ref($_)} $market->food->children(); #returns "market::food::meat, market::food::vegetable"

DESCRIPTION

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:

/my.cgi?gbrowse.param.navigation.instructions=1

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:

/my.cgi?ins=0

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

SEE ALSO

CGI, Symbol

AUTHOR

Allen Day, <allenday@ucla.edu>

COPYRIGHT AND LICENSE

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.

METHODS

new()

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

init()

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

ACCESSORS

cgi()

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)

package()

Usage   : $obj->package($newval)
Function: base package to use for composite's subclasses,
          for instance if package was 'Foo::Bar', and
          CGI::ParamComposite received the CGI parameter
          string:

            "baz.boo=1;bad.boo=2"

          packages "Foo::Bar::baz" and "Foo::Bar::boo" would
          be created (each with a boo() method).

          the value defaults to "CGI::ParamComposite" for
          safety reasons.
Returns : value of package (a scalar)
Args    : on set, new value (a scalar or undef, optional)

populate()

Usage   : $obj->populate($boolean)
Function: determines whether or not daughters of the root-level
          nodes are populated when a new object is built.  defaults
          to false.  objects/values are still accessible, but not
          pre-created for you (so a Data::Dumper::Dumper() on 
          CGI::ParamComposite->roots() won't tell you much, for
          instance.
Returns : value of populate (a boolean)
Args    : on set, new value (a boolean or undef, optional)

roots()

Usage   : $obj->roots()
Function: call this to get the top-level composite objects.  call children()
          on each of these (recursively) to get the child objects.
Returns : value of roots (a list of objects)
Args    : none

INTERNAL METHODS

You donn't need to touch these.

packit()

Usage   : internal method, creates a package new() constructor

slotit()

Usage   : internal method, creates a package get/set accessor

depth()

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)

treeit()

Usage   : internal method, used to recursively fill slots
          when L</populate()> returns a true value.