.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Hash::Flatten 3pm" .TH Hash::Flatten 3pm "2018-01-28" "perl v5.26.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Hash::Flatten \- flatten/unflatten complex data hashes .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& # 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 => \*(Aq\->\*(Aq, \& ArrayDelimiter => \*(Aq=>\*(Aq, \& OnRefScalar => \*(Aqwarn\*(Aq, \& }); \& $flat_hash = $o\->flatten($nested_hash); \& $nested_hash = $o\->unflatten($flat_hash); .Ve .SH "DESCRIPTION" .IX Header "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 \s-1CGI\s0 and DBMs). .SS "Functional interface" .IX Subsection "Functional interface" .ie n .IP "$flat_hash = flatten($nested_hash, \e%options)" 4 .el .IP "\f(CW$flat_hash\fR = flatten($nested_hash, \e%options)" 4 .IX Item "$flat_hash = flatten($nested_hash, %options)" Reduces a nested data-structure to key-value form. The top-level container must be hashref. For example: .Sp .Vb 10 \& $nested = { \& \*(Aqx\*(Aq => 1, \& \*(Aqy\*(Aq => { \& \*(Aqa\*(Aq => 2, \& \*(Aqb\*(Aq => 3 \& }, \& \*(Aqz\*(Aq => [ \& \*(Aqa\*(Aq, \*(Aqb\*(Aq, \*(Aqc\*(Aq \& ] \& } \& \& $flat = flatten($nested); \& use Data::Dumper; \& print Dumper($flat); \& \& $VAR1 = { \& \*(Aqy.a\*(Aq => 2, \& \*(Aqx\*(Aq => 1, \& \*(Aqy.b\*(Aq => 3, \& \*(Aqz:0\*(Aq => \*(Aqa\*(Aq, \& \*(Aqz:1\*(Aq => \*(Aqb\*(Aq, \& \*(Aqz:2\*(Aq => \*(Aqc\*(Aq \& }; .Ve .Sp The \f(CW\*(C`\e%options\*(C'\fR hashref can be used to override the default behaviour (see \*(L"\s-1OPTIONS\*(R"\s0). .ie n .IP "$nested_hash = unflatten($flat_hash, \e%options)" 4 .el .IP "\f(CW$nested_hash\fR = unflatten($flat_hash, \e%options)" 4 .IX Item "$nested_hash = unflatten($flat_hash, %options)" The \fIunflatten()\fR routine takes the flattened hash and returns the original nested hash (see \*(L"\s-1CAVEATS\*(R"\s0 though). .SS "\s-1OO\s0 interface" .IX Subsection "OO interface" .ie n .IP "$o = new Hash::Flatten(\e%options)" 4 .el .IP "\f(CW$o\fR = new Hash::Flatten(\e%options)" 4 .IX Item "$o = new Hash::Flatten(%options)" Options can be squirreled away in an object (see \*(L"\s-1OPTIONS\*(R"\s0) .ie n .IP "$flat = $o\->flatten($nested)" 4 .el .IP "\f(CW$flat\fR = \f(CW$o\fR\->flatten($nested)" 4 .IX Item "$flat = $o->flatten($nested)" Flatten the structure using the options stored in the object. .ie n .IP "$nested = $o\->unflatten($flat)" 4 .el .IP "\f(CW$nested\fR = \f(CW$o\fR\->unflatten($flat)" 4 .IX Item "$nested = $o->unflatten($flat)" Unflatten the structure using the options stored in the object. .SH "OPTIONS" .IX Header "OPTIONS" .IP "HashDelimiter and ArrayDelimiter" 4 .IX Item "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. .IP "OnRefScalar and OnRefRef and OnRefGlob" 4 .IX Item "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. .Sp By default references to references, and references to scalars, are followed silently. .IP "EscapeSequence" 4 .IX Item "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 '\e\e'. 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. .IP "DisableEscapes" 4 .IX Item "DisableEscapes" Stop the escaping from happening. No escape sequences will be added to flattened output, nor interpreted on the way back. .Sp \&\fB\s-1WARNING:\s0\fR If your structure has keys that contain the delimiter characters, it will not be possible to unflatten the structure correctly. .SH "CAVEATS" .IX Header "CAVEATS" Any blessings will be discarded during flattening, so that if you flatten an object you must re\-\fIbless()\fR it on unflattening. .PP 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. \&\f(CW\*(C`\*(Aqfoo\*(Aq => \e\e\e\e\e\e$foo\*(C'\fR will be collapsed to \&\f(CW\*(C`\*(Aqfoo\*(Aq => $foo\*(C'\fR. You can override this behaviour using the OnRefScalar and OnRefRef constructor option. .PP Recursive structures are detected and cause a fatal error. .SH "SEE ALSO" .IX Header "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 .IP "CGI::Expand" 4 .IX Item "CGI::Expand" Unflattens hashes using \*(L".\*(R" as a delimiter, similar to Template::Toolkit's behaviour. .IP "Tie::MultiDim" 4 .IX Item "Tie::MultiDim" This provides a tie interface to unflattening a data structure if you specify a \*(L"template\*(R" for the structure of the data. .IP "\s-1MLDBM\s0" 4 .IX Item "MLDBM" This also provides a tie interface but reduces a nested structure to key-value form by serialising the values below the top level. .SH "VERSION" .IX Header "VERSION" \&\f(CW$Id:\fR Flatten.pm,v 1.19 2009/05/09 12:42:02 jamiel Exp $ .SH "AUTHOR" .IX Header "AUTHOR" John Alden & P Kent .SH "COPYRIGHT" .IX Header "COPYRIGHT" (c) \s-1BBC 2005.\s0 This program is free software; you can redistribute it and/or modify it under the \s-1GNU GPL.\s0 .PP See the file \s-1COPYING\s0 in this distribution, or http://www.gnu.org/licenses/gpl.txt