/ 
Data-Dumper-EasyOO-0.02
River stage zero No dependents
/ Data::Dumper::EasyOO

NAME

Data::Dumper::EasyOO - wraps DD for easy use of printing styles

SYNOPSIS

{
    # set common style for all objects created
    use Data::Dumper::EasyOO (indent => 1);

    # build an EzDD object, adding print-styles
    my $ezdd = Data::Dumper::EasyOO->new (terse => 1);
    
    # use the same ezdd obj repeatedly
    print "default: ", $ezdd->($_) for @userdata;
    
    # label it $foo, not $VAR1
    print $ezdd->(foo => $_) for @userdata;
    
    # alter printing style using DD API
    $ezdd->Terse(0);
    print "default: ", $ezdd->($_) for @userdata;
    
    # alter many print styles at once
    $ezdd->Set (terse=>0, sortkeys=>1);
    print "default: ", $ezdd->($_) for @userdata;

    # set autoprint to STDOUT
    $ezdd->Set (autoprint => 1);
    $ezdd->( you_used_pkgs => \%INC);

    # set autoprint to an opened filehandle
    $ezdd->Set (autoprint => $fh);
    $ezdd->( you_used_pkgs => \%INC);
}

DESCRIPTION

This package wraps Data::Dumper, and gives an object thats as easy to print with as Dumper(), DDs exported procedural interface. Its also easy to control print-style, as theyre set within the EzDD object.

In this document, I use DD as shorthand for Data::Dumper, DD-OO for its object oriented API, and EzDD for this class. Despite the package name, I assume some knowledge about DD, at least wrt explaining why EzDD is better.

In DD-OO, you must provide new() with the data to print, then change print-style, then print. This 3 step usage tends to be verbose. Because theres no (currently documented) way to un-bind the data, most users just toss the DD object.

In contrast, EzDD is geared for object reuse, just think of it like a printer; print-style is analogous to color, paper-size, etc. You just build an object for each different print style you want, and use them repeatedly. A single EzDD object is enough for most users.

FEATURE COMPARISON

In the following, I compare EzDD to either or both DD and DD-OO. This section is meant to be somewhat cursory; the next section delves a bit deeper.

construct the EzDD object

To use EzDD, you have to (blow a line of code to) create an EzDD object, but you can initialize it once and for all, with less typing than with DDs package vars.

    new:   $ezdd = Data::Dumper::EasyOO->new(indent=>1,sortkeys=>1);
    old: {
	$Data::Dumper::Indent = 1;
	$Data::Dumper::Sortkeys = 1;
    }

EzDD printing is brief

Once your $ezdd object is built, printing is as easy as using Dumper(). Note that $ezdd doesnt even need a method name !

  new:   print $ezdd->($foo);
   dd:   print Dumper ($foo);
dd_oo:   print Data::Dumper->Dump($foo);

Using autoprint mode, you can drop the 'print'

$ezdd->Set(autoprint=>1);
$ezdd->($foo);

Easier Labelling of Data

old: print Data::Dumper->Dump ( [$a,$b,$c], [qw(a b c)] );
new: print $ezdd	 ->	( a=>$a, b=>$b, c=>$c )

Labelling data wih DD-OO is counterintuitive; most perl users like and expect to see labelled => $data. DD-OO is also too punctuation intensive, too dependent on having exactly 2 arrayref args, and having them the same length. Also, note that Dumper() cannot label data at all.

You can independently control print-style on each object

With Dumper(), print-style is controlled either globally, or by localizing a set of variables. With EzDD, print-style can be set on the object. This is a big advantage when you want 2 styles simultaneously.

DD: {
    local $Data::Dumper::Indent = 1;
    local $Data::Dumper::Sortkeys = 1;
    print Dumper (\@foo);
}
new: {
    $ezdd->Set(indent=>1,sortkeys=>1); # do once on obj
    print $ezdd->(\@foo);
}

The next example shows DD_OO style control. Its tedious if you have to do it each time you want to print.

You can print repeatedly with same object

