Expand(3pm)

📦
version 2.05 · 6 versions
, in ubuntu resolute, ubuntu stonking

💅 Expand(3pm) — the CGI::Expand era 💅

okay bestie, sit down, hydrate, because this is the User Contributed Perl Documentation page for a module that turns flat query strings into actual, structured, gorgeous nested data. it's giving architecture. it's giving modularity. and yes, i'm obsessed. 🦋

✨ 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 (aka the lazy girlie route, we respect it):

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 ✨

So basically it converts a CGI query into structured data using a dotted name convention that's similar to TT2. main character behavior honestly.

expand_cgi works with CGI.pm, Apache::Request, or literally anything that has a fitting param method. ✨ or you can just go straight to expand_hash if that's your vibe.

and if you'd rather use a different flattening convention? no problem, bestie, CGI::Expand can be subclassed. customize away. 💅

✨ MOTIVATION ✨

The Common Gateway Interface restricts parameters to name=value pairs 😭 which is so restrictive of it. but often we want more structured data. this module uses a name encoding convention to rebuild a hash of hashes, arrays, and values. arrays can be indexed explicitly, or they can come from CGI's multi-valued parameter handling. either way, we slay. 🎀

The generic nature of this whole process means the core components of your system can stay CGI ignorant and just operate on structured data. better for modularity, better for testing. periodt. 👑

✨ DOT CONVENTION ✨

The key-value pair a.b.1=hi expands to this perl structure:

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

The key (a.b.1) specifies the location where the value (hi) gets stored. the key is split on . characters, the first segment (a) is a key in the top level hash, and subsequent segments can be keys in sub-hashes or indices in sub-arrays. integer segments get treated as array indices, everything else as hash keys. iykyk.

Array size is limited to 100 by default. the limit can be altered by subclassing, or by using the deprecated $Max_Array package variable (see below, we'll get there 🫶).

The backslash \ escapes the next character in cgi parameter names, which lets you put ., \ and digits inside hash keys. the escaping \ gets 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 you can import them to be called as functions. in other words, you can call CGI::Expand->expand_hash(...), or you can import expand_hash and then just call expand_hash(...) without the method invocation syntax. whichever feels right for your era. ✨

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 it dies — see "EXCEPTIONS", and yes, dying is a whole mood but you gotta be ready for it 💀).

It's a wrapper around expand_hash that uses the param method of the CGI object to collect the names and values.

It handles multivalued parameters as array refs (although heads up bestie, they can't be mixed with indexed arrays and they'll 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 — again, 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. reversible queen behavior. 👑

$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 get handled (possibly by just letting the process die). this is not a drill, bestie, real ones plan for this. 😭
  • "CGI param array limit exceeded..." — if an array index exceeds the array limit (default: 100), an exception gets 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 — yes, that double "for" is exactly how it's written in the original, and honestly? iconic typo energy. 💅)

✨ SUBCLASSING ✨

Subclassing is 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 entirely — then everthing is a hash key. (that "everthing" is verbatim, and no, we're not fixing it. it's part of the lore now. 🫶)

🦋 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 into 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 they emit a warning (supressed with $CGI::Expand::BackCompat = 1 — and yes, that's "supressed", verbatim, we keep the typos, we keep the lore).

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 ->. glow up moment. 💅

✨ 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, since they will class with the value for name. (again: "class", not "clash". verbatim. immortalized. 🎀)

✨ 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

(and yeah, "Thing about ways" — that's exactly what the original says and we are NOT touching it, it's perfect as-is 😭)

✨ SEE ALSO ✨

✨ AUTHOR ✨

Brad Bowman <cgi-expand@bereft.net>

Pod corrections: Ricardo Signes

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

and that's the whole page bestie, no notes, no skipping, every single detail intact. 🫶 this one's from the perl v5.40.1 girlies and it's dated 2025-08-14 — so go forth, expand some hashes, and stay iconic. 💖✨🌈

📦 where this page comes from