Data-URIEncode-0.11/ 0000755 0001750 0001750 00000000000 10604240777 012552 5 ustar paul paul Data-URIEncode-0.11/MANIFEST 0000644 0001750 0001750 00000000260 10604240754 013674 0 ustar paul paul Changes
lib/Data/URIEncode.pm
Makefile.PL
MANIFEST This list of files
README
t/00_uri_encode.t
META.yml Module meta-data (added by MakeMaker)
Data-URIEncode-0.11/lib/ 0000755 0001750 0001750 00000000000 10604240777 013320 5 ustar paul paul Data-URIEncode-0.11/lib/Data/ 0000755 0001750 0001750 00000000000 10604240777 014171 5 ustar paul paul Data-URIEncode-0.11/lib/Data/URIEncode.pm 0000644 0001750 0001750 00000036376 10573371676 016333 0 ustar paul paul package Data::URIEncode;
=head1 NAME
Data::URIEncode - Allow complex data structures to be encoded using flat URIs.
=cut
use strict;
use base qw(Exporter);
use vars qw($VERSION
@EXPORT_OK
$MAX_ARRAY_EXPAND
$DUMP_BLESSED_DATA
$qr_chunk
$qr_chunk_quoted
);
BEGIN {
$VERSION = '0.11';
@EXPORT_OK = qw(flat_to_complex complex_to_flat query_to_complex complex_to_query);
$MAX_ARRAY_EXPAND = 100;
$DUMP_BLESSED_DATA = 1 if ! defined $DUMP_BLESSED_DATA;
$qr_chunk = "([^.:]*)";
$qr_chunk_quoted = "'((?:[^']*|\\\\')+)(?[$name]) {
$ref->[$name] = $sep eq ':' ? [] : {};
}
die "Can't use $name as index value for an array while unfolding $key"
if $name !~ /^\d+$/;
die "Can't expand array in $key by more than $MAX_ARRAY_EXPAND"
if $name - $#$ref > $MAX_ARRAY_EXPAND;
$ref = $ref->[$name];
$name = $next;
} elsif (ref $ref eq 'HASH') {
if (! exists $ref->{$name}) {
$ref->{$name} = $sep eq ':' ? [] : {};
}
$ref = $ref->{$name};
$name = $next;
} else {
die "Unknown type during unfold of $key";
}
if ($sep eq ':') {
die "Can't coerce hash into array near \"$name\" while unfolding $key"
if ref $ref eq 'HASH';
} else {
die "Can't coerce array into hash near \"$name\" while unfolding $key"
if ref $ref eq 'ARRAY';
}
}
if (ref $ref eq 'HASH') {
$ref->{$name} = $in->{$key};
} elsif (ref $ref eq 'ARRAY') {
die "Can't use $name as index value for an array while unfolding $key"
if $name !~ /^\d+$/;
die "Can't expand array in $key by more than $MAX_ARRAY_EXPAND"
if $name - $#$ref > $MAX_ARRAY_EXPAND;
$ref->[$name] = $in->{$key};
} else {
die "Can't unfold $key at level $name (scalar value exists)";
}
}
return $out->{'root'};
}
###----------------------------------------------------------------###
sub complex_to_flat {
my $in = shift;
my $out = shift || {};
my $prefix = shift;
$prefix = '' if ! defined $prefix;
if (UNIVERSAL::isa($in, 'ARRAY')) {
die "Not handling blessed ARRAY" if ref $in ne 'ARRAY' && ! $DUMP_BLESSED_DATA;
foreach my $i (0 .. $#$in) {
if (ref $in->[$i]) {
complex_to_flat($in->[$i], $out, "$prefix:"._flatten_escape($i));
} elsif (defined $in->[$i] || $i == $#$in) {
my $key = "$prefix:"._flatten_escape($i);
$key =~ s/^\.//; # leading . is not necessary (it is the default)
$out->{$key} = $in->[$i];
}
}
} elsif (UNIVERSAL::isa($in, 'HASH')) {
die "Not handling blessed HASH" if ref $in ne 'HASH' && ! $DUMP_BLESSED_DATA;
foreach my $key (keys %$in) {
my $val = $in->{$key};
if (ref $val) {
complex_to_flat($val, $out, "$prefix."._flatten_escape($key));
} else {
$key = "$prefix."._flatten_escape($key);
$key =~ s/^\.//; # leading . is not necessary (it is the default)
$out->{$key} = $val;
}
}
} else {
die "Need a hash or array" if ! defined $in;
die "Not sure how to handle that type ($in)";
}
return $out;
}
sub _flatten_escape {
my $val = shift;
return undef if ! defined $val;
return "''" if ! length $val;
return $val if $val !~ /[.:\']/;
$val =~ s/\'/\\\'/g;
return "'".$val."'";
}
###----------------------------------------------------------------###
sub complex_to_query {
my $flat = complex_to_flat(@_);
return join "&", map {
my $key = $_;
my $val = $flat->{$_};
foreach ($key, $val) {
$_ = '' if ! defined;
s/([^\w.\-\ \:])/sprintf('%%%02X', ord $1)/eg;
y/ /+/;
}
"$key=$val";
} sort keys %$flat;
}
sub query_to_complex {
my $q;
my $str = shift;
if (! ref $str) { # normal string
return {} if ! defined $str || ! length $str;
require CGI;
$q = CGI->new(\$str);
} elsif (ref $str eq 'SCALAR') { # ref to a string
return {} if ! defined $$str || ! length $$str;
require CGI;
$q = CGI->new($str);
} elsif (ref $str eq 'HASH') { # passed a data hash instead
return flat_to_complex($str);
} elsif (UNIVERSAL::can($str, 'param')) { # CGI looking object
$q = $str;
} else {
die "Not sure how to handle \"$str\" - should pass a string, ref to a string, a hashref, or a CGI compatible object";
}
my %hash = ();
foreach my $key ($q->param) {
my @val = $q->param($key);
$hash{$key} = ($#val <= 0) ? $val[0] : \@val;
}
return flat_to_complex(\%hash);
}
###----------------------------------------------------------------###
1;
__END__
=head1 SYNOPSIS
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
### 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",
},
};
=head1 DESCRIPTION
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.
=head1 RULES
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.
=over 4
=item Simple values stay simple
$data = {key => "val", key2 => "val2"};
$flat === {key => "val", key2 => "val2"};
$query eq "key=val&key2=val2"
=item Nested hashes use a dot to modify the key.
$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"
=item Nested arrays use a colon to modify the key.
$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"
=item Data structures can have an arrayref as the top level
A leading colon is used to indicate the top level node is an
arrayref.
$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"
=item Keys in flat hashrefs MAY begin with a leading dot
A leading dot may disambiguate some cases.
$query = ".foo=bar"
$flat = {".foo" => "bar"}
$data === {foo => "bar"}
=item Single quotes may be used to enclose complex strings.
Any key containing a colon ":", a dot ".", or a single quote "'"
must be quoted with single quotes and have enclosed single quotes escaped.
$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.
=item Undefined values are not included in the flattened data
$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"
=item Blessed hashes and arrayrefs are dumped by default.
Changing the default value of the global $DUMP_BLESSED_DATA variable changes
the behavior.
$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"
=item Arrays created by flat_to_complex and query_to_complex must
obey the value of the $MAX_ARRAY_EXPAND variable.
=back
=head1 FUNCTIONS
=over 4
=item flat_to_complex
Takes a hashref of simple key value pairs. Returns a data structure based
on the the parsed key value pairs. The parsing proceeds according to the
rules listed in RULES.
my $data = flat_to_complex({"foo.bar.baz:2" => "bling"});
# $data = {foo => {bar => {baz => [undef, undef, "bling"]}}};
=item complex_to_flat
Takes a complex data structure and turns it into a flat hashref (single level
key/value pairs only). The parsing proceeds according to the rules listed in
RULES.
my $flat = complex_to_flat({foo => ['a','b']});
# $flat = {"foo:0" => "a", "foo:1" => "b"});
=item complex_to_query
Similar to complex_to_flat, except that the flattened hashref is then translated
into query string suitable for use in a URI.
my $str = complex_to_query({foo => ['a','b']});
# $str eq "foo:0=a&foo:1=b"
=item query_to_complex
Takes one of a string, a reference to a string, a hash, or a CGI.pm compatible object
and translates it into a complex data structure. Similar to flat_to_complex, exempt
that a first step is taken to access the query parameters from the CGI compatible object
or string. If a string or string ref is given, the CGI module is used to parse the string
into an initial flat hash of key value pairs (using the param method). If another module
is desired over, CGI.pm you must initialize it with the data to be parsed prior to passing
the object to the query_to_complex function.
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);
=back
=head1 VARIABLES
=over 4
=item C<$MAX_ARRAY_EXPAND>
Default value is 100. This variable is used to determine how large
flat_to_complex will allow an array to be expanded beyond its current size.
An array can grow as large as you have memory, but intermediate values must
exist.
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.
=item C<$DUMP_BLESSED_DATA>
Default is true. If true, blessed hashrefs and arrayrefs will also be added to the
flat data returned by complex_to_flat. If false, bless hashrefs and arrayrefs will be
skipped.
=back
=head1 BUGS
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.
=head1 SEE ALSO
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.
L
L
L
L
=head1 AUTHOR
Paul Seamons perlspam at seamons dot com
=head1 LICENSE
This library may be distributed under the same terms as Perl itself.
=cut
Data-URIEncode-0.11/META.yml 0000644 0001750 0001750 00000000473 10604240777 014027 0 ustar paul paul # http://module-build.sourceforge.net/META-spec.html
#XXXXXXX This is a prototype!!! It will change in the future!!! XXXXX#
name: Data-URIEncode
version: 0.11
version_from: lib/Data/URIEncode.pm
installdirs: site
requires:
distribution_type: module
generated_by: ExtUtils::MakeMaker version 6.30_01
Data-URIEncode-0.11/t/ 0000755 0001750 0001750 00000000000 10604240777 013015 5 ustar paul paul Data-URIEncode-0.11/t/00_uri_encode.t 0000644 0001750 0001750 00000023142 10517223107 015606 0 ustar paul paul # -*- Mode: Perl; -*-
=head1 NAME
00_uri_encode.t - Test the uri_encode funcionality
=cut
use strict;
use Test::More tests => 104;
use_ok("Data::URIEncode", qw(flat_to_complex complex_to_flat query_to_complex complex_to_query));
my $data;
my $out;
$data = {
"foo:2" => "bar",
"foo:5" => "bing",
};
ok(($out = flat_to_complex($data)), 'Ran flat_to_complex');
ok($out->{"foo"}->[2] eq "bar", "foo.2");
ok($out->{"foo"}->[5] eq "bing", "foo.5");
ok(! defined $out->{"foo"}->[4], "foo.4");
ok(flat_to_complex({"foo" => "a"})->{"foo"} eq "a", "key: (foo)");
ok(flat_to_complex({"0" => "a"})->{"0"} eq "a", "key: (0)");
ok(flat_to_complex({"foo.bar.baz" => "a"})->{"foo"}{"bar"}{baz} eq "a", "key: (foo.bar.baz)");
ok(flat_to_complex({"foo:0" => "a"})->{"foo"}->[0] eq "a", "key: (foo:0)");
ok(flat_to_complex({"foo:0:2" => "a"})->{"foo"}->[0]->[2] eq "a", "key: (foo:0:2)");
ok(flat_to_complex({"foo.0" => "a"})->{"foo"}->{"0"} eq "a", "key: (foo.0)");
ok(flat_to_complex({"foo.0.2" => "a"})->{"foo"}->{"0"}{"2"} eq "a", "key: (foo.0.2)");
ok(flat_to_complex({"foo." => "a"})->{"foo"}->{""} eq "a", "key: (foo.)");
ok(flat_to_complex({"foo.''" => "a"})->{"foo"}->{""} eq "a", "key: (foo.'')");
ok(flat_to_complex({".foo" => "a"})->{"foo"} eq "a", "key: (.foo)");
ok(flat_to_complex({"''.foo" => "a"})->{""}->{"foo"} eq "a", "key: (''.foo)");
ok(flat_to_complex({"..foo" => "a"})->{""}->{"foo"} eq "a", "key: (..foo)");
ok(flat_to_complex({".''.foo" => "a"})->{""}->{"foo"} eq "a", "key: (.''.foo)");
ok(flat_to_complex({"foo..bar" => "a"})->{"foo"}{""}{"bar"} eq "a", "key: (foo..bar)");
ok(flat_to_complex({" " => "a"})->{" "} eq "a", "key: ( )");
ok(flat_to_complex({" . " => "a"})->{" "}->{" "} eq "a", "key: ( . )");
ok(flat_to_complex({" . . " => "a"})->{" "}->{" "}->{" "} eq "a", "key: ( . . )");
ok(flat_to_complex({"foo.'.'" => "a"})->{"foo"}->{"."} eq "a", "key: (foo.'.')");
ok(flat_to_complex({"'.'.foo" => "a"})->{"."}->{"foo"} eq "a", "key: ('.'.foo)");
ok(flat_to_complex({"'.'" => "a"})->{"."} eq "a", "key: ('.')");
ok(flat_to_complex({"'.'.'.'" => "a"})->{"."}->{"."} eq "a", "key: ('.'.'.')");
ok(flat_to_complex({"'.'.'.'.'.'" => "a"})->{"."}->{"."}->{"."} eq "a", "key: ('.'.'.'.'.')");
ok(flat_to_complex({"'\\'\\''" => "a"})->{"''"} eq "a", "key: ('\\'\\'')");
ok(flat_to_complex({"''" => "a"})->{""} eq "a", "key: ('')");
ok(flat_to_complex({"" => "a"})->{""} eq "a", "key: ()");
ok(flat_to_complex({":3" => "a"})->[3] eq "a", "key: (:3)");
ok(flat_to_complex({".foo" => "a"})->{"foo"} eq "a", "key: (.foo)");
ok(flat_to_complex({".foo.bar.baz" => "a"})->{"foo"}{"bar"}{baz} eq "a", "key: (.foo.bar.baz)");
ok(flat_to_complex({".foo:0" => "a"})->{"foo"}->[0] eq "a", "key: (.foo:0)");
ok(flat_to_complex({".foo:0:2" => "a"})->{"foo"}->[0]->[2] eq "a", "key: (.foo:0:2)");
ok(flat_to_complex({".foo.0" => "a"})->{"foo"}->{"0"} eq "a", "key: (.foo.0)");
ok(flat_to_complex({".foo.0.2" => "a"})->{"foo"}->{"0"}{"2"} eq "a", "key: (.foo.0.2)");
ok(flat_to_complex({".foo." => "a"})->{"foo"}->{""} eq "a", "key: (.foo.)");
ok(flat_to_complex({".''.foo" => "a"})->{""}->{"foo"} eq "a", "key: (.''.foo)");
ok(flat_to_complex({".foo..bar" => "a"})->{"foo"}{""}{"bar"} eq "a", "key: (.foo..bar)");
ok(flat_to_complex({". " => "a"})->{" "} eq "a", "key: (. )");
ok(flat_to_complex({". . " => "a"})->{" "}->{" "} eq "a", "key: (. . )");
ok(flat_to_complex({". . . " => "a"})->{" "}->{" "}->{" "} eq "a", "key: (. . . )");
ok(flat_to_complex({".foo.'.'" => "a"})->{"foo"}->{"."} eq "a", "key: (.foo.'.')");
ok(flat_to_complex({".'.'.foo" => "a"})->{"."}->{"foo"} eq "a", "key: (.'.'.foo)");
ok(flat_to_complex({"'.'.foo" => "a"})->{"."}->{"foo"} eq "a", "key: ('.'.foo)");
ok(flat_to_complex({".'.'" => "a"})->{"."} eq "a", "key: (.'.')");
ok(flat_to_complex({".'.'.'.'" => "a"})->{"."}->{"."} eq "a", "key: (.'.'.'.')");
ok(flat_to_complex({".'.'.'.'.'.'" => "a"})->{"."}->{"."}->{"."} eq "a", "key: (.'.'.'.'.'.')");
ok(flat_to_complex({".'\\'\\''" => "a"})->{"''"} eq "a", "key: (.'\\'\\'')");
ok(flat_to_complex({".'.:\\''" => "a"})->{".:'"} eq "a", "key: (.'.:\\'')");
ok(flat_to_complex({".''" => "a"})->{""} eq "a", "key: (.'')");
ok(flat_to_complex({"." => "a"})->{""} eq "a", "key: (.)");
ok(! eval { flat_to_complex({".1" => "a", ":1" => "a" }) }, "Can't coerce ($@)");
ok(! eval { flat_to_complex({"foo.1" => "a", "foo:1" => "a"}) }, "Can't coerce ($@)");
ok(! eval { flat_to_complex({"foo.1" => "a", "'foo':1"=>"a"}) }, "Can't coerce ($@)");
ok(! eval { flat_to_complex({"foo:10000" => "a"}) }, "Couldn't run - too big ($@)");
ok(! eval { flat_to_complex({"foo" => "a", "foo.a" => "a"}) }, "Couldn't run - overlap of keys ($@)");
ok(! eval { flat_to_complex({"foo:1" => "a", "foo:a" => "a"}) }, "Couldn't run - using a for index ($@)");
ok(! eval { flat_to_complex({"foo:a" => "a" }) }, "Couldn't run - using a for index ($@)");
ok(! eval { flat_to_complex({":a" => "a" }) }, "Couldn't run - using a for index ($@)");
ok(complex_to_flat({"foo" => "a" })->{"foo"} eq "a", "key: (foo)");
ok(complex_to_flat({"0" => "a" })->{"0"} eq "a", "key: (0)");
ok(complex_to_flat({"foo" => {"bar" => "a"} })->{"foo.bar"} eq "a", "key: (foo.bar)");
ok(complex_to_flat({"foo" => {bar=>{baz=>"a"}} })->{"foo.bar.baz"} eq "a", "key: (foo.bar.baz)");
ok(complex_to_flat({"foo" => ["a"] })->{"foo:0"} eq "a", "key: (foo:0)");
ok(complex_to_flat({"foo" => [[0,1,"a"]] })->{"foo:0:2"} eq "a", "key: (foo:0:2)");
ok(complex_to_flat({"foo" => {"0" => "a"} })->{"foo.0"} eq "a", "key: (foo.0)");
ok(complex_to_flat({"foo" => {"0"=>{"2"=>"a"}} })->{"foo.0.2"} eq "a", "key: (foo.0.2)");
ok(complex_to_flat({"foo" => {"" => "a"} })->{"foo.''"} eq "a", "key: (foo.'')");
ok(complex_to_flat({"" => {"foo" => "a"} })->{"''.foo"} eq "a", "key: (''.foo)");
ok(complex_to_flat({"foo" => {""=>{"bar"=>"a"}}})->{"foo.''.bar"} eq "a", "key: (foo.''.bar)");
ok(complex_to_flat({" " => "a" })->{" "} eq "a", "key: ( )");
ok(complex_to_flat({" " => {" " => "a"} })->{" . "} eq "a", "key: ( . )");
ok(complex_to_flat({" " => {" " =>{" "=>"a"}}})->{" . . "} eq "a", "key: ( . . )");
ok(complex_to_flat({"foo" => {"." => "a"} })->{"foo.'.'"} eq "a", "key: (foo.'.')");
ok(complex_to_flat({"." => {"foo" => "a"} })->{"'.'.foo"} eq "a", "key: ('.'.foo)");
ok(complex_to_flat({"." => "a" })->{"'.'"} eq "a", "key: ('.')");
ok(complex_to_flat({"." => {"." => "a"} })->{"'.'.'.'"} eq "a", "key: ('.'.'.')");
ok(complex_to_flat({"." => {"."=>{"."=> "a"}}})->{"'.'.'.'.'.'"} eq "a", "key: ('.'.'.'.'.')");
ok(complex_to_flat({"''" => "a" })->{"'\\'\\''"} eq "a", "key: ('\\'\\'')");
ok(complex_to_flat({"" => "a" })->{"''"} eq "a", "key: ('')");
ok(complex_to_flat([0, 1, 2, "a" ])->{":3"} eq "a", "key: (:3)");
Foo: {
local $Data::URIEncode::DUMP_BLESSED_DATA;
$Data::URIEncode::DUMP_BLESSED_DATA = 0;
ok(! eval { complex_to_flat(bless [], "main") }, 'Couldn"t flatten: ($@)');
ok(! eval { complex_to_flat(bless {}, "main") }, 'Couldn"t flatten: ($@)');
};
ok(! eval { complex_to_flat(sub {}) }, 'Couldn"t flatten: ($@)');
ok(! eval { complex_to_flat(undef) }, 'Couldn"t flatten: ($@)');
ok(! eval { complex_to_flat("undef") }, 'Couldn"t flatten: ($@)');
ok(complex_to_query(["a","b"]) eq ":0=a&:1=b", ":0=a&:1=b");
ok(complex_to_query({"a","b"}) eq "a=b", "a=b");
ok(complex_to_query({x => {y => ["a","b"], z => 1}}) eq "x.y:0=a&x.y:1=b&x.z=1", "x.y:0=a&x.y:1=b&x.z=1");
SKIP: {
skip('No CGI found', 9) if ! eval { require CGI };
ok(query_to_complex(":0=a&:1=b" )->[1] eq "b", "str: :0=a&:1=b");
ok(query_to_complex("a=b" )->{"a"} eq "b", "str: a=b");
ok(query_to_complex("x.y:0=a&x.y:1=b&x.z=1")->{"x"}->{"y"}->[1] eq "b", "str: x.y:0=a&x.y:1=b&x.z=1");
ok(query_to_complex(\ ":0=a&:1=b" )->[1] eq "b", "str ref: :0=a&:1=b");
ok(query_to_complex(\ "a=b" )->{"a"} eq "b", "str ref: a=b");
ok(query_to_complex(\ "x.y:0=a&x.y:1=b&x.z=1")->{"x"}->{"y"}->[1] eq "b", "str ref: x.y:0=a&x.y:1=b&x.z=1");
ok(query_to_complex(CGI->new(\ ":0=a&:1=b" ))->[1] eq "b", "CGI->new: :0=a&:1=b");
ok(query_to_complex(CGI->new(\ "a=b" ))->{"a"} eq "b", "CGI->new: a=b");
ok(query_to_complex(CGI->new(\ "x.y:0=a&x.y:1=b&x.z=1"))->{"x"}->{"y"}->[1] eq "b", "CGI->new: x.y:0=a&x.y:1=b&x.z=1");
};
ok(query_to_complex({":0" => "a", ":1" => "b"} )->[1] eq "b", "hashref: :0=a&:1=b");
ok(query_to_complex({"a" => "b"} )->{"a"} eq "b", "hashref: a=b");
ok(query_to_complex({"x.y:0" =>"a", "x.y:1" => "b", "x.z" => "1"})->{"x"}->{"y"}->[1] eq "b", "hashref: x.y:0=a&x.y:1=b&x.z=1");
ok(! eval { query_to_complex([]) }, 'Blew up - not a known type to deal with');
Data-URIEncode-0.11/Changes 0000644 0001750 0001750 00000000356 10573371766 014061 0 ustar paul paul 0.11 * Fix bug in array expansion in flat_to_complex
* Use foreach keys instead of while each to avoid non-reset on some data types.
0.10 2006-10-23
* Initial release - from the URLEncode library of the YAR project.
Data-URIEncode-0.11/README 0000644 0001750 0001750 00000025155 10573371703 013441 0 ustar paul paul NAME
Data::URIEncode - Allow complex data structures to be encoded using flat
URIs.
SYNOPSIS
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
### 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",
},
};
DESCRIPTION
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.
RULES
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.
Simple values stay simple
$data = {key => "val", key2 => "val2"};
$flat === {key => "val", key2 => "val2"};
$query eq "key=val&key2=val2"
Nested hashes use a dot to modify the key.
$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"
Nested arrays use a colon to modify the key.
$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 structures can have an arrayref as the top level
A leading colon is used to indicate the top level node is an
arrayref.
$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"
Keys in flat hashrefs MAY begin with a leading dot
A leading dot may disambiguate some cases.
$query = ".foo=bar"
$flat = {".foo" => "bar"}
$data === {foo => "bar"}
Single quotes may be used to enclose complex strings.
Any key containing a colon ":", a dot ".", or a single quote "'"
must be quoted with single quotes and have enclosed single quotes
escaped.
$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.
Undefined values are not included in the flattened data
$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"
Blessed hashes and arrayrefs are dumped by default.
Changing the default value of the global $DUMP_BLESSED_DATA variable
changes the behavior.
$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"
Arrays created by flat_to_complex and query_to_complex must obey the
value of the $MAX_ARRAY_EXPAND variable.
FUNCTIONS
flat_to_complex
Takes a hashref of simple key value pairs. Returns a data structure
based on the the parsed key value pairs. The parsing proceeds
according to the rules listed in RULES.
my $data = flat_to_complex({"foo.bar.baz:2" => "bling"});
# $data = {foo => {bar => {baz => [undef, undef, "bling"]}}};
complex_to_flat
Takes a complex data structure and turns it into a flat hashref
(single level key/value pairs only). The parsing proceeds according
to the rules listed in RULES.
my $flat = complex_to_flat({foo => ['a','b']});
# $flat = {"foo:0" => "a", "foo:1" => "b"});
complex_to_query
Similar to complex_to_flat, except that the flattened hashref is
then translated into query string suitable for use in a URI.
my $str = complex_to_query({foo => ['a','b']});
# $str eq "foo:0=a&foo:1=b"
query_to_complex
Takes one of a string, a reference to a string, a hash, or a CGI.pm
compatible object and translates it into a complex data structure.
Similar to flat_to_complex, exempt that a first step is taken to
access the query parameters from the CGI compatible object or
string. If a string or string ref is given, the CGI module is used
to parse the string into an initial flat hash of key value pairs
(using the param method). If another module is desired over, CGI.pm
you must initialize it with the data to be parsed prior to passing
the object to the query_to_complex function.
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);
VARIABLES
$MAX_ARRAY_EXPAND
Default value is 100. This variable is used to determine how large
flat_to_complex will allow an array to be expanded beyond its
current size. An array can grow as large as you have memory, but
intermediate values must exist.
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.
$DUMP_BLESSED_DATA
Default is true. If true, blessed hashrefs and arrayrefs will also
be added to the flat data returned by complex_to_flat. If false,
bless hashrefs and arrayrefs will be skipped.
BUGS
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.
SEE ALSO
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
AUTHOR
Paul Seamons perlspam at seamons dot com
LICENSE
This library may be distributed under the same terms as Perl itself.
Data-URIEncode-0.11/Makefile.PL 0000644 0001750 0001750 00000002102 10520033647 014510 0 ustar paul paul use ExtUtils::MakeMaker;
###----------------------------------------------------------------###
# Copyright 2003 - Paul Seamons #
# Distributed under the GNU General Public License without warranty #
###----------------------------------------------------------------###
WriteMakefile(
NAME => "Data::URIEncode",
AUTHOR => "Paul Seamons",
ABSTRACT_FROM => "lib/Data/URIEncode.pm",
VERSION_FROM => "lib/Data/URIEncode.pm",
INSTALLDIRS => 'site',
dist => {
DIST_DEFAULT => 'all tardist',
COMPRESS => 'gzip -vf',
SUFFIX => '.gz',
},
clean => {
FILES => '*~',
},
realclean => {
FILES => '*~',
},
);
package MY;
sub postamble {
return qq^
pm_to_blib: README
README: \$(VERSION_FROM)
pod2text \$(VERSION_FROM) > README
^;
}
1;