NAME

Data::Dumper::Limited - Vastly faster subset of Data::Dumper functionality

SYNOPSIS

  use Data::Dumper::Limited qw(DumpLimited);
  print DumpLimited($your_structure);

DESCRIPTION

This is an experimental module. The interface may change without notice. Before using it in production, please get in touch with the authors!

Think of Data::Dumper::Limited as supporting a subset of the data structures and features of Data::Dumper. The output is still valid Perl, so you can abuse eval STRING for deserialization. Alternatively, you can choose to use Data::Undump, which is a couple of orders of magnitude faster than eval and does not have the same security implications. Did we mention that this module dumps over 10x faster than Data::Dumper (similar to JSON::XS in our benchmarks)?

The power of this module is very similar to that of generating JSON, except it can dump scalar references, dumps top-level non-references (JSON must be an array or hash ref on the outside), and, again, is valid Perl. Furthermore, this module can optionally dump plain Perl object using bless() function calls. Since this can be unsafe, it needs to be explicitly enabled.

Repeated sub-references are detected, as are cyclic references. Repeated sub-structures are simply serialized multiple times -- they do not round-trip as repeated sub-structures. Since that is at least somewhat dubious, you can set an option that will make DumpLimited throw an exception when encountering repeated sub-structures. Cyclic references currently always cause the module to throw an exception as they are not supported.

EXPORTABLE FUNCTIONS

DumpLimited($structure, $options)

This function will return a string that represents the serialization of the first parameter to the function. Optionally, the second parameter can be a hash reference that contains any one of several options, see below.

Available options (as hash keys in the options hash reference):

undef_blessed

Boolean, defaults to false. Instead of dying on blessed references, simply emit undef.

objects_as_unblessed

Boolean, defaults to false. Instead of dying on blessed references, simply serialize them as unblessed references.

dump_objects

Boolean, defaults to false. Instead of dying on blessed references, serialize them properly including a call to bless(). Does not include logic for loading thusly referenced modules. That is by design. In the future, this might accept a list of acceptable class names to bless into.

disallow_multi

Boolean, defaults to false. If set, the module will refuse to serialize common sub-structures and throw and exception instead (eg. [\$x, \$x].

The options undef_blessed, objects_as_unblessed, and dump_objects are mutually exclusive and trying to set more than one of them will yield an exception.

SEE ALSO

The original Data::Dumper.

Data::Undump implements the efficient deserialization for this format (minus objects).

JSON::XS contains some excellent code that is very similar to the code in this module for a reason: It solves a similar problem and we included much of the code structure from JSON::XS. Thank you, Marc, for writing great software.

AUTHOR

Steffen Mueller <smueller@cpan.org>

Yves Orton <demerphq@gmail.com>

Some inspiration and code was taken from Marc Lehmann's excellent JSON::XS module due to obvious overlap in problem domain.

COPYRIGHT AND LICENSE

Copyright (C) 2012, 2013 by Steffen Mueller

Except portions taken from Marc Lehmann's code for the JSON::XS module. The license for JSON::XS is the same as for this module:

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.