The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Data::Dumper::Again - An OO alter ego for Data::Dumper

SYNOPSIS

    use Data::Dumper::Again;

    $dumper = Data::Dumper::Again->new( purity => 1 );
    $dumper->dump($scalar);
    $dumper->dump(@list);

    $dumper->dump_named( '$var' => $scalar, '*list' => \@list );

DESCRIPTION

This is meant to be a proper OO interface to Data::Dumper. As any pretentious piece of code that starts with bold statements, that does not mean anyone else will think it is proper too.

My rant with Data::Dumper is because I wanted to deal with it like this:

  • create a dumper

  • configure the dumper

  • use it to dump (possibly many values)

And when I think something similar, the code that comes to mind looks like:

    $dumper = Data::Dumper->new;
    $dumper->Purity(1);
    $dumper->Sortkeys(1);
    print $dumper->dump($value1);
    print $dumper->dump($value2);

and not

    $dumper = Data::Dumper->new([ $value1 ]);
    $dumper->Purity(1);
    $dumper->Sortkeys(1);
    print $dumper->dump;

    # and then I repeat the sequence (replacing $value1 by $value2) or
    $dumper->Values([ $value2 ]);
    print $dumper->dump;

So this module cheats, being yet another simpler wrapper around Data::Dumper that makes it more OOish (at least to me).

So that I do not look just opportunist, it also provides some nice features for the user's delight. Among them:

  1. A constructor which can be given configuration options to be setted at object creation. So instead of doing

        $dumper = Data::Dumper->new([]);
        $dumper->Purity(1);
        $dumper->Sortkeys(1);

    you may say

        $dumper = Data::Dumper::Again->new( purity => 1, sortkeys => 1 );
  2. A dump method that tests to see if the arguments looks like a single scalar or a list. So that

        $dumper->dump(1); # output looks like "$VAR1 = 1;"
        $dumper->dump(qw(a b)); # @VAR1 = ( 'a', 'b' );
        $dumper->dump( () ); # @VAR1 = ();

    Obviously, the criterion for this is pretty stupid. If the argument list of the method has one element, dump it as a scalar. Otherwise, dump a list. This is basically what Gisle's Data::Dump does.

    But what if I want to dump a one-element list? See below.

  3. If you are sure that you want to dump a list, no matter how much elements there is (zero, one or more), you may use dump_list method for this effect.

        $dumper->dump_list(1); # output looks like "@VAR1 = (1);"
        $dumper->dump_list(qw(a b)); # @VAR1 = ( 'a', 'b' );
        $dumper->dump_list( () ); # @VAR1 = ();

    Orthogonally, you have a dump_scalar which only cares for the first method argument and dumps it as a scalar.

        $dumper->dump_scalar({ a => 3 }); # $VAR1 = { a => 3 };
  4. A dump_named method to which you specify variable names and values in pairs.

        $dump_named( '$s' => 1, '@a' => [ 1, 2] );
        # returns "$s = 1; @a = ( 1, 2 ); "

METHODS

Here they are:

new
    $dumper = Data::Dumper::Again->new(%args);

The constructor.

Actually the supported arguments are the configurable variables/methods provided by Data::Dumper. Actually they are

    indent
    purity
    pad
    varname
    useqq
    terse
    freezer
    toaster
    deepcopy
    quotekeys
    bless
    pair
    maxdepth
    useperl
    sortkeys
    deparse

XXX

guts
    $ddumper = $dumper->guts;

Inside a Data::Dumper::Again lives a Data::Dumper object. This method returns the underlying beast. But just because it is here, it does not mean that it is such a good idea to fuss around with this and expect that everything keeps working. Its purpose was to instrument the tests and to give you an opportunity to shoot at your feet. Don't use! You have been warned.

dump
    $s = $dumper->dump($scalar);
    $s = $dumper->dump(@list);

XXX

dump_scalar

XXX

dump_list

XXX

dump_named
    $s = $dumper->dump_named( $name1 => $value1, ... );

XXX

set_*

XXX

get_*

XXX

EXPORTS

None. This is supposed to be a pure OO module, and let's leave it that way for now.

GOTCHAS

Remember not to say

    dump($var)

while working with this module (or you will be greeted with a nice core dump). (See perldoc -f dump.) You probably meant

    $dumper->dump($var);

Yep. I actually did this a few times. (More than a few to tell the truth.)

TO DO

Document that the Data::Dumper configurable attributes, like Purity or Terse, are available via the interface of this class, with getter (get_*) and setter (set_*) methods.

Write many more tests.

SEE ALSO

There is a whole feast out there on Data::Dump(er) namespace:

    Data::Dumper
    Data::Dump
    Data::Dump::Streamer
    Data::Dumper::Simple
    Data::Dumper::Names

(It was not me, but Yves Orton that noticed this.)

BUGS

At least as many as the ones from Data::Dumper itself. But probably more.

Please report bugs via CPAN RT http://rt.cpan.org/NoAuth/Bugs.html?Dist=Data-Dumper-Again or mailto://bugs-Data-Dumper-Again@rt.cpan.org.

AUTHOR

Adriano Ferreira, <ferreira@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2007 by Adriano R. Ferreira

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