|
NAMECGI::Expand - convert flat hash to nested data using TT2's dot conventionSYNOPSISuse 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 ] } DESCRIPTIONConverts 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. MOTIVATIONThe 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 CONVENTIONThe 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 / FUNCTIONSThe 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.
EXCEPTIONSWARNING: The users of your site can cause these exceptions so you must decide how they are handled (possibly by letting the process die).
SUBCLASSINGSubclassing 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.
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 ->. LIMITATIONSThe 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. TODOThing about ways to keep $cgi and the expanded version in syncGlob 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
AUTHORBrad Bowman <cgi-expand@bereft.net>Pod corrections: Ricardo Signes COPYRIGHTCopyright (C) 2004-2013, Brad Bowman.LICENSECGI::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>.
Visit the GSP FreeBSD Man Page Interface. |