1Devel::PartialDump(3) User Contributed Perl DocumentationDevel::PartialDump(3)
2
6 Devel::PartialDump - Partial dumping of data structures, optimized for
7 argument printing.
8
10 version 0.20
11
13 use Devel::PartialDump;
14 sub foo {
16 print "foo called with args: " . Devel::PartialDump->new->dump(@_);
17 }
18 use Devel::PartialDump qw(warn);
20 # warn is overloaded to create a concise dump instead of stringifying $some_bad_data
22 warn "this made a boo boo: ", $some_bad_data
23
25 This module is a data dumper optimized for logging of arbitrary
26 parameters.
27 It attempts to truncate overly verbose data, in a way that is hopefully
29 more useful for diagnostics warnings than
30 warn Dumper(@stuff);
32 Unlike other data dumping modules there are no attempts at correctness
34 or cross referencing, this is only meant to provide a slightly deeper
35 look into the data in question.
36 There is a default recursion limit, and a default truncation of long
38 lists, and the dump is formatted on one line (new lines in strings are
39 escaped), to aid in readability.
40 You can enable it temporarily by importing functions like "warn",
42 "croak" etc to get more informative errors during development, or even
43 use it as:
44 BEGIN { local $@; eval "use Devel::PartialDump qw(...)" }
46 to get DWIM formatting only if it's installed, without introducing a
48 dependency.
49
51 "foo"
52 "foo"
53 "foo" => "bar"
55 foo: "bar"
56 "foo => "bar", gorch => [ 1, "bah" ]"
58 foo: "bar", gorch: [ 1, "bah" ]
59 "[ { foo => ["bar"] } ]"
61 [ { foo: ARRAY(0x9b265d0) } ]
62 "[ 1 .. 10 ]"
64 [ 1, 2, 3, 4, 5, 6, ... ]
65 "foo\nbar"
67 "foo\nbar"
68 ""foo" . chr(1)"
70 "foo\x{1}"
71
73 max_length
74 The maximum character length of the dump.
75 Anything bigger than this will be truncated.
77 Not defined by default.
79 max_elements
81 The maximum number of elements (array elements or pairs in a hash)
82 to print.
83 Defaults to 6.
85 max_depth
87 The maximum level of recursion.
88 Defaults to 2.
90 stringify
92 Whether or not to let objects stringify themselves, instead of
93 using "StrVal" in overload to avoid side effects.
94 Defaults to false (no overloading).
96 pairs
98 Whether or not to autodetect named args as pairs in the main "dump"
99 function. If this attribute is true, and the top level value list
100 is even sized, and every odd element is not a reference, then it
101 will dumped as pairs instead of a list.
102
104 All exports are optional, nothing is exported by default.
105 This module uses Sub::Exporter, so exports can be renamed, curried,
107 etc.
108 warn
110 show
111 show_scalar
112 croak
113 carp
114 confess
115 cluck
116 dump
117 See the various methods for behavior documentation.
118 These methods will use $Devel::PartialDump::default_dumper as the
120 invocant if the first argument is not blessed and "isa"
121 Devel::PartialDump, so they can be used as functions too.
122 Particularly "warn" can be used as a drop in replacement for the
124 built in warn:
125 warn "blah blah: ", $some_data;
127 by importing
129 use Devel::PartialDump qw(warn);
131 $some_data will be have some of it's data dumped.
133 $default_dumper
135 The default dumper object to use for export style calls.
136 Can be assigned to to alter behavior globally.
138 This is generally useful when using the "warn" export as a drop in
140 replacement for "CORE::warn".
141
143 warn @blah
144 A wrapper for "dump" that prints strings plainly.
145 show @blah
147 show_scalar $x
148 Like "warn", but instead of returning the value from "warn" it
149 returns its arguments, so it can be used in the middle of an
150 expression.
151 Note that
153 my $x = show foo();
155 will actually evaluate "foo" in list context, so if you only want
157 to dump a single element and retain scalar context use
158 my $x = show_scalar foo();
160 which has a prototype of "$" (as opposed to taking a list).
162 This is similar to the venerable Ingy's fabulous and amazing XXX
164 module.
165 carp
167 croak
168 confess
169 cluck
170 Drop in replacements for Carp exports, that format their arguments
171 like "warn".
172 dump @stuff
174 Returns a one line, human readable, concise dump of @stuff.
175 If called in void context, will "warn" with the dump.
177 Truncates the dump according to "max_length" if specified.
179 dump_as_list $depth, @stuff
181 dump_as_pairs $depth, @stuff
182 Dump @stuff using the various formatting functions.
183 Dump as pairs returns comma delimited pairs with "=>" between the
185 key and the value.
186 Dump as list returns a comma delimited dump of the values.
188 format $depth, $value
190 format_key $depth, $key
191 format_object $depth, $object
192 format_ref $depth, $Ref
193 format_array $depth, $array_ref
194 format_hash $depth, $hash_ref
195 format_undef $depth, undef
196 format_string $depth, $string
197 format_number $depth, $number
198 quote $string
199 The various formatting methods.
200 You can override these to provide a custom format.
202 "format_array" and "format_hash" recurse with "$depth + 1" into
204 "dump_as_list" and "dump_as_pairs" respectively.
205 "format_ref" delegates to "format_array" and "format_hash" and does
207 the "max_depth" tracking. It will simply stringify the ref if the
208 recursion limit has been reached.
209
211 Bugs may be submitted through the RT bug tracker
212 <https://rt.cpan.org/Public/Dist/Display.html?Name=Devel-PartialDump>
213 (or bug-Devel-PartialDump@rt.cpan.org <mailto:bug-Devel-
214 PartialDump@rt.cpan.org>).
215 There is also a mailing list available for users of this distribution,
217 at <http://lists.perl.org/list/moose.html>.
218 There is also an irc channel available for users of this distribution,
220 at "#moose" on "irc.perl.org" <irc://irc.perl.org/#moose>.
221
223 יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
224
226 • Karen Etheridge <ether@cpan.org>
227 • Florian Ragwitz <rafl@debian.org>
229 • Steven Lee <stevenwh.lee@gmail.com>
231 • Leo Lapworth <web@web-teams-computer.local>
233 • Jesse Luehrs <doy@tozt.net>
235 • David Golden <dagolden@cpan.org>
237 • Paul Howarth <paul@city-fan.org>
239
241 This software is copyright (c) 2008 by יובל קוג'מן (Yuval Kogman).
242 This is free software; you can redistribute it and/or modify it under
244 the same terms as the Perl 5 programming language system itself.
245perl v5.32.1 2021-01-27 Devel::PartialDump(3)