oracular (3) Hash::Flatten.3pm.gz

NAME

       Hash::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