1Data::Printer::Object(3U)ser Contributed Perl DocumentatiDoanta::Printer::Object(3)
2
6 Data::Printer::Object - underlying object for Data::Printer
7
9 Unless you're writing a plugin, or looking for some configuration
10 property details the documentation you want is probably on
11 Data::Printer. Seriously!
12
14 This module implements the underlying object used by Data::Printer to
15 parse, format and print Perl data structures.
16 It is passed to plugins so they can rely on contextual information from
18 the caller like colors, spacing and other options.
19
21 Scalar Options
22 show_tainted
23 When set, will detect and let you know of any tainted data (default: 1)
25 Note that this is a no-op unless your script is in taint mode, meaning
26 it's running with different real and effective user/group IDs, or with
27 the -T flag. See perlsec for extra information.
28 show_unicode
30 Whether to label data that has the unicode flag set. (default: 1)
32 show_dualvar
34 Perl can interpret strings as numbers and vice-versa, but that doesn't
36 mean it always gets it right. When this option is set to "lax",
37 Data::Printer will show both values if they differ. If set to "strict",
38 it will always show both values, and when set to "off" it will never
39 show the second value. (default: lax)
40 show_lvalue
42 Let's you know whenever a value is an lvalue (default: 1)
44 string_max
46 The maximum number of characters to display in a string. If the string
48 is bigger than that, Data::Printer will trim a part of the string (set
49 by string_preserve) and replace it with the message set on
50 string_overflow. Set "string_max" to 0 to show all characters (default:
51 4096)
52 string_overflow
54 Message to display once string_max is reached. Defaults to
56 "(...skipping __SKIPPED__ chars...)".
57 string_preserve
59 When the string has more characters than string_max, this option
61 defines which part of the string to preserve. Can be set to 'begin',
62 'middle' or 'end'. (default: 'begin')
63 scalar_quotes
65 Which quotation character to use when printing strings (default: ")
67 escape_chars
69 Use this to escape certain characters from strings, which could be
71 useful if your terminal is in a different encoding than the data being
72 printed. Can be set to 'nonascii', 'nonlatin1', 'all' or 'none'
73 (default: none).
74 unicode_charnames
76 whether to use the character's names when escaping unicode (e.g.
78 SNOWMAN instead of \x{2603}) (default: 0)
79 print_escapes
81 Wether to print invisible characters in strings, like \b, \n and \t
83 (default: 0)
84 resolve_scalar_refs
86 If a reference to a scalar value is found more than once, print the
88 resolved value. For example, you may have an object that you reuse to
89 represent 'true' or 'false'. If you have more than one of those in your
90 data, Data::Printer will by default print the second one as a circular
91 reference. When this option is set to true, it will instead resolve the
92 scalar value and keep going. (default: false)
93 Array Options
95 array_max
96 The maximum number of array elements to show. If the array is bigger
98 than that, Data::Printer will trim the offending slice (set by
99 array_preserve) and replace it with the message set on array_overflow.
100 Set "array_max" to 0 to show all elements in the array, regardless of
101 array size (default: 100)
102 array_overflow
104 Message to display once array_max is reached. Defaults to "(...skipping
106 __SKIPPED__ items...)".
107 array_preserve
109 When an array has more elements than array_max, this option defines
111 which part of the array to preserve. Can be set to 'begin', 'middle' or
112 'end'. (default: 'begin')
113 index
115 When set, shows the index number before each array element. (default:
117 1)
118 Hash Options
120 align_hash
122 If this option is set, hash keys will be vertically aligned by the
124 length of the longest key.
125 This is better explained with an example, so consider the hash "my %h =
127 ( a => 123, aaaaaa => 456 )". This would be an unaligned output:
128 a => 123,
130 aaaaaa => 456
131 and this is what it looks like with "align_hash = 1":
133 a => 123,
135 aaaaaa => 456
136 (default: 1)
138 hash_max
140 The maximum number of hash key/value pairs to show. If the hash is
142 bigger than that, Data::Printer will trim the offending slice (set by
143 hash_preserve) and replace it with the message set on hash_overflow.
144 Set "hash_max" to 0 to show all elements in the hash, regardless of the
145 total keys. (default: 100)
146 hash_overflow
148 Message to display once hash_max is reached. Defaults to "(...skipping
150 __SKIPPED__ keys...)".
151 hash_preserve
153 When a hash has more elements than hash_max, this option defines which
155 part of the hash to preserve. Can be set to 'begin', 'middle' or 'end'.
156 Note that Perl makes no promises regarding key order, so this option
157 only makes sense if keys are sorted. In other words, if you have
158 disabled sort_keys, expect random keys to be shown regardless of which
159 part was preserved. (default: 'begin')
160 hash_separator
162 What to use to separate keys from values. Default is ' ' (three
164 spaces)
165 sort_keys
167 Whether to sort keys when printing the contents of a hash (default: 1)
169 quote_keys
171 Whether to quote hash keys or not. Can be set to 1 (always quote), 0
173 (never quote) or 'auto' to quote only when a key contains spaces or
174 linebreaks. (default: 'auto')
175 Caller Information
177 Data::Printer can add an informational message to every call to p() or
178 np() if you enable "caller_info". So for example if you write:
179 my $var = "meep!";
181 p $var, caller_info => 1;
182 this will output something like:
184 Printing in line 2 of myapp.pl:
186 "meep!"
187 The following options let you customize the message and how it is
189 displayed.
190 caller_info
192 Set this option to a true value to display a message next to the data
194 being printed. (default: 0)
195 caller_message
197 What message to print when caller_info is true.
199 Defaults to ""Printing in line __LINE__ of __FILENAME__"".
201 If the special strings "__LINE__", "__FILENAME__" or "__PACKAGE__" are
203 present in the message, they'll be interpolated into their according
204 value so you can customize the message at will:
205 caller_message = "[__PACKAGE__:__LINE__]"
207 caller_message_newline
209 When true, skips a line when printing caller_message. When false, only
211 a single space is added between the message and the data. (default: 1)
212 caller_message_position
214 This option controls where the caller_message will appear in relation
216 to the code being printed. Can be set to 'before' or 'after'. A line is
217 always skipped between the message and the data (either before or
218 after), unless you set caller_message_newline to 0. (default:
219 'before')
220 General Options
222 arrows
223 Data::Printer shows circular references as a data path, indicating
225 where in the data that reference points to. You may use this option to
226 control if/when should it print reference arrows. Possible values are
227 'all' (e.g "var->{x}->[y]->[z]"), 'first' ("var->{x}[y][z]") or 'none'
228 ("var{x}[y][z]"). Default is 'none'.
229 colored
231 Whether to colorize the output or not. Can be set to 1 (always
233 colorize), 0 (never colorize) or 'auto'. Default is 'auto', meaning it
234 will colorize only when printing to STDOUT or STDERR, never to a file
235 or to a variable. The 'auto' setting also respects the
236 "ANSI_COLORS_DISABLED" environment variable.
237 deparse
239 If the data structure contains a subroutine reference (coderef), this
241 option can be set to deparse it and print the underlying code, which
242 hopefully resembles the original source code. (default: 0)
243 coderef_stub
245 If the data structure contains a subroutine reference (coderef) and the
247 'deparse' option above is set to false, Data::Printer will print this
248 instead. (default: '"sub { ... }"')
249 coderef_undefined
251 If the data structure contains a subroutine reference (coderef) that
253 has not actually been defined at the time of inspection, Data::Printer
254 will print this instead. Set it to '0' to disable this check, in which
255 case Data::Printer will use whatever value you set on coderef_stub
256 above. (default: '<undefined coderef>').
257 end_separator
259 When set, the last item on an array or hash will always contain a
261 trailing separator. (default: 0)
262 show_memsize
264 Set to true and Data::Printer will show the estimate memory size of the
266 data structure being printed. Requires Devel::Size. (default: 0)
267 memsize_unit
269 If show_memsize is on, this option lets you specify the unit in which
271 to show the memory size. Can be set to "b" to show size in bytes, "k"
272 for kilobytes, "m" for megabytes or "auto", which will use the biggest
273 unit that makes sense. (default: auto)
274 output
276 Where you want the output to be printed. Can be set to the following
278 values:
279 • 'stderr' - outputs to the standard error handle.
281 • 'stdout' - outputs to the standard output handle.
283 • reference to a scalar (e.g. "\$string") - outputs to the scalar
285 reference.
286 • file handle - any open file handle:
288 open my $fh, '>>', '/path/to/some/file.log' or die $!;
290 p @{[ 1,2,3 ]}, output => $fh;
291 • file path - if you pass a non-empty string that is not 'stderr' nor
293 'stdout', Data::Printer will consider it to be a file path and
294 create/append to it automatically for you. So you can do this in
295 your ".dataprinter":
296 output = /path/to/some/file.log
298 By default, Data::Printer will print to the standard error
300 (stderr).
301 max_depth
303 This setting controls how far inside the data structure we should go
305 (default: 0 for no depth limit)
306 return_value
308 Whether the user wants the return value to be a pass-through of the
310 source data ('pass'), the dump content itself ('dump') or nothing at
311 all ('void').
312 Defaults to 'pass' since version 0.36. NOTE: if you set it to 'dump',
314 make sure it's not the last statement of a subroutine or that, if it
315 is, the sub is only called in void context.
316 separator
318 The separator character(s) to use for arrays and hashes. The default is
320 the comma ",".
321 show_readonly
323 When this option is set, Data::Printer will let you know whenever a
325 value is read-only. (default: 1)
326 show_refcount
328 Whether to show data refcount it's above 1 (default: 0)
330 show_weak
332 When this option is set, Data::Printer will let you know whenever it
334 finds a weak reference (default: 1)
335 show_tied
337 When set to true, this option will let you know whenever a tied
339 variable is detected, including what is tied to it (default: 1)
340 theme
342 theme = Monokai
344 This setting gets/sets the current color theme module. The default
346 theme is Material. Data::Printer ships with several themes for you to
347 choose, and you can create your own theme or use any other from CPAN.
348 warnings
350 If something goes wrong when parsing your data or printing it to the
352 selected output, Data::Printer by default shows you a warning from the
353 standpoint of the actual call to p() or np(). To silence those
354 warnings, set this option to 0.
355 Class / Object Options
357 class_method
358 When Data::Printer is printing an object, it first looks for a method
360 named ""_dataprinter"" and, if one is found, we call it instead of
361 actually parsing the structure.
362 This way, module authors can control how Data::Printer outputs their
364 objects the best possible way by simply adding a private method instead
365 of having to write a full filter or even adding Data::Printer as a
366 dependency.
367 To disable this behavior, simply set this option to false or an empty
369 string. You can also change it to a different name and Data::Printer
370 will look for that instead.
371 class - class properties to override.
373 This "namespace" gets/sets all class properties that are used by the
375 standard class filter that ships with Data::Printer. Note that, if you
376 are using a specific filter for that object, most (if not all) of the
377 settings below will not apply.
378 In your ".dataprinter" file, the defaults would look like this:
380 class.parents = 1
382 class.linear_isa = auto
383 class.universal = 0
384 class.expand = 1
385 class.stringify = 1
386 class.show_reftype = 0
387 class.show_overloads = 1
388 class.show_methods = all
389 class.sort_methods = 1
390 class.inherited = public
391 class.format_inheritance = lines
392 class.parent_filters = 1
393 class.internals = 1
394 In code, you should use the "class" namespace as a key to a hash
396 reference:
397 use Data::Printer class => {
399 parents => 1,
400 linear_isa => 'auto',
401 universal => 0,
402 expand => 1,
403 stringify => 1,
404 show_reftype => 0,
405 show_overloads => 1,
406 show_methods => 'all',
407 sort_methods => 1,
408 inherited => 'public',
409 format_inheritance => 'lines',
410 parent_filters => 1,
411 internals => 1,
412 };
413 Or inline:
415 p $some_object, class => { internals => 1, ... };
417 parents
419 When set, shows all superclasses of the object being printed. (default:
421 1)
422 linear_isa
424 This setting controls whether to show the linearized @ISA, which is the
426 order of preference in which the object's methods and attributes are
427 resolved according to its inheritance. Can be set to 1 (always show), 0
428 (never show) or 'auto', which shows only when the object has more than
429 one superclass. (default: 'auto')
430 universal
432 Set this option to 1 to include UNIVERSAL methods to the list of public
434 methods (like "can" and "isa"). (default: 0)
435 expand
437 Sets how many levels to descend when printing classes, in case their
439 internals point to other classes. Set this to 0 to never expand any
440 objects, just show their name. Set to any integer number and when
441 Data::Printer reaches that depth, only the class name will be printed.
442 Set to 'all' to always expand objects found inside your object.
443 (default: 1)
444 stringify
446 When this option is set, Data::Printer will check if the object being
448 printed contains any methods named "as_string", "to_string" or
449 "stringify". If it does, Data::Printer will use it as the object's
450 output instead of the generic class plugin. (default: 1)
451 show_reftype
453 If set to a true value, Data::Printer will show the internal reference
455 type of the object. (default: 0)
456 show_overloads
458 This option includes a list of all overloads implemented by the object.
460 (default: 1)
461 show_methods
463 Controls which of the object's direct methods to show. Can be set to
465 'none', 'all', 'private' or 'public'. When applicable (Moo, Moose) it
466 will also show attributes and roles. (default: 'all')
467 sort_methods
469 When listing methods, attributes and roles, this option will order them
471 alphabetically, rather than on whatever order the list of methods
472 returned. (default: 1)
473 inherited
475 Controls which of the object's parent methods to show. Can be set to
477 'none', 'all', 'private' or 'public'. (default: 'public')
478 format_inheritance
480 This option controls how to format the list of methods set by a parent
482 class (and not the class itself). Setting it to 'lines' it will print
483 one line for each parent, like so:
484 public methods (5):
486 foo, bar
487 Parent::Class:
488 baz, meep
489 Other::Parent:
490 moop
491 Setting it to 'string', it will put all methods on the same line:
493 public methods (5): foo, bar, baz (Parent::Class), meep (Parent::CLass), moop (Other::Parent)
495 Default is: 'lines'.
497 parent_filters
499 If there is no filter for the given object's class, there may still be
501 a filter for one of its parent classes. When this option is set,
502 Data::Printer will traverse the object's superclass and use the first
503 filter it finds, if one is present. (default: 1)
504 internals
506 Shows the object's internal data structure. (default: 1)
508 "Shortcuts"
510 Some options are so often used together we have created shortcuts for
511 them.
512 as
514 p $somevar, as => 'is this right?';
516 The ""as"" shortcut activates caller_info and sets caller_message to
518 whatever you set it to. It's really useful to quickly differentiate
519 between sequential uses of p().
520 multiline
522 p $somevar, multiline => 0;
524 When set to 0, disables array index and linebreaks, uses ':' as hash
526 separator and '(...)' as overflow for hashes, arrays and strings, and
527 also disables 'caller_message_newline' so any caller message is shown
528 on the same line as the variable being printed. If this is set on a
529 global configuration or on the ".dataprinter" file, Can be "undone" by
530 setting it to "1".
531 fulldump
533 p $somevar, fulldump => 1;
535 By default, Data::Printer limits the size of string/array/hash dumps to
537 a (hopefully) reasonable size. Still, sometimes you really need to see
538 everything. To completely disable such limits, just set this option to
539 true.
540 Methods and Accessors for Filter Writers
542 The following attributes could be useful if you're writing your own
543 custom filters or maybe even a non-obvious profile. Otherwise, no need
544 to worry about any of them ;)
545 And make sure to check out the current filter list for real usage
547 examples!
548 indent
550 outdent
552 newline
554 These methods are used to control the indentation level of the string
556 being created to represent your data. While "indent" and "outdent"
557 respectively increase and decrease the indentation level, "newline"
558 will add a linebreak and position the "cursor" where you are expected
559 to continue your dump string:
560 my $output = $ddp->newline . 'this is a new line';
562 $ddp->indent;
563 $output .= $ddp->newline . 'this is indented';
564 $ddp->outdent;
565 $output .= $ddp->newline . 'back to our previous indentation!';
566 Unless multiline was set to 0, the code above should print something
568 like:
569 this is a new line
571 this is indented
572 back to our previous indentation
573 extra_config
575 Data::Printer will read and pass-through any unrecognized settings in
577 either your ".dataprinter" file or your inline arguments inside this
578 structure. This is useful to create custom settings for your filters.
579 While any and all unknown settings will be readable here, we recommend
581 you prepend them with a namespace like "filter_xxx" as those are
582 reserved for filters and thus guaranteed not to colide with any core
583 Data::Printer settings now or in the future.
584 For example, on the Web filter we have the "expand_headers" option, and
586 even though Data::Printer itself doesn't have this option, we prepend
587 everything with the "filter_web" namespace, either in the config file:
588 filter_web.expand_headers = 1
590 or inline:
592 p $http_response, filters => ['Web'], filter_web => { expand_headers => 1 };
594 maybe_colorize( $string, $label )
596 maybe_colorize( $string, $label, $default_color )
598 my $output = $ddp->maybe_colorize( 12.3, 'number');
600 Instead of simply adding raw content to your dump string, you should
602 wrap it with this method, as it will look up colors on the current
603 theme and print them (or not, depending on whether the terminal
604 supports color or the user has explicitly turned them off).
605 If you are writing a custom filter and don't want to use the core
607 labels to colorize your content, you may want to set your own label and
608 pass a default color. For example:
609 my $output = $ddp->maybe_colorize( $data, 'filter_myclass', '#ffccb3' );
611 In the code above, if the user has "colors.filter_myclass" set either
613 on the ".dataprinter" file or the runtime hashref, that one will be
614 used. Otherwise, Data::Printer will use '#ffccb3'.
615 current_depth
617 Shows the current depth level, from 0 onwards.
619 current_name
621 Gets/sets the name for the current posistion, to be printed when the
623 parser visits that data again. E.g. "var[0]{abc}[2]".
624 parse( $data_ref )
626 parse( $data_ref, %options )
628 This method receives a reference to a data structure to parse, and
630 returns the parsed string. It will call each filter and colorize the
631 output accordingly.
632 Use this inside filters whenever you want to use the result of a parsed
634 data strucure.
635 my $output = $ddp->parse( [3,2,1] );
637 An optional set of parameters may be passed:
639 • "force_type => $type" - forces data to be treated as that type,
641 where $type is the name of the Perl data strucuture as returned by
642 Scalar::Util::reftype (e.g. 'HASH', 'ARRAY' etc). This is used when
643 a filter wants to show the internals of blessed data. Otherwise
644 parse would just call the same filter over and over again.
645 • "seen_override => 1" - Data::Printer::Object tries to remember if
647 it has already seen a data structure before, so it can show the
648 circular reference instead of entenring an infinite loop. However,
649 there are cases when you want to print the same data structure
650 twice, like when you're doing a second pass on a blessed object to
651 print its internals, or if you're using the same object over and
652 over again. This setting overrides the internal counter and prints
653 the same data again. Check unsee below for another way to achieve
654 this.
655 parse_as( $type, $data_ref )
657 This is a convenience method to force some data to be interpreted as a
659 particular type. It is the same as:
660 $ddp->parse( $data, force_type => $type, seen_override => 1 );
662 unsee( $data )
664 Sometimes you are writing a filter for data that you know will be
665 repeated several times, like JSON Boolean objects. To prevent
666 Data::Printer from showing this content as repeated, you can use the
667 "unsee" method to make the current object forget about having ever
668 visited this data.
669
671 You'll most like never need this unless you're planning on extending
672 Data::Printer itself.
673 new( %options )
675 Creates a new Data::Printer::Object instance. It may (optionally)
676 receive a hash or hash reference with custom settings for any of its
677 properties.
678
680 Data::Printer
681perl v5.36.0 2023-01-20 Data::Printer::Object(3)