Name

Data::Undump::PPI - Perl extension for limited undumping of data structures (via PPI, not eval)

Synopsis

use Data::Dumper;
use Data::Undump::PPI;             # "Undump()" is exported by default
$Data::Dumper::Purity=1;           # should always be turned on for Undump

my @input = ( {foo=>"bar"}, ["Hello","World"], "undumping!" );
my $str = Dumper(@input);          # dump the data structure to a string
my @parsed = Undump($str);         # parse the data structure back out
# @parsed now looks identical to @input (is a deep copy)

use Data::Undump::PPI qw/Dump Undump/;      # additionally import "Dump()"
Dump(\@input, file=>'/tmp/test.conf');      # Data::Dumper to file
my @conf = Undump(file=>'/tmp/test.conf');  # Undump directly from file

Description

This module allows for limited undumping and round-tripping of data structures from strings generated by Data::Dumper (and possibly other dumper modules, but that's currently not explicitly supported). It is a thin wrapper around Config::Perl, so please see Config::Perl for more details, including the limitations.

When using Data::Dumper, make sure to always turn on its Purity option and turn off its Terse option, as otherwise Data::Dumper may produce code that may not evaluate back to the same data structure, sometimes even though it's valid, parseable Perl! See also "Dump" for a helper function.

Undump

my @out = Undump($string);
my @out = Undump(file => $filename);
my @out = Undump(fh => $filehandle);

Accepts either a string, a filename or a filehandle, parses it and attempts to return the data as it would have been passed to Data::Dumper's Dumper. This means that the $VAR1, $VAR2 etc. variable names generated by Dumper will be removed and the argument list passed to Dumper(...) is returned, and if the string ends on a true value, that will be ignored so that parsing files which end on e.g. 1;, like those generated by the "Dump" helper function, will work.

In list context, this function returns the list of values as they would have been passed as the arguments to Dumper(...). If you know that the data contains only one value, you may call Undump in scalar context to get that value. If you call Undump in scalar context but the data contains more than one value, currently the last value is returned and a warning is issued (in the "Config::Perl" warnings category).

If the string doesn't look like the output of Data::Dumper, this function will throw an exception, and any errors from Config::Perl's parse_or_die will also be passed through.

If you used Data::Dumper's ability to give the dumped variables user-specified names, you will need to use Config::Perl to parse that, since Undump only supports the $VAR... style output of Dumper.

This function is exported by default.

Dump

my $str = Dump(\@data);
Dump(\@data, file => $filename);
Dump(\@data, fh => $filehandle);
Dump(\@data, ..., %dumper_options);  # e.g.:
Dump(\@data, file => $filename, Deepcopy=>1);

This function is a simple helper for Data::Dumper which sets some default options and always returns a string, optionally writing that string to a file or filehandle.

The Data::Dumper options that can be set are: Deepcopy (default: off), Useqq (default: on), Quotekeys (default: off), Sortkeys (default: on), and Indent (default is Data::Dumper's default). Note that Terse is always off and Purity is always on.

When writing to a file, the output is prefixed with #!perl and ended with 1;, this is not the case when writing to a filehandle.

More Details

This module aims to support most of Data::Dumper's features except code references and (currently) blessed objects. If you find a Data::Dumper data structure that this module does not yet support, please feel free to send in your data structure, as it can help extend Config::Perl's features and help fix bugs. Currently, using modules other than Data::Dumper may not work, for example, Data::Dump sometimes generates code with the .. range operator, which is currently not supported by Config::Perl. In the future, this module's features may be extended to more fully support dumper modules like Data::Dump as well.

Although Config::Perl now supports self-referential data structures, you can also use Data::Dumper's Deepcopy option to get rid of references within data structures, if the loss of references and copying of data is acceptable for your application.

This module is part of the Config::Perl distribution, but was named separately in an attempt to make its purpose more clear and its name a little easier to remember.

This document describes version 0.06 of the module. Although this module has a fair number of tests, it still lacks some features (see Config::Perl) and there may be bugs lurking. Contributions are welcome!

Author, Copyright, and License

Copyright (c) 2015 Hauke Daempfling (haukex@zero-g.net).

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

For more information see the Perl Artistic License, which should have been distributed with your copy of Perl. Try the command "perldoc perlartistic" or see http://perldoc.perl.org/perlartistic.html.