In DD-OO, you must provide the data to be dumped when the object is created, only then can the print-style be changed. This means lots of extra typing and method calls, thus discouraging use of OO style.

  EzDD: {
      $d->Set(indent=>1,deepcopy=>1);
      print $d->($_) foreach @data;
  }
  DD_OO:
    foreach $datum (@data) {
	$d = Data::Dumper->new($datum);
	$d->Sortkeys(1)->Indent(1)->Deepcopy(1);
	print $d->Dump;
    }

FEATURES

Controlling Print Style for objects

With EzDD, you control print style of single objects, either by speifying at creation, or altering thereafter.

$ezdd = Data::Dumper::EasyOO->new(%printOptions);
$ezdd->Set(%newprintOptions);	# update many
$ezdd->Indent(1); 			# update by DDs methods
$ezdd->Terse(1)->Sortkeys(1);	# update in chains (like DD)

These settings stay with the object thru its lifetime, and are independent of other objects settings. If you dont set preferences as above, DDs globals are used by default.

Controlling Print Style via use

Print style can also be set at use-time, these are defaults for every object built thereafter. They can be overridden for individual objects, by any of new(), Set(), or DDs style-setting methods.

The styles are saved separately for each package using EzDD, so Foo.pm and Bar.pm can have a different styles.

Easy Labelling for your Data

print $ezdd->(@args);

@args are treated as pairs of labelled data if possible; ie if arglist is even length, and if the 'labels' are scalars. If you have an array (of scalars) that is incorrectly printed as labelled data, you can force things by passing its ref; ie $ezdd->([0..3]) vs $ezdd->((0..3)).

This maybe a bit aggressive for your tastes, but I dont use DD with simple scalars (except by accident ;-) and my habit with Dumper() is to always pass a single data-arg anyway, ex \@foo. YMMV. FWIW - DD::Dumper() also does this; it calls Data::Dumper->Dump([@_]). For more specifics, check t/labels.t or the code.

Auto-Printing

Autoprinting allows you to drop the 'print':

use Data::Dumper::EasyOO ( autoprint => 1 );
my $ez = Data::Dumper::EasyOO->new();
$ez->('the-includes' => \%INC);

The autoprint property can be 1 for STDOUT, 2 for STDERR, or an open FileHandle, and will write accordingly. You can also change this afterwards (note the tag change);

my $ez2 = EzDD->new(_ezdd_autoprint => 2);	# set in ctor
$ez->Set(_ezdd_autoprint => 2);		# change during use

Speed

Dumper() builds a new DD object for each print, and this has non-zero runtime costs. Ive included a benchmark in the testsuite which shows 3% to 24% improvement on a linux 686 laptop, using the small data chunks I used for testing. With large data sets, printing time dominates, and the improvement drops asymtotically to 0%.

INTERFACE

As I hope is clear by now, $ezdd->($data) renders the data.

new(%printOptions) creates a new EzDD object, and calls Set() to establish desired printing behavior of that instance.

Set(%printOptions) alters the print style of an existing EzDD object. It accepts option names matching the methods that DD provides, and lowercase versions of them. %option values are not validated by EzDD, DD itself may do so, but I havent tested this, and make no promises.

Set() also does not provide accessor functionality; most DD methods return the DD object in support of method chaining, they cannot return the attribute values.

AUTOLOAD() allows you to invoke the familiar DD methods on an EzDD object, its a convenience method which calls Set().

pp() and dump() are methods to "pretty-print". The names were borrowed from Data::Dump

IMPLEMENTATION

The class builds a blessed CODEref object, for which perl also allows method-lookups. This hybrid nature is key to the viability of the design.

new() builds a private Data::Dumper object, then builds and returns a closure on that object. The closure provides the printing interface directly, and also provides (via special data value - slightly hackish) access to the underlying DD object for the other methods; Set() and AUTOLOAD().

BUGS

EasyOO relys on Data::Dumper, so if youre using 5.00503 and havent upgraded DD, some print-style controls wont be available.

Validation of DD methods is based on checks of $DD::VERSION, and may have a few errors, or may miss a few DD versions in between original and current.

