CGI::ParamComposite.3pm

Langue: en

Version: 2004-10-10 (mandriva - 01/05/08)

Section: 3 (Bibliothèques de fonctions)

Sommaire

NAME

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

SYNOPSIS

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

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

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

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

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

AUTHOR

Allen Day, <allenday@ucla.edu> 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)

param()

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

INTERNAL METHODS

You donn't need to touch these.

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)

follow()

  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
            example:
 
 

            @path  = qw(foo bar baz);
            $value  = 'boo';
            $result = {};
            follow($value,$result,@path);
            $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