.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Expand 3pm" .TH Expand 3pm "2022-10-13" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CGI::Expand \- convert flat hash to nested data using TT2's dot convention .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use CGI::Expand (); \& use CGI; # or Apache::Request, etc. \& \& $args = CGI::Expand\->expand_cgi( CGI\->new(\*(Aqa.0=3&a.2=4&b.c.0=x\*(Aq) ); .Ve .PP Or, as an imported function for convenience: .PP .Vb 2 \& use CGI::Expand; \& use CGI; # or Apache::Request, etc. \& \& $args = expand_cgi( CGI\->new(\*(Aqa.0=3&a.2=4&b.c.0=x\*(Aq) ); \& # $args = { a => [3,undef,4], b => { c => [\*(Aqx\*(Aq] }, } \& \& # Or to catch exceptions: \& eval { \& $args = expand_cgi( CGI\->new(\*(Aqa.0=3&a.2=4&b.c.0=x\*(Aq) ); \& } or log_and_exit( $@ ); \& \& #\-\-\-\-\- \& use CGI::Expand qw(expand_hash); \& \& $args = expand_hash({\*(Aqa.0\*(Aq=>77}); # $args = { a => [ 77 ] } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Converts a \s-1CGI\s0 query into structured data using a dotted name convention similar to \s-1TT2.\s0 .PP \&\f(CW\*(C`expand_cgi\*(C'\fR works with \s-1CGI\s0.pm, Apache::Request or anything with an appropriate \*(L"param\*(R" method. Or you can use \f(CW\*(C`expand_hash\*(C'\fR directly. .PP If you prefer to use a different flattening convention then CGI::Expand can be subclassed. .SH "MOTIVATION" .IX Header "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 \s-1CGI\s0's multi-valued parameter handling. .PP The generic nature of this process means that the core components of your system can remain \s-1CGI\s0 ignorant and operate on structured data. Better for modularity, better for testing. .SH "DOT CONVENTION" .IX Header "DOT CONVENTION" The key-value pair \*(L"a.b.1=hi\*(R" expands to the perl structure: .PP .Vb 1 \& { a => { b => [ undef, "hi" ] } .Ve .PP The key (\*(L"a.b.1\*(R") specifies the location at which the value (\*(L"hi\*(R") is stored. The key is split on '.' characters, the first segment (\*(L"a\*(R") 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. .PP Array size is limited to 100 by default. The limit can be altered by subclassing or using the deprecated \f(CW$Max_Array\fR package variable. See below. .PP The backslash '\e' escapes the next character in cgi parameter names allowing '.' , '\e' and digits in hash keys. The escaping \&'\e' is removed. Values are not altered. .SS "Key-Value Examples" .IX Subsection "Key-Value Examples" .Vb 2 \& # 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.\e0=hi \-\-\-> { "a" => { 0 => "hi"} } \& \& # or to put . and \e literals in keys \& a\e\eb\e.c=hi \-\-\- { \*(Aqa\e\eb\e.c\*(Aq => "hi" } .Ve .SH "METHODS / FUNCTIONS" .IX Header "METHODS / FUNCTIONS" The routines listed below are all methods, but can be imported to be called as functions. In other words, you can call \f(CW\*(C`CGI::Expand\->expand_hash(...)\*(C'\fR or you can import \f(CW\*(C`expand_hash\*(C'\fR and then call \f(CW\*(C`expand_hash(...)\*(C'\fR without using method invocation syntax. .PP \&\f(CW\*(C`expand_cgi\*(C'\fR is exported by default. \f(CW\*(C`expand_hash\*(C'\fR and \f(CW\*(C`collapse_hash\*(C'\fR are exported upon request. .IP "expand_cgi" 4 .IX Item "expand_cgi" .Vb 1 \& my $deep_hash = expand_cgi ( $CGI_object_or_similar ); .Ve .Sp Takes a \s-1CGI\s0 object and returns a hashref for the expanded data structure (or dies, see \*(L"\s-1EXCEPTIONS\*(R"\s0). .Sp Wrapper around expand_hash that uses the \*(L"param\*(R" method of the \s-1CGI\s0 object to collect the names and values. .Sp Handles multivalued parameters as array refs (although they can't be mixed with indexed arrays and will have an undefined ordering). .Sp .Vb 1 \& $query = \*(Aqa.0=3&a.2=4&b.c.0=x&c.0=2&c.1=3&d=&e=1&e=2\*(Aq; \& \& $args = expand_cgi( CGI\->new($query) ); \& \& # result: \& # $args = { \& # a => [3,undef,4], \& # b => { c => [\*(Aqx\*(Aq] }, \& # c => [\*(Aq2\*(Aq,\*(Aq3\*(Aq], \& # d => \*(Aq\*(Aq, \& # e => [\*(Aq1\*(Aq,\*(Aq2\*(Aq], # order depends on CGI/etc \& # }; .Ve .IP "expand_hash" 4 .IX Item "expand_hash" .Vb 1 \& my $deep_hash = expand_hash( $flat_hash ); .Ve .Sp Expands the keys of the parameter hash according to the dot convention (or dies, see \*(L"\s-1EXCEPTIONS\*(R"\s0). .Sp .Vb 2 \& $args = expand_hash({ \*(Aqa.b.1\*(Aq => [1,2] }); \& # $args = { a => { b => [undef, [1,2] ] } } .Ve .IP "collapse_hash" 4 .IX Item "collapse_hash" .Vb 1 \& my $flat_hash = collapse_hash( $deep_hash ); .Ve .Sp The inverse of expand_hash. Converts the \f(CW$deep_hash\fR data structure back into a flat hash. .Sp .Vb 2 \& $flat = collapse_hash({ a => { b => [undef, [1,2] ] } }); \& # $flat = { \*(Aqa.b.1.0\*(Aq => 1, \*(Aqa.b.1.1\*(Aq => 2 } .Ve .SH "EXCEPTIONS" .IX Header "EXCEPTIONS" \&\fB\s-1WARNING\s0\fR: The \fIusers\fR of your site can cause these exceptions so you must decide how they are handled (possibly by letting the process die). .ie n .IP """\s-1CGI\s0 param array limit exceeded...""" 4 .el .IP "``\s-1CGI\s0 param array limit exceeded...''" 4 .IX Item "CGI param array limit exceeded..." If an array index exceeds the array limit (default: 100) then an exception is thrown. .ie n .IP """\s-1CGI\s0 param clash for...""" 4 .el .IP "``\s-1CGI\s0 param clash for...''" 4 .IX Item "CGI param clash for..." A cgi query like \*(L"a=1&a.b=1\*(R" would require the value of \f(CW$args\fR\->{a} to be both 1 and { b => 1 }. Such type inconsistencies are reported as exceptions. (See test.pl for for examples) .SH "SUBCLASSING" .IX Header "SUBCLASSING" Subclassing in now the preferred way to change the behaviour and defaults. (Previously package variables were used, see test.pl). .PP The methods which may be overridden by subclasses are separator, max_array, split_name and join_name. .IP "max_array" 4 .IX Item "max_array" .Vb 1 \& $subclass\->max_Array; .Ve .Sp 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. .IP "separator" 4 .IX Item "separator" .Vb 1 \& $subclass\->separator; .Ve .Sp 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. .Sp If there is no separator then '\e' escaping does not occur. This is for use with split_name and join_name below. .IP "split_name" 4 .IX Item "split_name" .Vb 1 \& my @segments = $subclass\->split_name($name); .Ve .Sp The split_name method must break \f(CW$name\fR 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. .IP "join_name" 4 .IX Item "join_name" .Vb 1 \& my $name = $subclass\->join_name(@segments); .Ve .Sp 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. .SH "DEPRECATIONS" .IX Header "DEPRECATIONS" \&\f(CW$CGI::Expand::Separator\fR and \f(CW$CGI::Expand::Max_Array\fR are deprecated. They still work for now but emit a warning (supressed with \&\f(CW$CGI::Expand::BackCompat\fR = 1) .PP 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 \->. .SH "LIMITATIONS" .IX Header "LIMITATIONS" The top level is always a hash. Consequently, any digit only names will be keys in this hash rather than array indices. .PP Image inputs with name.x, name.y coordinates are ignored as they will class with the value for name. .SH "TODO" .IX Header "TODO" Thing about ways to keep \f(CW$cgi\fR and the expanded version in sync .PP Glob style parameters (with \s-1SCALAR, ARRAY\s0 and \s-1HASH\s0 slots) would resolve the type clashes, probably no fun to use. Look at using Template::Plugin::StringTree to avoid path clashes .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 HTTP::Rollup \- Replaces \s-1CGI\s0.pm completely, no list ordering. .IP "\(bu" 4 CGI::State \- Tied to \s-1CGI\s0.pm, unclear error checking .IP "\(bu" 4 Template::Plugin::StringTree .IP "\(bu" 4 Hash::Flatten \- Pick your delimiters .IP "\(bu" 4 http://template\-toolkit.org/pipermail/templates/2002\-January/002368.html .IP "\(bu" 4 There's a tiny and beautiful reduce solution somewhere on perlmonks. .SH "AUTHOR" .IX Header "AUTHOR" Brad Bowman .PP Pod corrections: Ricardo Signes .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 2004\-2013, Brad Bowman. .SH "LICENSE" .IX Header "LICENSE" CGI::Expand is free software; you can redistribute it and/or modify it under the terms of either: .PP a) the \s-1GNU\s0 General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or .PP b) the \*(L"Artistic License\*(R" which comes with Perl. .PP For more details, see the full text of the licenses at , and .