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 use Devel::PartialDump;
11 sub foo {
13 print "foo called with args: " . Devel::PartialDump->new->dump(@_);
14 }
15 use Devel::PartialDump qw(warn);
17 # warn is overloaded to create a concise dump instead of stringifying $some_bad_data
19 warn "this made a boo boo: ", $some_bad_data
20
22 This module is a data dumper optimized for logging of arbitrary
23 parameters.
24 It attempts to truncate overly verbose data, in a way that is hopefully
26 more useful for diagnostics warnings than
27 warn Dumper(@stuff);
29 Unlike other data dumping modules there are no attempts at correctness
31 or cross referencing, this is only meant to provide a slightly deeper
32 look into the data in question.
33 There is a default recursion limit, and a default truncation of long
35 lists, and the dump is formatted on one line (new lines in strings are
36 escaped), to aid in readability.
37 You can enable it temporarily by importing functions like "warn",
39 "croak" etc to get more informative errors during development, or even
40 use it as:
41 BEGIN { local $@; eval "use Devel::PartialDump qw(...)" }
43 to get DWIM formatting only if it's installed, without introducing a
45 dependency.
46
48 "foo"
49 "foo"
50 "foo" => "bar"
52 foo: "bar"
53 "foo => "bar", gorch => [ 1, "bah" ]"
55 foo: "bar", gorch: [ 1, "bah" ]
56 "[ { foo => ["bar"] } ]"
58 [ { foo: ARRAY(0x9b265d0) } ]
59 "[ 1 .. 10 ]"
61 [ 1, 2, 3, 4, 5, 6, ... ]
62 "foo\nbar"
64 "foo\nbar"
65 ""foo" . chr(1)"
67 "foo\x{1}"
68
70 max_length
71 The maximum character length of the dump.
72 Anything bigger than this will be truncated.
74 Not defined by default.
76 max_elements
78 The maximum number of elements (array elements or pairs in a hash)
79 to print.
80 Defualts to 6.
82 max_depth
84 The maximum level of recursion.
85 Defaults to 2.
87 stringify
89 Whether or not to let objects stringify themeslves, instead of
90 using "StrVal" in overload to avoid sideffects.
91 Defaults to false (no overloading).
93 pairs
95 Whether or not to autodetect named args as pairs in the main "dump"
96 function. If this attribute is true, and the top level value list
97 is even sized, and every odd element is not a reference, then it
98 will dumped as pairs instead of a list.
99
101 All exports are optional, nothing is exported by default.
102 This module uses Sub::Exporter, so exports can be renamed, curried,
104 etc.
105 warn
107 show
108 show_scalar
109 croak
110 carp
111 confess
112 cluck
113 dump
114 See the various methods for behavior documentation.
115 These methods will use $Devel::PartialDump::default_dumper as the
117 invocant if the first argument is not blessed and "isa"
118 Devel::PartialDump, so they can be used as functions too.
119 Particularly "warn" can be used as a drop in replacement for the
121 built in warn:
122 warn "blah blah: ", $some_data;
124 by importing
126 use Devel::PartialDump qw(warn);
128 $some_data will be have some of it's data dumped.
130 $default_dumper
132 The default dumper object to use for export style calls.
133 Can be assigned to to alter behavior globally.
135 This is generally useful when using the "warn" export as a drop in
137 replacement for "CORE::warn".
138
140 warn @blah
141 A warpper for "dump" that prints strings plainly.
142 show @blah
144 show_scalar $x
145 Like "warn", but instead of returning the value from "warn" it
146 returns its arguments, so it can be used in the middle of an
147 expression.
148 Note that
150 my $x = show foo();
152 will actually evaluaate "foo" in list context, so if you only want
154 to dump a single element and retain scalar context use
155 my $x = show_scalar foo();
157 which has a prototype of "$" (as opposed to taking a list).
159 This is similar to the venerable Ingy's fabulous and amazing XXX
161 module.
162 carp
164 croak
165 confess
166 cluck
167 Drop in replacements for Carp exports, that format their arguments
168 like "warn".
169 dump @stuff
171 Returns a one line, human readable, concise dump of @stuff.
172 If called in void context, will "warn" with the dump.
174 Truncates the dump according to "max_length" if specified.
176 dump_as_list $depth, @stuff
178 dump_as_pairs $depth, @stuff
179 Dump @stuff using the various formatting functions.
180 Dump as pairs returns comma delimited pairs with "=>" between the
182 key and the value.
183 Dump as list returns a comma delimited dump of the values.
185 frmat $depth, $value
187 format_key $depth, $key
188 format_object $depth, $object
189 format_ref $depth, $Ref
190 format_array $depth, $array_ref
191 format_hash $depth, $hash_ref
192 format_undef $depth, undef
193 format_string $depth, $string
194 format_number $depth, $number
195 quote $string
196 The various formatting methods.
197 You can override these to provide a custom format.
199 "format_array" and "format_hash" recurse with "$depth + 1" into
201 "dump_as_list" and "dump_as_pairs" respectively.
202 "format_ref" delegates to "format_array" and "format_hash" and does
204 the "max_depth" tracking. It will simply stringify the ref if the
205 recursion limit has been reached.
206
208 This module is maintained using git. You can get the latest version
209 from http://github.com/nothingmuch/devel-partialdump
210 <http://github.com/nothingmuch/devel-partialdump>.
211
213 Yuval Kogman <nothingmuch@woobling.org>
214
216 Copyright (c) 2008, 2009 Yuval Kogman. All rights reserved
217 This program is free software; you can redistribute
218 it and/or modify it under the same terms as Perl itself.
219perl v5.12.3 2011-04-25 Devel::PartialDump(3)