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

FreeBSD Manual Pages


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

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

	   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 ] }

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

       "expand_cgi" works with, 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.

       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.

       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

       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" }

       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.

	       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
	       # };

	       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] ] } }

	       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 }

       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 for for examples)

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

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


	   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.


	   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.

	       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.

	       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.

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

       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.

       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

       o   HTTP::Rollup	- Replaces completely, no list ordering.

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

       o   Template::Plugin::StringTree

       o   Hash::Flatten - Pick	your delimiters


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

       Brad Bowman <>

       Pod corrections:	Ricardo	Signes

       Copyright (C) 2004-2013,	Brad Bowman.

       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
       <>, and

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


Want to link to this manual page? Use this URL:

home | help