NAME

Data::Tersify - generate terse equivalents of complex data structures

VERSION

This is version 1.001 of Data::Tersify.

SYNOPSIS

 use Data::Dumper;
 use Data::Tersify qw(tersify);
 
 my $complicated_data_structure = ...;
 
 print Dumper(tersify($complicated_data_structure));
 # Your scrollback is not full of DateTime, DBIx::Class, Moose etc.
 # spoor which you weren't interested in.

DESCRIPTION

Complex data structures are useful; necessary, even. But they're not helpful. In particular, when you're buried in the guts of some code you don't fully understand and you have a variable you want to inspect, and you say x $foo in the debugger, or print STDERR Dumper($foo) from your code, or something very similar with the dumper module of your choice, and you then get pages upon pages of unhelpful stuff because $foo contained, somewhere one or more references to a DateTime, DBIx::Class, Moose or other verbose object ... you didn't need that.

Data::Tersify looks at any data structure it's given, and if it finds a blessed object that it knows about, anywhere, it replaces it in the data structure by a terser equivalent, designed to (a) not use up all of your scrollback, but (b) be blatantly clear that this is not the original object that was in that data structure originally, but a terser equivalent.

Do not use Data::Tersify as part of any serialisation implementation! By design, Data::Tersify is lossy and will throw away information! That's because it supposes that that if you're using it, you want to dump information about a complex data structure, and you don't care about the fine details.

If you find yourself saying x $foo in the debugger a lot, consider adding Data::Tersify::perldb to your .perldb file, or something like it.

tersify

 In: $data_structure
 In: $terser_data_structure

Supplied with a data structure, returns a data structure with the complicated bits summarised. Every attempt is made to preserve those parts of the data structure that don't need summarising.

Objects are only summarised if (1) they're blessed objects, (2) they're not the root structure passed to tersify (so if you actually to want to dump a complex DBIx::Class object, for instance, you still can), and (3) a plugin has been registered that groks that type of object, or they contain as an element one such object.

Summaries are either scalar references of the form "Classname (refaddr) summary", e.g. "DateTime (0xdeadbeef) 2017-08-15 12:34:56", blessed into the Data::Tersify::Summary class, or copies of the object's internal state with any sub-objects tersified as above, blessed into the Data::Tersify::Summary::Foo::0xrefaddr class, where Foo is the class the object was originally blessed into and refaddr the object's original address.

So, if you had the plugin Data::Tersify::Plugin::DateTime installed, passing a DateTime object to tersify would return that same object, untouched; but passing

 {
     name        => 'Now',
     description => 'The time it currently is, not a time in the future',
     datetime    => DateTime->now
 }

to tersify would return something like this:

 {
    name        => 'Now',
    description => 'The time it currently is, not a time in the future',
    datetime    => bless \"DateTime (0xdeadbeef) 2018-08-12 17:15:00",
        "Data::Tersify::Summary",
 }

If the hashref had been blessed into the class "Time::Description", and had a refaddr of 0xcafebabe, you would get back a hash as above, but blessed into the class Data::Tersify::Summary::Time::Description::0xcafebabe.

Note that point 2 above (objects aren't tersified if they're the root structure) applies only to plugins. If the object contains other objects that could be tersified, they will be. One design consequence of this is that you should consider writing plugins for multiple types of object, rather than the ur-object that they might be part of.

tersify_many

 In: @data_structures
 Out: @terser_data_structures

A simple wrapper around "tersify" that expects to be passed one or more variables. Note that as each value is passed to "tersify", none of the values in @data_structures will be tersified if they're objects recognised by plugins. (Whereas they would have been if you'd said tersify(\@data_structures).

This is intended to be used by e.g. the Perl debugger's x command.

PLUGINS

Data::Tersify can be extended by plugins. See Data::Tersify::Plugin for a general description of plugins; for examples of plugins, see Data::Tersify::Plugin::DateTime and Data::Tersify::Plugin::DBIx::Class, provided in separate distributions.

LICENSE

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

BUGS

If you find any bugs, or have any feature suggestions, please report them via github.

SEE ALSO

Data::Printer will tersify data structures as part of its standard output.

cpanm Data::Tersify

perl -MCPAN -e shell
install Data::Tersify