Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Expand(3)	      User Contributed Perl Documentation	     Expand(3)

NAME
       CGI::Expand - convert flat hash to nested data using TT2's dot
       convention

SYNOPSIS
	   use CGI::Expand ();
	   use CGI; # or Apache::Request, etc.

	   $args = CGI::Expand->expand_cgi( CGI->new('a.0=3&a.2=4&b.c.0=x') );

       Or, as an imported function for convenience:

	   use CGI::Expand;
	   use CGI; # or Apache::Request, etc.

	   $args = expand_cgi( CGI->new('a.0=3&a.2=4&b.c.0=x') );
	   # $args = { a => [3,undef,4], b => {	c => ['x'] }, }

	   # Or	to catch exceptions:
	   eval	{
	       $args = expand_cgi( CGI->new('a.0=3&a.2=4&b.c.0=x') );
	   } or	log_and_exit( $@ );

	   #-----
	   use CGI::Expand qw(expand_hash);

	   $args = expand_hash({'a.0'=>77}); # $args = { a => [	77 ] }

DESCRIPTION
       Converts	a CGI query into structured data using a dotted	name
       convention similar to TT2.

       "expand_cgi" works with CGI.pm, Apache::Request or anything with	an
       appropriate "param" method.  Or you can use "expand_hash" directly.

       If you prefer to	use a different	flattening convention then CGI::Expand
       can be subclassed.

MOTIVATION
       The Common Gateway Interface restricts parameters to name=value pairs,
       but often we'd like to use more structured data.	 This module uses a
       name encoding convention	to rebuild a hash of hashes, arrays and
       values.	Arrays can either be indexed explicitly	or from	CGI's multi-
       valued parameter	handling.

       The generic nature of this process means	that the core components of
       your system can remain CGI ignorant and operate on structured data.
       Better for modularity, better for testing.

