NAME

Data::Structure::Util - Change nature of data within a structure

SYNOPSIS

  use Data::Structure::Util qw(has_utf8 utf8_off utf8_on unbless get_blessed get_refs has_circular_ref circular_off signature);

  $data = {
            key1 => 'hello',
            key2 => bless({}, 'Foo'),
          };
  $data->{key3} = \$data;

  utf8_off($data) if has_utf8($data);

  $objs = get_blessed($data);
  unbless($data) if @$objs;

  die "Found a circular reference!" if has_circular_ref($data);

DESCRIPTION

Data::Structure::Util is a toolbox to manipulate data inside a data structure. It can parse an entire tree and perform the operation requested on each appropriate element. It can transform to utf8 any string within a data structure. I can attempts to transform any utf8 string back to default encoding either. It can remove the blessing on any reference. It can collect all the objects or detect if there is a circular reference.

It is written in C for decent speed.

FUNCTIONS

has_utf8($var)

Returns $var if there is a utf8 (as noted by perl) string anywhere within $var. Returns undef if no utf8 string has been found.

utf8_off($var)

Attempts to decode from utf8 any string within $var. Returns $var. If successful, the resulting string will not not be flagged as utf8.

utf8_on($var)

Encode to utf8 any string within $var. Returns $var. The resulting string will flagged as utf8.

_utf8_off($var)

Switch off the utf8 flag on any string within $var. This the same than _utf8_off of Encode but applies to any string within $var.

_utf8_on($var)

Switch on the utf8 flag on any string within $var. This the same than _utf8_on of Encode but applies to any string within $var.

unbless($ref)

Remove the blessing from any object found wihtin the date structure referenced by $ref

get_blessed($ref)

Returns an array ref of all objects within the data structure. The data structure is parsed deep first, so the top most objects should be the last elements of the array.

get_refs($ref)

Decomposes the data structure by returning an array ref of all references within. The data structure is parsed deep first, so the top most references should be the last elements of the array.

has_circular_ref($ref)

If a circular reference is detected, it returns the reference to an element composing the circuit. Returns false if no circular reference is detected. If the version of perl enables weaken references, these are skipped and are not reported as part of a circular reference.

Example:

  if ($circular_ref = has_circular_ref($ref)) {
    warn "Got a circular reference " . Dumper($circular_ref) .
         "You can use 'weaken' from Scalar::Util module to break it";
  }

circular_off($ref)

Weaken any reference part of a circular reference in an attempt to break it. Returns the number of references newly weaken.

signature($ref)

Returns a md5 of the $ref. Any change in the structure should change the signature. It examines the structure, addresses, value types and flags to generate the signature.

Example:

  $ref1 = { key1 => [] };
  $ref2 = $ref1;
  $ref2->{key1} = [];

signature($ref1) and signature($ref2) will be different, even if they look the same using Data::Dumper;

SEE ALSO

Encode, Scalar::Util, Devel::Leak, Devel::LeakTrace

See the excellent article http://www.perl.com/pub/a/2002/08/07/proxyobject.html from Matt Sergeant for more info on circular references

The development version of this module and others can be found at http://opensource.fotango.com/cgi-bin/viewcvs.cgi/trunk/

BUGS

  Using perl 5.8.0, there is a pathological case where circular_off will fail, I don't know why yet:
  my $obj8 = [];
  $obj8->[0] = \$obj8;
  circular_off($obj8); # Will throw an error

  signature() is sensitive to the hash randomisation algorithm

THANKS TO

James Duncan and Arthur Bergman who helped me and found a name for this module. Leon Brocard and Richard Clamp have provided invaluable help to debug this module.

AUTHOR

Pierre Denis <pdenis@fotango.com>

http://opensource.fotango.com/

COPYRIGHT

Copyright 2003, 2004 Fotango - All Rights Reserved.

This module is released under the same license as Perl itself.