view release on metacpan or  search on metacpan

lib/Acme/Data/Dumper/Extensions.pm  view on Meta::CPAN

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

=head3 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 C<$_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 I<new> feature wherein, users have to I<< Opt-B<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.

=head2 C<$_DumpValues>

This function is a helper that does what people who maintain a long-lived
C<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 B<first> store the data in the object, and B<then>
dump it, which introduces fun problems with your data living longer than you
intended it to.

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

This function is designed to be used atomically. Any pre-existing variable
state (eg: C<Names>, C<Values>, C<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.

=head3 Syntax

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

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

=head3 Arguments

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

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

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

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

If this option is present, passed values used instead.