NAME

Acme::Data::Dumper::Extensions - Experimental Enhancements to core Data::Dumper

SYNOPSIS

use Data::Dumper;
use Acme::Data::Dumper::Extensions qw/$_new_with_defaults/;

local $Data::Dumper::Indent = 5;

my $instance = Data::Dumper->$_new_with_defaults({ }); # Indent is still 2!

$instance =  Data::Dumper->$_new_with_defaults({
  Indent => 4,         # Easier initalizer
});

DESCRIPTION

This is just a testing ground for things that I'm suggesting for Data::Dumper.

It will likely be terrible because bolting on features after-the-fact its also pretty ugly.

But its just a prototype.

For some, it will serve more as a proof-of-concept for various interfaces until they get accepted into core.

EXPORTS

$_new_with_defaults

This is a prototype function for construcing a Data::Dumper instance without being prone to leak from other people using the global values.

At the time of this writing, if you need perfect consistency from Data::Dumper in widely used code, you by necessity have to know every version of Data::Dumper that exists, and know what the default values are of various arguments, in order to revert them to your "known good" state if 3rd party code decides to locally change those values for their own purposes.

Getting an instance of a Data::Dumper object before anyone tweaks those values would also work, but trying to bet on getting loaded and getting an instance before anyone else does is just foolhardy

Additionally, due to how ->Values works, having a global instance of Data::Dumper can lend itself to a memory leak and you have to take additional care to make sure you free values passed to it.

Syntax

The name used here is $_new_with_defaults as this makes it straight forward to migrate code that uses this once its adopted, without needing to monkey-patch Data::Dumper itself.

Data::Dumper->$_new_with_defaults( ... )
Data::Dumper->new_with_defaults( ... )

Arguments

# Using the defaults
Data::Dumper->$_new_with_defaults()

# Augmenting the defaults
Data::Dumper->$_new_with_defaults({ Name => value, Name => value });

The approach I've taken here is to ignore the standard arguments to new, because it wasn't clear to me how else to organise this with the existing alternative interfaces.

Given there's an alternative way of passing the dump values, its suggested to just use those until this part of the design is sorted out:

Data::Dumper->$_new_with_defaults()->Values([ stuff, to, dump ])->Dump();

Or use the other feature suggested in this module:

Data::Dumper->$_new_with_defaults()->$_DumpValues([ stuff, to, dump ]);

Unrecognised Features

I'm still not sure how to handle what happens when somebody passes the name of a feature which doesn't exist yet, but does in a future version.

Ideally, calling $_new_with_defaults() should give you the same results in perpetuity ( or at least, from the date this feature gets added )

For now I think the best thing to do is die fatally if a feature that is requested can't be provided, as that will produce output other than is desired and violate output consistency as a result.

This will just become a nightmare if somebody ever changes "The Default" for a new feature wherein, users have to Opt-Out, causing an explosion on older versions where that feature didn't exist.

This should be a hazard to never even consider changing the default behaviour.

$_DumpValues

This function is a helper that does what people who maintain a long-lived Data::Dumper instance generally desire: The ability to just set up an instance, and then call it an arbitrary number of times with arbitrary inputs and have it act without side effects.

However, the current implementation of Data::Dumper is such that if you have an instance, you must first store the data in the object, and then dump it, which introduces fun problems with your data living longer than you intended it to.

Currently, you also must call ->Reset after dumping to reset the Seen state.

This function is designed to be used atomically. Any pre-existing variable state (eg: Names, Values, Seen ) should be thouroughly ignored, and any of those values will be left in a "reset" state after using this function.

It is thus inadvisable to combine use of this function with others.

If you need complex behaviours provided by the more advanced interfaces, its recommended to use those instead.

Syntax

# Dump array of values as a string
$instance->$_DumpValues( [ values ] );

# Dump array of values with predefined names
$instance->$_DumpValues( [ values, ... ], [ names, ... ]);

Arguments

The first argument (required) must be an ArrayRef of values to dump.

This value will ALWAYS be used instead of any instances of Values passed earlier. Any values previously passed to Values will be preserved.

The second (optional) argument is an ArrayRef of names to use for values.

If this option is omitted, it will behave as if you'd passed [].

If this option is present, passed values used instead.