| Subject: | PATCH: improved docs |
I thought the docs could be improved to better document some features
with examples and highlight some limitations as well.
I provide the attached patch as a proposed update.
Overall, I really like and plan to switch it from Data::Dumper as a
standard tool.
Mark
| Subject: | improved_docs.patch |
--- lib/Data/Dump.pm.orig 2006-11-29 05:47:17.000000000 -0500
+++ lib/Data/Dump.pm 2007-12-05 21:59:27.000000000 -0500
@@ -446,24 +446,62 @@
=head1 SYNOPSIS
- use Data::Dump qw(dump);
+ use Data::Dump 'dump';
$str = dump(@list)
@copy_of_list = eval $str;
=head1 DESCRIPTION
-This module provides a single function called dump() that takes a list
+This module provides a single function called C<dump()> that takes a list
of values as its argument and produces a string as its result. The string
contains Perl code that, when C<eval>ed, produces a deep copy of the
-original arguments. The string is formatted for easy reading.
+original arguments.
+
+=head2 FEATURES
+
+=head3 Easy reading
+
+Example:
+
+ @a = (1,[2,3],{4=>5});
+ dump(@a);
+
+Produces:
+
+ (1, [2, 3], { 4 => 5 });
+
+If you dump just a little data, it is output on a single line. If
+you dump data that is more complex or there is a lot of it, line breaks
+are automatically added to keep it easy to read.
+
+=head3 Easily Dump to STDERR
If dump() is called in a void context, then the dump is printed on
STDERR instead of being returned.
-If you don't like importing a function that overrides Perl's
-not-so-useful builtin, then you can also import the same function as
-pp(), mnemonic for "pretty-print".
+With L<Data::Dumper>, you might do this:
+
+ warn Dumper(\@a);
+
+With this module you can do just:
+
+ dump(\@a);
+
+If you want an even shorter name or you don't like importing a function that
+overrides Perl's not-so-useful builtin 'dump', then you can also import the
+same function as pp(), mnemonic for "pretty-print". Then the basic usage is
+just:
+
+ pp(\@a);
+
+=head1 LIMITATIONS
+
+Code references will be displayed as simply 'sub { "???" }' when dumped. Thus,
+"eval'ing" them will not reproduce the original routine.
+
+If you forget to explicitly import the 'dump' function, your code will core dump. That's because
+you just called the builtin 'dump' function by accident, which intentionally dumps core.
=head1 HISTORY