Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Hash::Flatten(3)      User Contributed Perl Documentation     Hash::Flatten(3)

       Hash::Flatten - flatten/unflatten complex data hashes

	       # 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);

       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.

       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

       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.

	   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.

	   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

       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.

       The perlmonks site has a	helpful	introduction to	when and why you might
       want to flatten a hash:

	   Unflattens hashes using "." as a delimiter, similar to
	   Template::Toolkit's behaviour.

	   This	provides a tie interface to unflattening a data	structure if
	   you specify a "template" for	the structure of the data.

	   This	also provides a	tie interface but reduces a nested structure
	   to key-value	form by	serialising the	values below the top level.

       $Id:,v 1.19 2009/05/09 12:42:02 jamiel Exp $

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

       (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

perl v5.32.0			  2010-09-24		      Hash::Flatten(3)


Want to link to this manual page? Use this URL:

home | help