DOT CONVENTION
       The key-value pair "a.b.1=hi" expands to	the perl structure:

	 { a =>	{ b => [ undef,	"hi" ] }

       The key ("a.b.1") specifies the location	at which the value ("hi") is
       stored.	The key	is split on '.'	characters, the	first segment ("a") is
       a key in	the top	level hash, subsequent segments	may be keys in sub-
       hashes or indices in sub-arrays.	 Integer segments are treated as array
       indices,	others as hash keys.

       Array size is limited to	100 by default.	 The limit can be altered by
       subclassing or using the	deprecated $Max_Array package variable.	 See
       below.

       The backslash '\' escapes the next character in cgi parameter names
       allowing	'.' , '\' and digits in	hash keys.  The	escaping '\' is
       removed.	 Values	are not	altered.

   Key-Value Examples
	 # HoHoL
	 a.b.1=hi ---> { a => {	b => [ undef, "hi" ] }

	 # HoLoH
	 a.1.b=hi ---> { a => [	undef, { b => "hi" } ] }

	 # top level always a hash
	 9.0=hi	  ---> { "9" =>	[ "hi" ] }

	 # can backslash escape	to treat digits	hash as	keys
	 a.\0=hi     ---> { "a"	=> { 0 => "hi"}	}

	 # or to put . and \ literals in keys
	 a\\b\.c=hi  ---  { 'a\\b\.c' => "hi" }

METHODS	/ FUNCTIONS
       The routines listed below are all methods, but can be imported to be
       called as functions.  In	other words, you can call
       "CGI::Expand->expand_hash(...)"	or you can import "expand_hash"	and
       then call "expand_hash(...)" without using method invocation syntax.

       "expand_cgi" is exported	by default. "expand_hash" and "collapse_hash"
       are exported upon request.

       expand_cgi
	       my $deep_hash = expand_cgi ( $CGI_object_or_similar );

	   Takes a CGI object and returns a hashref for	the expanded data
	   structure (or dies, see "EXCEPTIONS").

	   Wrapper around expand_hash that uses	the "param" method of the CGI
	   object to collect the names and values.

	   Handles multivalued parameters as array refs	(although they can't
	   be mixed with indexed arrays	and will have an undefined ordering).

	       $query =	'a.0=3&a.2=4&b.c.0=x&c.0=2&c.1=3&d=&e=1&e=2';

	       $args = expand_cgi( CGI->new($query) );

	       # result:
	       # $args = {
	       #   a =>	[3,undef,4],
	       #   b =>	{ c => ['x'] },
	       #   c =>	['2','3'],
	       #   d =>	'',
	       #   e =>	['1','2'], # order depends on CGI/etc
	       # };

       expand_hash
	       my $deep_hash = expand_hash( $flat_hash );

	   Expands the keys of the parameter hash according to the dot
	   convention (or dies,	see "EXCEPTIONS").

	       $args = expand_hash({ 'a.b.1' =>	[1,2] });
	       # $args = { a =>	{ b => [undef, [1,2] ] } }

       collapse_hash
	       my $flat_hash = collapse_hash( $deep_hash );

	   The inverse of expand_hash.	Converts the $deep_hash	data structure
	   back	into a flat hash.

	       $flat = collapse_hash({ a => { b	=> [undef, [1,2] ] } });
	       # $flat = { 'a.b.1.0' =>	1, 'a.b.1.1' =>	2 }

EXCEPTIONS
       WARNING:	The users of your site can cause these exceptions so you must
       decide how they are handled (possibly by	letting	the process die).

       "CGI param array	limit exceeded..."
	   If an array index exceeds the array limit (default: 100) then an
	   exception is	thrown.

       "CGI param clash	for..."
	   A cgi query like "a=1&a.b=1"	would require the value	of $args->{a}
	   to be both 1	and { b	=> 1 }.	 Such type inconsistencies are
	   reported as exceptions.  (See test.pl for for examples)

SUBCLASSING
       Subclassing in now the preferred	way to change the behaviour and
       defaults.  (Previously package variables	were used, see test.pl).

       The methods which may be	overridden by subclasses are separator,
       max_array, split_name and join_name.

       max_array
	       $subclass->max_Array;

	   The limit for the array size, defaults to 100.  The value 0 can be
	   used	to disable the use of arrays, everthing	is a hash key.

       separator
	       $subclass->separator;

	   Returns the separator characters used to split the keys of the flat
	   hash.  The default is '.' but multiple characters are allowed.  The
	   default join	will use the first character.

	   If there is no separator then '\' escaping does not occur.  This is
	   for use with	split_name and join_name below.

       split_name
	       my @segments = $subclass->split_name($name);

	   The split_name method must break $name in to	key segments for the
	   nested data structure.  The default version just splits on the
	   separator characters	with a bit of fiddling to handle escaping.

       join_name
	       my $name	= $subclass->join_name(@segments);

	   The inverse of split_name, joins the	segments back to the key for
	   the flat hash.  The default version uses the	first character	of the
	   string returned by the separator method.

DEPRECATIONS
       $CGI::Expand::Separator and $CGI::Expand::Max_Array are deprecated.
       They still work for now but emit	a warning (supressed with
       $CGI::Expand::BackCompat	= 1)

       Using the functions by their fully qualified names ceased to work at
       around version 1.04.  They're now class methods so just replace the
       last :: with ->.

LIMITATIONS
       The top level is	always a hash.	Consequently, any digit	only names
       will be keys in this hash rather	than array indices.

       Image inputs with name.x, name.y	coordinates are	ignored	as they	will
       class with the value for	name.

TODO
       Thing about ways	to keep	$cgi and the expanded version in sync

       Glob style parameters (with SCALAR, ARRAY and HASH slots) would resolve
       the type	clashes, probably no fun to use.  Look at using
       Template::Plugin::StringTree to avoid path clashes

SEE ALSO
       o   HTTP::Rollup	- Replaces CGI.pm completely, no list ordering.

       o   CGI::State -	Tied to	CGI.pm,	unclear	error checking

       o   Template::Plugin::StringTree

       o   Hash::Flatten - Pick	your delimiters

       o   http://template-toolkit.org/pipermail/templates/2002-January/002368.html

       o   There's a tiny and beautiful	reduce solution	somewhere on
	   perlmonks.

AUTHOR
       Brad Bowman <cgi-expand@bereft.net>

       Pod corrections:	Ricardo	Signes

COPYRIGHT
       Copyright (C) 2004-2013,	Brad Bowman.

LICENSE
       CGI::Expand is free software; you can redistribute it and/or modify it
       under the terms of either:

       a) the GNU General Public License as published by the Free Software
       Foundation; either version 1, or	(at your option) any later version, or

       b) the "Artistic	License" which comes with Perl.

       For more	details, see the full text of the licenses at
       <http://www.perlfoundation.org/artistic_license_1_0>, and
       <http://www.gnu.org/licenses/gpl-1.0.html>.

perl v5.32.0			  2014-04-24			     Expand(3)

NAME | SYNOPSIS | DESCRIPTION | MOTIVATION | DOT CONVENTION | METHODS / FUNCTIONS | EXCEPTIONS | SUBCLASSING | DEPRECATIONS | LIMITATIONS | TODO | SEE ALSO | AUTHOR | COPYRIGHT | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CGI::Expand&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help