Some allowed methods may be nonsense in this context; I havent used them all myself in real-life, or in tests.

Theres no accessor functionality for print-styles.

Possible Applications

A client-class dumper. You can create one or a few EzDD objects in your Foo.pm module, and tailor them to serialize Foo objects however you like. With Sortkeys, you can serialize only the object keys you want, for persistent storage, or for debugging purposes. Maxdepth, Varname, etc are all similarly usable.

CAVEATS, Enhancements, TBD, TBC

method-less invocation may be over-cool.

This was an experiment (in blessed coderefs) that went well enough to continue. If this feature makes you itch, you can use $ezdd->pp() $ezdd->dump() instead.

Brand new code, with the usual caveats.

Tested OK against 5.005_03, 5.8.2, and many in between, both threaded and unthreaded. As wise men say, 'release early, release often'

Too much dependency on DD

The down-side of 5.00503 compatibility is that DD was less capable back then. Barbie caught and reported some test failures on ActiveState 5.6.1 due to then non-existent DD methods used in some aggressive tests. Ive detuned t/chains.t, but others may lurk.

No validation on %printOptions values.

Arrayrefs & hashrefs are passed verbatim to DD object. If DD expects a particular value type, you must provide it; I do no checking, and rely on DD to complain as fitting.

If DD carps about stuff passed in, it may blame EzDD. I regard this as a user error, youve been warned. I will accept patches which place blame properly ;-)

format control not per-use, but on object only

You cant localize print options for 1 usage. This is because those DD pkg vars, localized or not, are copied into the object when its constructed, and are thereafter ignored by that object. This *could* be fixed by changes to DD, but I dont see the value, Id anticipate a slowdown, and I dont expect DDs maintainer would accept that.

auto-labelling may be overzealous.

In particular, $ezdd->(1,2,3,4) will treat 1,3 as labels. At minimum it needs more tests.

Reporting of illegal methods can change capitalization

DD has nice property that object attributes are lower-cased versions of the method names. I leverage this, and use lc(), ucfirst() to allow mixed case print-styles, but this may result in slightly confusing capitalization differences.

not *entirely* data-agnostic

$ezdd->('__SA__') will return underlying DD object, unlike all other data. This hackery is needed cuz the closure is the only handle to the DD object, unless Ive missed something.

add no_reset option

EzDD uses $ddo->Reset so that $ddo can be reused. a no_reset option would allow you to defeat that. The internal flag 'ddez_noreset' already exists, but the details are subject to change.

To Be Considered

AUTOLOAD() accessor mode

This conflicts with support for method-chaining (ie returning the object so it can be chained). Since DD supports it, we should too.

It may be possible by defining sub _get($prop), calling it from AUTOLOAD if not @args. This would break chaining for accessors, but thats 'broken by design' anyway.

Sortkeys as hashref

If sortkeys was a hashref (with arrayref values), the keys *could* specify applicability of the arrayref based upon the data being dumped; its type, depth, tag, etc.. See "Possible Applications".

Reasons not to bother: The key would need som XPath-ish form, which may be sufficient reason to kill the idea at birth. It would also need DD support, at very least a callback scheme.

Comments welcome.

Whats overkill ?

SEE ALSO

Data::Dumper is used internally (you know by now ;-). If you really want to, you can reuse DD objects without this module. See the code for how to do so.

Data::Dump also has a simple interface, ie a single function, imported as dump() or pp(). It doesnt have print-style controls, and doesnt have DDs evaluable output, so its not directly usable in place of DD, where this is. On the other hand, its output is magically data-dependent; if the data fits on a single line, it gets printed that way.

ACKNOWLEDGMENTS

Gurusamy Sarathy for writing DD, I love it and use it *ALL* the time, its often my microscope of choice. I cant leave the above critique as the only commentary.

AUTHOR

Jim Cromie <jcromie@cpan.org>

Copyright (c) 2003 Jim Cromie. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

I dont suppose I'll ever recover the (modest) development time via reduced keystrokes, but CPAN has saved me so much already; heres a little give-back. And besides, perl is fun, like an always-new toy.