| Data::URIEncode(3pm) | User Contributed Perl Documentation | Data::URIEncode(3pm) |
Data::URIEncode - Allow complex data structures to be encoded using flat URIs.
use Data::URIEncode qw(flat_to_complex complex_to_flat);
my $data = {
foo => {
bar => 'bing',
},
baz => [123],
};
my $flat = complex_to_flat($data);
my $query = complex_to_query($data);
# $flat looks like:
$flat = {
'foo.bar' => 'bing',
'baz:0' => 123,
};
# $query looks like:
$query = "foo.bar=bing&baz:0=123"
################################################
# put data back to how it was
$data = flat_to_complex($flat);
$data = query_to_complex($query);
################################################
### some html form somewhere
<form>
<input type="text" name="foo.bar.baz" value="brum">
<input type="text" name="bing:2" value="blang">
<input type="text" name="'key with :, ., and \''.red" value="blue">
</form>
### when the form is submitted to the following code
use CGI;
use Data::URIEncode qw(query_to_complex);
my $q = CGI->new;
my $data = query_to_complex($q);
### data will look like
$data = {
foo => {
bar => {
baz = "brum",
},
},
bing => [
undef,
undef,
"blang",
],
"key with :, ., and '" => {
red = "blue",
},
};
The world of the web works off of URI's. The Query string portion of URIs already support encoding of key/value paired data - they just don't natively allow for for complex data structures.
There are modules or encodings that do support arbitrarily complex data structures. JSON, YAML and Data::Dumper all have their own way of encoding complex structures. But then to pass them across the web, you usually still have to URL encode them and pass them via a form parameter.
Data::URIEncode allows for encoding and decoding complex (multi level datastructures) using native Query String manipulators (such as CGI.pm). It takes complex data and turns it into a flat hashref which can then be turned into a URI query string using URL encoding. It also takes a flat hashref of data passed in and translates it back to a complex structure.
One benefit of using Data::URIEncode is that a standard submission from a standard html form can automatically be translated into complex data even though it arrived in a "flat" form. This somewhat mimics the abilities of XForms without introducing the complexity of XForms.
Another benefit is that sparse data can be represented in a more compact form than JSON or YAML are able to provide. However, complex data with long key names will be more verbose as the full data hierarchy must be repeated for each value.
For each of the following rules, the $data can be translated to $flat and $query by calling complex_to_flat and complex_to_query respectively. The $flat and $query can be translated back into $data using flat_to_complex and query_to_complex respectively.
$data = {key => "val", key2 => "val2"};
$flat === {key => "val", key2 => "val2"};
$query eq "key=val&key2=val2"
$data = {key => {key2 => "val"}};
$flat === {"key.key2" => "val"};
$query eq "key.key2=val
########
$data = {foo => {bar => {baz => "bling"}}};
$flat === {"foo.bar.baz" = "bling"};
$query eq "foo.bar.baz=bling"
$data = {key => ["val1", "val2"]};
$flat === {"key:0" => "val1", "key:1" => "val2"};
$query eq "key:0=val1&key:1=val2"
########
$data = {key => [ [ ["val"] ] ]};
$flat === {"key:0:0" => "val"}
$query eq "key:0:0=val"
$data = ["val1", "val2"]
$flat === {":0" => "val1", ":1" => "val2"}
$query eq ":0=>val1&:1=>val2"
########
$data = [ [ ["val"] ] ];
$flat === {":0:0:0" => "val"}
$query eq ":0:0:0=val"
$query = ".foo=bar"
$flat = {".foo" => "bar"}
$data === {foo => "bar"}
$data = {"foo.bar" => "baz"}
$flat === {"'foo.bar'" => "baz"}
$query eq "'foo.bar'=baz" # the ' will be swapped with %27
########
$data = {"foo:bar" => "baz"}
$flat === {"'foo:bar'" => "baz"}
$query eq "'foo:bar'=baz" # the ' will be swapped with %27
########
$data = {"" => "baz"}
$flat === {"''" => "baz"}
$query eq "''=baz" # the ' will be swapped with %27
########
$data = {"'" => "baz"}
$flat === {"'\\''" => "baz"}
$query eq "'\\''=baz" # the ' will be swapped with %27 and the \ will be replaced with %5C
Single quotes were chosen as double quotes are most commonly used in HTML forms, thus allowing escaped single quotes more easily inside the double quoted name.
$data = {foo => undef, bar => 1}
$flat === {bar => 1}
$query eq "bar=1"
########
$data = ["val1", undef, "val2"]
$flat === {":0" => "val1", ":2" => "val2"}
$query eq ":0=val1&:2=val2"
$Data::URIEncode::DUMP_BLESSED_DATA = 1; # default
$data = {foo => bless({bar => "baz"}, "main"), one => "two"}
$flat === {"foo.bar" => "baz", one => "two"}
$query eq "foo.bar=baz&one=two"
########
$Data::URIEncode::DUMP_BLESSED_DATA = 0;
$data = {foo => bless({bar => "baz"}, "main"), one => "two"}
$flat === {one => "two"}
$query eq "one=two"
my $data = flat_to_complex({"foo.bar.baz:2" => "bling"});
# $data = {foo => {bar => {baz => [undef, undef, "bling"]}}};
my $flat = complex_to_flat({foo => ['a','b']});
# $flat = {"foo:0" => "a", "foo:1" => "b"});
my $str = complex_to_query({foo => ['a','b']});
# $str eq "foo:0=a&foo:1=b"
my $data = query_to_complex("foo.bar:0=baz");
my $data = query_to_complex(\ "foo.bar:0=baz");
my $data = query_to_complex({"foo.bar:0" => "baz"}); # same as flat_to_complex
my $cgi = CGI->new(\ "foo.bar:0=baz");
my $data = query_to_complex($cgi);
my $cgi = CGI->new; # use the values passed in from STDIN
my $data = query_to_complex($cgi);
Without this value, somebody could specify foo:1000000000000=bar and your server would attempt to set the 1000000000000th index of the foo value to bar.
The string "foo:101=bar" would die, but the string "foo:50=bar&foo:101=baz" would not die because the intermediate foo->[50] increments the foo arrayref by 51 and the subsequent foo->[101] call increments the foo arrayref by only 51.
Circular refs are not detected. Any attempt to dump a struture with cirular refs will result in an infinite loop. There is no immediate plan to add circular ref tracking.
All of the following have attempted to solve the same problem as Data::URIEncode. All of them (including Data::URIEncode) suffer from the problem of being hard to find for the specific purpose. Hash::Flatten is probably the only suitable replacement for Data::URIEncode.
Hash::Flatten
CGI::Expand
HTTP::Rollup
CGI::State
Paul Seamons perlspam at seamons dot com
This library may be distributed under the same terms as Perl itself.
| 2022-10-13 | perl v5.34.0 |