local-lib5/man/man3/Devel::PartialDump.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Devel::PartialDump 3"
 127 .TH Devel::PartialDump 3 "2009-11-08" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Devel::PartialDump \- Partial dumping of data structures, optimized for argument
 134 printing.
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&        use Devel::PartialDump;
 139 \&
 140 \&        sub foo {
 141 \&                print "foo called with args: " . Devel::PartialDump\->new\->dump(@_);
 142 \&        }
 143 \&
 144 \&        use Devel::PartialDump qw(warn);
 145 \&
 146 \&        # warn is overloaded to create a concise dump instead of stringifying $some_bad_data
 147 \&        warn "this made a boo boo: ", $some_bad_data
 148 .Ve
 149 .SH "DESCRIPTION"
 150 .IX Header "DESCRIPTION"
 151 This module is a data dumper optimized for logging of arbitrary parameters.
 152 .PP
 153 It attempts to truncate overly verbose data, in a way that is hopefully more
 154 useful for diagnostics warnings than
 155 .PP
 156 .Vb 1
 157 \&        warn Dumper(@stuff);
 158 .Ve
 159 .PP
 160 Unlike other data dumping modules there are no attempts at correctness or cross
 161 referencing, this is only meant to provide a slightly deeper look into the data
 162 in question.
 163 .PP
 164 There is a default recursion limit, and a default truncation of long lists, and
 165 the dump is formatted on one line (new lines in strings are escaped), to aid in
 166 readability.
 167 .PP
 168 You can enable it temporarily by importing functions like \f(CW\*(C`warn\*(C'\fR, \f(CW\*(C`croak\*(C'\fR etc
 169 to get more informative errors during development, or even use it as:
 170 .PP
 171 .Vb 1
 172 \&        BEGIN { local $@; eval "use Devel::PartialDump qw(...)" }
 173 .Ve
 174 .PP
 175 to get \s-1DWIM\s0 formatting only if it's installed, without introducing a
 176 dependency.
 177 .SH "SAMPLE OUTPUT"
 178 .IX Header "SAMPLE OUTPUT"
 179 .ie n .IP """foo""" 4
 180 .el .IP "\f(CW``foo''\fR" 4
 181 .IX Item """foo"""
 182 .Vb 1
 183 \&    "foo"
 184 .Ve
 185 .ie n .IP """foo"" => ""bar""" 4
 186 .el .IP "\f(CW``foo'' => ``bar''\fR" 4
 187 .IX Item """foo"" => ""bar"""
 188 .Vb 1
 189 \&    foo: "bar"
 190 .Ve
 191 .ie n .IP """foo => ""bar"", gorch => [ 1, ""bah"" ]""" 4
 192 .el .IP "\f(CWfoo => ``bar'', gorch => [ 1, ``bah'' ]\fR" 4
 193 .IX Item "foo => ""bar"", gorch => [ 1, ""bah"" ]"
 194 .Vb 1
 195 \&    foo: "bar", gorch: [ 1, "bah" ]
 196 .Ve
 197 .ie n .IP """[ { foo => [""bar""] } ]""" 4
 198 .el .IP "\f(CW[ { foo => [``bar''] } ]\fR" 4
 199 .IX Item "[ { foo => [""bar""] } ]"
 200 .Vb 1
 201 \&    [ { foo: ARRAY(0x9b265d0) } ]
 202 .Ve
 203 .ie n .IP """[ 1 .. 10 ]""" 4
 204 .el .IP "\f(CW[ 1 .. 10 ]\fR" 4
 205 .IX Item "[ 1 .. 10 ]"
 206 .Vb 1
 207 \&    [ 1, 2, 3, 4, 5, 6, ... ]
 208 .Ve
 209 .ie n .IP """foo\enbar""" 4
 210 .el .IP "\f(CW``foo\enbar''\fR" 4
 211 .IX Item """foonbar"""
 212 .Vb 1
 213 \&    "foo\enbar"
 214 .Ve
 215 .ie n .IP """""foo"" . chr(1)""" 4
 216 .el .IP "\f(CW``foo'' . chr(1)\fR" 4
 217 .IX Item """foo"" . chr(1)"
 218 .Vb 1
 219 \&    "foo\ex{1}"
 220 .Ve
 221 .SH "ATTRIBUTES"
 222 .IX Header "ATTRIBUTES"
 223 .IP "max_length" 4
 224 .IX Item "max_length"
 225 The maximum character length of the dump.
 226 .Sp
 227 Anything bigger than this will be truncated.
 228 .Sp
 229 Not defined by default.
 230 .IP "max_elements" 4
 231 .IX Item "max_elements"
 232 The maximum number of elements (array elements or pairs in a hash) to print.
 233 .Sp
 234 Defualts to 6.
 235 .IP "max_depth" 4
 236 .IX Item "max_depth"
 237 The maximum level of recursion.
 238 .Sp
 239 Defaults to 2.
 240 .IP "stringify" 4
 241 .IX Item "stringify"
 242 Whether or not to let objects stringify themeslves, instead of using
 243 \&\*(L"StrVal\*(R" in overload to avoid sideffects.
 244 .Sp
 245 Defaults to false (no overloading).
 246 .IP "pairs" 4
 247 .IX Item "pairs"
 248 Whether or not to autodetect named args as pairs in the main \f(CW\*(C`dump\*(C'\fR function.
 249 If this attribute is true, and the top level value list is even sized, and
 250 every odd element is not a reference, then it will dumped as pairs instead of a
 251 list.
 252 .SH "EXPORTS"
 253 .IX Header "EXPORTS"
 254 All exports are optional, nothing is exported by default.
 255 .PP
 256 This module uses Sub::Exporter, so exports can be renamed, curried, etc.
 257 .IP "warn" 4
 258 .IX Item "warn"
 259 .PD 0
 260 .IP "show" 4
 261 .IX Item "show"
 262 .IP "show_scalar" 4
 263 .IX Item "show_scalar"
 264 .IP "croak" 4
 265 .IX Item "croak"
 266 .IP "carp" 4
 267 .IX Item "carp"
 268 .IP "confess" 4
 269 .IX Item "confess"
 270 .IP "cluck" 4
 271 .IX Item "cluck"
 272 .IP "dump" 4
 273 .IX Item "dump"
 274 .PD
 275 See the various methods for behavior documentation.
 276 .Sp
 277 These methods will use \f(CW$Devel::PartialDump::default_dumper\fR as the invocant if the
 278 first argument is not blessed and \f(CW\*(C`isa\*(C'\fR Devel::PartialDump, so they can be
 279 used as functions too.
 280 .Sp
 281 Particularly \f(CW\*(C`warn\*(C'\fR can be used as a drop in replacement for the built in
 282 warn:
 283 .Sp
 284 .Vb 1
 285 \&        warn "blah blah: ", $some_data;
 286 .Ve
 287 .Sp
 288 by importing
 289 .Sp
 290 .Vb 1
 291 \&        use Devel::PartialDump qw(warn);
 292 .Ve
 293 .Sp
 294 \&\f(CW$some_data\fR will be have some of it's data dumped.
 295 .ie n .IP "$default_dumper" 4
 296 .el .IP "\f(CW$default_dumper\fR" 4
 297 .IX Item "$default_dumper"
 298 The default dumper object to use for export style calls.
 299 .Sp
 300 Can be assigned to to alter behavior globally.
 301 .Sp
 302 This is generally useful when using the \f(CW\*(C`warn\*(C'\fR export as a drop in replacement
 303 for \f(CW\*(C`CORE::warn\*(C'\fR.
 304 .SH "METHODS"
 305 .IX Header "METHODS"
 306 .ie n .IP "warn @blah" 4
 307 .el .IP "warn \f(CW@blah\fR" 4
 308 .IX Item "warn @blah"
 309 A warpper for \f(CW\*(C`dump\*(C'\fR that prints strings plainly.
 310 .ie n .IP "show @blah" 4
 311 .el .IP "show \f(CW@blah\fR" 4
 312 .IX Item "show @blah"
 313 .PD 0
 314 .ie n .IP "show_scalar $x" 4
 315 .el .IP "show_scalar \f(CW$x\fR" 4
 316 .IX Item "show_scalar $x"
 317 .PD
 318 Like \f(CW\*(C`warn\*(C'\fR, but instead of returning the value from \f(CW\*(C`warn\*(C'\fR it returns its
 319 arguments, so it can be used in the middle of an expression.
 320 .Sp
 321 Note that
 322 .Sp
 323 .Vb 1
 324 \&        my $x = show foo();
 325 .Ve
 326 .Sp
 327 will actually evaluaate \f(CW\*(C`foo\*(C'\fR in list context, so if you only want to dump a
 328 single element and retain scalar context use
 329 .Sp
 330 .Vb 1
 331 \&        my $x = show_scalar foo();
 332 .Ve
 333 .Sp
 334 which has a prototype of \f(CW\*(C`$\*(C'\fR (as opposed to taking a list).
 335 .Sp
 336 This is similar to the venerable Ingy's fabulous and amazing \s-1XXX\s0 module.
 337 .IP "carp" 4
 338 .IX Item "carp"
 339 .PD 0
 340 .IP "croak" 4
 341 .IX Item "croak"
 342 .IP "confess" 4
 343 .IX Item "confess"
 344 .IP "cluck" 4
 345 .IX Item "cluck"
 346 .PD
 347 Drop in replacements for Carp exports, that format their arguments like
 348 \&\f(CW\*(C`warn\*(C'\fR.
 349 .ie n .IP "dump @stuff" 4
 350 .el .IP "dump \f(CW@stuff\fR" 4
 351 .IX Item "dump @stuff"
 352 Returns a one line, human readable, concise dump of \f(CW@stuff\fR.
 353 .Sp
 354 If called in void context, will \f(CW\*(C`warn\*(C'\fR with the dump.
 355 .Sp
 356 Truncates the dump according to \f(CW\*(C`max_length\*(C'\fR if specified.
 357 .ie n .IP "dump_as_list $depth, @stuff" 4
 358 .el .IP "dump_as_list \f(CW$depth\fR, \f(CW@stuff\fR" 4
 359 .IX Item "dump_as_list $depth, @stuff"
 360 .PD 0
 361 .ie n .IP "dump_as_pairs $depth, @stuff" 4
 362 .el .IP "dump_as_pairs \f(CW$depth\fR, \f(CW@stuff\fR" 4
 363 .IX Item "dump_as_pairs $depth, @stuff"
 364 .PD
 365 Dump \f(CW@stuff\fR using the various formatting functions.
 366 .Sp
 367 Dump as pairs returns comma delimited pairs with \f(CW\*(C`=>\*(C'\fR between the key and the value.
 368 .Sp
 369 Dump as list returns a comma delimited dump of the values.
 370 .ie n .IP "frmat $depth, $value" 4
 371 .el .IP "frmat \f(CW$depth\fR, \f(CW$value\fR" 4
 372 .IX Item "frmat $depth, $value"
 373 .PD 0
 374 .ie n .IP "format_key $depth, $key" 4
 375 .el .IP "format_key \f(CW$depth\fR, \f(CW$key\fR" 4
 376 .IX Item "format_key $depth, $key"
 377 .ie n .IP "format_object $depth, $object" 4
 378 .el .IP "format_object \f(CW$depth\fR, \f(CW$object\fR" 4
 379 .IX Item "format_object $depth, $object"
 380 .ie n .IP "format_ref $depth, $Ref" 4
 381 .el .IP "format_ref \f(CW$depth\fR, \f(CW$Ref\fR" 4
 382 .IX Item "format_ref $depth, $Ref"
 383 .ie n .IP "format_array $depth, $array_ref" 4
 384 .el .IP "format_array \f(CW$depth\fR, \f(CW$array_ref\fR" 4
 385 .IX Item "format_array $depth, $array_ref"
 386 .ie n .IP "format_hash $depth, $hash_ref" 4
 387 .el .IP "format_hash \f(CW$depth\fR, \f(CW$hash_ref\fR" 4
 388 .IX Item "format_hash $depth, $hash_ref"
 389 .ie n .IP "format_undef $depth, undef" 4
 390 .el .IP "format_undef \f(CW$depth\fR, undef" 4
 391 .IX Item "format_undef $depth, undef"
 392 .ie n .IP "format_string $depth, $string" 4
 393 .el .IP "format_string \f(CW$depth\fR, \f(CW$string\fR" 4
 394 .IX Item "format_string $depth, $string"
 395 .ie n .IP "format_number $depth, $number" 4
 396 .el .IP "format_number \f(CW$depth\fR, \f(CW$number\fR" 4
 397 .IX Item "format_number $depth, $number"
 398 .ie n .IP "quote $string" 4
 399 .el .IP "quote \f(CW$string\fR" 4
 400 .IX Item "quote $string"
 401 .PD
 402 The various formatting methods.
 403 .Sp
 404 You can override these to provide a custom format.
 405 .Sp
 406 \&\f(CW\*(C`format_array\*(C'\fR and \f(CW\*(C`format_hash\*(C'\fR recurse with \f(CW\*(C`$depth + 1\*(C'\fR into
 407 \&\f(CW\*(C`dump_as_list\*(C'\fR and \f(CW\*(C`dump_as_pairs\*(C'\fR respectively.
 408 .Sp
 409 \&\f(CW\*(C`format_ref\*(C'\fR delegates to \f(CW\*(C`format_array\*(C'\fR and \f(CW\*(C`format_hash\*(C'\fR and does the
 410 \&\f(CW\*(C`max_depth\*(C'\fR tracking. It will simply stringify the ref if the recursion limit
 411 has been reached.
 412 .SH "VERSION CONTROL"
 413 .IX Header "VERSION CONTROL"
 414 This module is maintained using git. You can get the latest version from
 415 <http://github.com/nothingmuch/devel\-partialdump>.
 416 .SH "AUTHOR"
 417 .IX Header "AUTHOR"
 418 Yuval Kogman <nothingmuch@woobling.org>
 419 .SH "COPYRIGHT"
 420 .IX Header "COPYRIGHT"
 421 .Vb 3
 422 \&        Copyright (c) 2008, 2009 Yuval Kogman. All rights reserved
 423 \&        This program is free software; you can redistribute
 424 \&        it and/or modify it under the same terms as Perl itself.
 425 .Ve