Hash::Flatten(3) User Contributed Perl Documentation Hash::Flatten(3)NAMEHash::Flatten - flatten/unflatten complex data hashes
SYNOPSIS
# Exported functions
use Hash::Flatten qw(:all);
$flat_hash = flatten($nested_hash);
$nested_hash = unflatten($flat_hash);
# OO interface
my $o = new Hash::Flatten({
HashDelimiter => '->',
ArrayDelimiter => '=>',
OnRefScalar => 'warn',
});
$flat_hash = $o->flatten($nested_hash);
$nested_hash = $o->unflatten($flat_hash);
DESCRIPTION
Converts back and forth between a nested hash structure and a flat hash
of delimited key-value pairs. Useful for protocols that only support
key-value pairs (such as CGI and DBMs).
Functional interface
$flat_hash = flatten($nested_hash, \%options)
Reduces a nested data-structure to key-value form. The top-level
container must be hashref. For example:
$nested = {
'x' => 1,
'y' => {
'a' => 2,
'b' => 3
},
'z' => [
'a', 'b', 'c'
]
}
$flat = flatten($nested);
use Data::Dumper;
print Dumper($flat);
$VAR1 = {
'y.a' => 2,
'x' => 1,
'y.b' => 3,
'z:0' => 'a',
'z:1' => 'b',
'z:2' => 'c'
};
The "\%options" hashref can be used to override the default
behaviour (see "OPTIONS").
$nested_hash = unflatten($flat_hash, \%options)
The unflatten() routine takes the flattened hash and returns the
original nested hash (see "CAVEATS" though).
OO interface
$o = new Hash::Flatten(\%options)
Options can be squirreled away in an object (see "OPTIONS")
$flat = $o->flatten($nested)
Flatten the structure using the options stored in the object.
$nested = $o->unflatten($flat)
Unflatten the structure using the options stored in the object.
OPTIONS
HashDelimiter and ArrayDelimiter
By default, hash dereferences are denoted by a dot, and array
dereferences are denoted by a colon. However you may change these
characters to any string you want, because you don't want there to
be any confusion as to which part of a string is the 'key' and
which is the 'delimiter'. You may use multicharacter strings if you
prefer.
OnRefScalar and OnRefRef and OnRefGlob
Behaviour if a reference of this type is encountered during
flattening. Possible values are 'die', 'warn' (default behaviour
but warns) or a coderef which is passed the reference and should
return the flattened value.
By default references to references, and references to scalars, are
followed silently.
EscapeSequence
This is the character or sequence of characters that will be used
to escape the hash and array delimiters. The default escape
sequence is '\\'. The escaping strategy is to place the escape
sequence in front of delimiter sequences; the escape sequence
itself is escaped by replacing it with two instances.
DisableEscapes
Stop the escaping from happening. No escape sequences will be
added to flattened output, nor interpreted on the way back.
WARNING: If your structure has keys that contain the delimiter
characters, it will not be possible to unflatten the structure
correctly.
CAVEATS
Any blessings will be discarded during flattening, so that if you
flatten an object you must re-bless() it on unflattening.
Note that there is no delimiter for scalar references, or references to
references. If your structure to be flattened contains scalar, or
reference, references these will be followed by default, i.e. "'foo'
=> \\\\\\$foo" will be collapsed to "'foo' => $foo". You can override
this behaviour using the OnRefScalar and OnRefRef constructor option.
Recursive structures are detected and cause a fatal error.
SEE ALSO
The perlmonks site has a helpful introduction to when and why you might
want to flatten a hash:
http://www.perlmonks.org/index.pl?node_id=234186
CGI::Expand
Unflattens hashes using "." as a delimiter, similar to
Template::Toolkit's behaviour.
Tie::MultiDim
This provides a tie interface to unflattening a data structure if
you specify a "template" for the structure of the data.
MLDBM
This also provides a tie interface but reduces a nested structure
to key-value form by serialising the values below the top level.
VERSION
$Id: Flatten.pm,v 1.19 2009/05/09 12:42:02 jamiel Exp $
AUTHOR
John Alden & P Kent <cpan _at_ bbc _dot_ co _dot_ uk>
COPYRIGHT
(c) BBC 2005. This program is free software; you can redistribute it
and/or modify it under the GNU GPL.
See the file COPYING in this distribution, or
http://www.gnu.org/licenses/gpl.txt
perl v5.14.1 2010-09-24 Hash::Flatten(3)
