1Hash::Flatten(3)      User Contributed Perl Documentation     Hash::Flatten(3)
2
3
4

NAME

6       Hash::Flatten - flatten/unflatten complex data hashes
7

SYNOPSIS

9               # Exported functions
10               use Hash::Flatten qw(:all);
11               $flat_hash = flatten($nested_hash);
12               $nested_hash = unflatten($flat_hash);
13
14               # OO interface
15               my $o = new Hash::Flatten({
16                       HashDelimiter => '->',
17                       ArrayDelimiter => '=>',
18                       OnRefScalar => 'warn',
19               });
20               $flat_hash = $o->flatten($nested_hash);
21               $nested_hash = $o->unflatten($flat_hash);
22

DESCRIPTION

24       Converts back and forth between a nested hash structure and a flat hash
25       of delimited key-value pairs.  Useful for protocols that only support
26       key-value pairs (such as CGI and DBMs).
27
28   Functional interface
29       $flat_hash = flatten($nested_hash, \%options)
30           Reduces a nested data-structure to key-value form.  The top-level
31           container must be hashref.  For example:
32
33                   $nested = {
34                           'x' => 1,
35                           'y' => {
36                                   'a' => 2,
37                                   'b' => 3
38                           },
39                           'z' => [
40                                   'a', 'b', 'c'
41                           ]
42                   }
43
44                   $flat = flatten($nested);
45                   use Data::Dumper;
46                   print Dumper($flat);
47
48                   $VAR1 = {
49                           'y.a' => 2,
50                           'x' => 1,
51                           'y.b' => 3,
52                           'z:0' => 'a',
53                           'z:1' => 'b',
54                           'z:2' => 'c'
55                   };
56
57           The "\%options" hashref can be used to override the default
58           behaviour (see "OPTIONS").
59
60       $nested_hash = unflatten($flat_hash, \%options)
61           The unflatten() routine takes the flattened hash and returns the
62           original nested hash (see "CAVEATS" though).
63
64   OO interface
65       $o = new Hash::Flatten(\%options)
66           Options can be squirreled away in an object (see "OPTIONS")
67
68       $flat = $o->flatten($nested)
69           Flatten the structure using the options stored in the object.
70
71       $nested = $o->unflatten($flat)
72           Unflatten the structure using the options stored in the object.
73

OPTIONS

75       HashDelimiter and ArrayDelimiter
76           By default, hash dereferences are denoted by a dot, and array
77           dereferences are denoted by a colon. However you may change these
78           characters to any string you want, because you don't want there to
79           be any confusion as to which part of a string is the 'key' and
80           which is the 'delimiter'. You may use multicharacter strings if you
81           prefer.
82
83       OnRefScalar and OnRefRef and OnRefGlob
84           Behaviour if a reference of this type is encountered during
85           flattening.  Possible values are 'die', 'warn' (default behaviour
86           but warns) or a coderef which is passed the reference and should
87           return the flattened value.
88
89           By default references to references, and references to scalars, are
90           followed silently.
91
92       EscapeSequence
93           This is the character or sequence of characters that will be used
94           to escape the hash and array delimiters.  The default escape
95           sequence is '\\'. The escaping strategy is to place the escape
96           sequence in front of delimiter sequences; the escape sequence
97           itself is escaped by replacing it with two instances.
98
99       DisableEscapes
100           Stop the escaping from happening.  No escape sequences will be
101           added to flattened output, nor interpreted on the way back.
102
103           WARNING: If your structure has keys that contain the delimiter
104           characters, it will not be possible to unflatten the structure
105           correctly.
106

CAVEATS

108       Any blessings will be discarded during flattening, so that if you
109       flatten an object you must re-bless() it on unflattening.
110
111       Note that there is no delimiter for scalar references, or references to
112       references.  If your structure to be flattened contains scalar, or
113       reference, references these will be followed by default, i.e.  "'foo'
114       => \\\\\\$foo" will be collapsed to "'foo' => $foo".  You can override
115       this behaviour using the OnRefScalar and OnRefRef constructor option.
116
117       Recursive structures are detected and cause a fatal error.
118

SEE ALSO

120       The perlmonks site has a helpful introduction to when and why you might
121       want to flatten a hash:
122       http://www.perlmonks.org/index.pl?node_id=234186
123
124       CGI::Expand
125           Unflattens hashes using "." as a delimiter, similar to
126           Template::Toolkit's behaviour.
127
128       Tie::MultiDim
129           This provides a tie interface to unflattening a data structure if
130           you specify a "template" for the structure of the data.
131
132       MLDBM
133           This also provides a tie interface but reduces a nested structure
134           to key-value form by serialising the values below the top level.
135

VERSION

137       $Id: Flatten.pm,v 1.19 2009/05/09 12:42:02 jamiel Exp $
138

AUTHOR

140       John Alden & P Kent <cpan _at_ bbc _dot_ co _dot_ uk>
141

COPYRIGHT

143       (c) BBC 2005. This program is free software; you can redistribute it
144       and/or modify it under the GNU GPL.
145
146       See the file COPYING in this distribution, or
147       http://www.gnu.org/licenses/gpl.txt
148
149
150
151perl v5.38.0                      2023-07-20                  Hash::Flatten(3)