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
121 If this option is set, hash keys will be vertically aligned by the
123 length of the longest key.
124 This is better explained with an example, so consider the hash "my %h =
126 ( a => 123, aaaaaa => 456 )". This would be an unaligned output:
127 a => 123,
129 aaaaaa => 456
130 and this is what it looks like with "align_hash = 1":
132 a => 123,
134 aaaaaa => 456
135 (default: 1)
137 hash_max
139 The maximum number of hash key/value pairs to show. If the hash is
141 bigger than that, Data::Printer will trim the offending slice (set by
142 hash_preserve) and replace it with the message set on hash_overflow.
143 Set "hash_max" to 0 to show all elements in the hash, regardless of the
144 total keys. (default: 100)
145 hash_overflow
147 Message to display once hash_max is reached. Defaults to "(...skipping
149 __SKIPPED__ keys...)".
150 hash_preserve
152 When a hash has more elements than hash_max, this option defines which
154 part of the hash to preserve. Can be set to 'begin', 'middle' or 'end'.
155 Note that Perl makes no promises regarding key order, so this option
156 only makes sense if keys are sorted. In other words, if you have
157 disabled sort_keys, expect random keys to be shown regardless of which
158 part was preserved. (default: 'begin')
159 hash_separator
161 What to use to separate keys from values. Default is ' ' (three
163 spaces)
164 sort_keys
166 Whether to sort keys when printing the contents of a hash (default: 1)
168 quote_keys
170 Whether to quote hash keys or not. Can be set to 1 (always quote), 0
172 (never quote) or 'auto' to quote only when a key contains spaces or
173 linebreaks. (default: 'auto')
174 Caller Information
176 Data::Printer can add an informational message to every call to p() or
177 np() if you enable "caller_info". So for example if you write:
178 my $var = "meep!";
180 p $var, caller_info => 1;
181 this will output something like:
183 Printing in line 2 of myapp.pl:
185 "meep!"
186 The following options let you customize the message and how it is
188 displayed.
189 caller_info
191 Set this option to a true value to display a message next to the data
193 being printed. (default: 0)
194 caller_message
196 What message to print when caller_info is true.
198 Defaults to ""Printing in line __LINE__ of __FILENAME__"".
200 If the special strings "__LINE__", "__FILENAME__" or "__PACKAGE__" are
202 present in the message, they'll be interpolated into their according
203 value so you can customize the message at will:
204 caller_message = "[__PACKAGE__:__LINE__]"
206 caller_message_newline
208 When true, skips a line when printing caller_message. When false, only
210 a single space is added between the message and the data. (default: 1)
211 caller_message_position
213 This option controls where the caller_message will appear in relation
215 to the code being printed. Can be set to 'before' or 'after'. A line is
216 always skipped between the message and the data (either before or
217 after), unless you set caller_message_newline to 0. (default:
218 'before')
219 General Options
221 arrows
222 Data::Printer shows circular references as a data path, indicating
224 where in the data that reference points to. You may use this option to
225 control if/when should it print reference arrows. Possible values are
226 'all' (e.g "var->{x}->[y]->[z]"), 'first' ("var->{x}[y][z]") or 'none'
227 ("var{x}[y][z]"). Default is 'none'.
228 colored
230 Whether to colorize the output or not. Can be set to 1 (always
232 colorize), 0 (never colorize) or 'auto'. Default is 'auto', meaning it
233 will colorize only when printing to STDOUT or STDERR, never to a file
234 or to a variable. The 'auto' setting also respects the
235 "ANSI_COLORS_DISABLED" environment variable.
236 deparse
238 If the data structure contains a subroutine reference (coderef), this
240 option can be set to deparse it and print the underlying code, which
241 hopefully resembles the original source code. (default: 0)
242 coderef_stub
244 If the data structure contains a subroutine reference (coderef) and the
246 'deparse' option above is set to false, Data::Printer will print this
247 instead. (default: '"sub { ... }"')
248 coderef_undefined
250 If the data structure contains a subroutine reference (coderef) that
252 has not actually been defined at the time of inspection, Data::Printer
253 will print this instead. Set it to '0' to disable this check, in which
254 case Data::Printer will use whatever value you set on coderef_stub
255 above. (default: '<undefined coderef>').
256 end_separator
258 When set, the last item on an array or hash will always contain a
260 trailing separator. (default: 0)
261 show_memsize
263 Set to true and Data::Printer will show the estimate memory size of the
265 data structure being printed. Requires Devel::Size. (default: 0)
266 memsize_unit
268 If show_memsize is on, this option lets you specify the unit in which
270 to show the memory size. Can be set to "b" to show size in bytes, "k"
271 for kilobytes, "m" for megabytes or "auto", which will use the biggest
272 unit that makes sense. (default: auto)
273 output
275 Where you want the output to be printed. Can be set to the following
277 values:
278 • 'stderr' - outputs to the standard error handle.
280 • 'stdout' - outputs to the standard output handle.
282 • reference to a scalar (e.g. "\$string") - outputs to the scalar
284 reference.
285 • file handle - any open file handle:
287 open my $fh, '>>', '/path/to/some/file.log' or die $!;
289 p @{[ 1,2,3 ]}, output => $fh;
290 • file path - if you pass a non-empty string that is not 'stderr' nor
292 'stdout', Data::Printer will consider it to be a file path and
293 create/append to it automatically for you. So you can do this in
294 your ".dataprinter":
295 output = /path/to/some/file.log
297 By default, Data::Printer will print to the standard error
299 (stderr).
300 max_depth
302 This setting controls how far inside the data structure we should go
304 (default: 0 for no depth limit)
305 return_value
307 Whether the user wants the return value to be a pass-through of the
309 source data ('pass'), the dump content itself ('dump') or nothing at
310 all ('void').
311 Defaults to 'pass' since version 0.36. NOTE: if you set it to 'dump',
313 make sure it's not the last statement of a subroutine or that, if it
314 is, the sub is only called in void context.
315 separator
317 The separator character(s) to use for arrays and hashes. The default is
319 the comma ",".
320 show_readonly
322 When this option is set, Data::Printer will let you know whenever a
324 value is read-only. (default: 1)
325 show_refcount
327 Whether to show data refcount it's above 1 (default: 0)
329 show_weak
331 When this option is set, Data::Printer will let you know whenever it
333 finds a weak reference (default: 1)
334 show_tied
336 When set to true, this option will let you know whenever a tied
338 variable is detected, including what is tied to it (default: 1)
339 theme
341 theme = Monokai
343 This setting gets/sets the current color theme module. The default
345 theme is Material. Data::Printer ships with several themes for you to
346 choose, and you can create your own theme or use any other from CPAN.
347 warnings
349 If something goes wrong when parsing your data or printing it to the
351 selected output, Data::Printer by default shows you a warning from the
352 standpoint of the actual call to p() or np(). To silence those
353 warnings, set this option to 0.
354 Class / Object Options
356 class_method
357 When Data::Printer is printing an object, it first looks for a method
359 named ""_data_printer"" and, if one is found, we call it instead of
360 actually parsing the structure.
361 This way, module authors can control how Data::Printer outputs their
363 objects the best possible way by simply adding a private method instead
364 of having to write a full filter or even adding Data::Printer as a
365 dependency.
366 To disable this behavior, simply set this option to false or an empty
368 string. You can also change it to a different name and Data::Printer
369 will look for that instead.
370 class - class properties to override.
372 This "namespace" gets/sets all class properties that are used by the
374 standard class filter that ships with Data::Printer. Note that, if you
375 are using a specific filter for that object, most (if not all) of the
376 settings below will not apply.
377 In your ".dataprinter" file, the defaults would look like this:
379 class.parents = 1
381 class.linear_isa = auto
382 class.universal = 0
383 class.expand = 1
384 class.stringify = 1
385 class.show_reftype = 0
386 class.show_overloads = 1
387 class.show_methods = all
388 class.sort_methods = 1
389 class.inherited = public
390 class.format_inheritance = lines
391 class.parent_filters = 1
392 class.internals = 1
393 In code, you should use the "class" namespace as a key to a hash
395 reference:
396 use Data::Printer class => {
398 parents => 1,
399 linear_isa => 'auto',
400 universal => 0,
401 expand => 1,
402 stringify => 1,
403 show_reftype => 0,
404 show_overloads => 1,
405 show_methods => 'all',
406 sort_methods => 1,
407 inherited => 'public',
408 format_inheritance => 'lines',
409 parent_filters => 1,
410 internals => 1,
411 };
412 Or inline:
414 p $some_object, class => { internals => 1, ... };
416 parents
418 When set, shows all superclasses of the object being printed. (default:
420 1)
421 linear_isa
423 This setting controls whether to show the linearized @ISA, which is the
425 order of preference in which the object's methods and attributes are
426 resolved according to its inheritance. Can be set to 1 (always show), 0
427 (never show) or 'auto', which shows only when the object has more than
428 one superclass. (default: 'auto')
429 universal
431 Set this option to 1 to include UNIVERSAL methods to the list of public
433 methods (like "can" and "isa"). (default: 0)
434 expand
436 Sets how many levels to descend when printing classes, in case their
438 internals point to other classes. Set this to 0 to never expand any
439 objects, just show their name. Set to any integer number and when
440 Data::Printer reaches that depth, only the class name will be printed.
441 Set to 'all' to always expand objects found inside your object.
442 (default: 1)
443 stringify
445 When this option is set, Data::Printer will check if the object being
447 printed contains any methods named "as_string", "to_string" or
448 "stringify". If it does, Data::Printer will use it as the object's
449 output instead of the generic class plugin. (default: 1)
450 show_reftype
452 If set to a true value, Data::Printer will show the internal reference
454 type of the object. (default: 0)
455 show_overloads
457 This option includes a list of all overloads implemented by the object.
459 (default: 1)
460 show_methods
462 Controls which of the object's direct methods to show. Can be set to
464 'none', 'all', 'private' or 'public'. When applicable (Moo, Moose) it
465 will also show attributes and roles. (default: 'all')
466 sort_methods
468 When listing methods, attributes and roles, this option will order them
470 alphabetically, rather than on whatever order the list of methods
471 returned. (default: 1)
472 inherited
474 Controls which of the object's parent methods to show. Can be set to
476 'none', 'all', 'private' or 'public'. (default: 'public')
477 format_inheritance
479 This option controls how to format the list of methods set by a parent
481 class (and not the class itself). Setting it to 'lines' it will print
482 one line for each parent, like so:
483 public methods (5):
485 foo, bar
486 Parent::Class:
487 baz, meep
488 Other::Parent:
489 moop
490 Setting it to 'string', it will put all methods on the same line:
492 public methods (5): foo, bar, baz (Parent::Class), meep (Parent::CLass), moop (Other::Parent)
494 Default is: 'lines'.
496 parent_filters
498 If there is no filter for the given object's class, there may still be
500 a filter for one of its parent classes. When this option is set,
501 Data::Printer will traverse the object's superclass and use the first
502 filter it finds, if one is present. (default: 1)
503 internals
505 Shows the object's internal data structure. (default: 1)
507 "Shortcuts"
509 Some options are so often used together we have created shortcuts for
510 them.
511 as
513 p $somevar, as => 'is this right?';
515 The ""as"" shortcut activates caller_info and sets caller_message to
517 whatever you set it to. It's really useful to quickly differentiate
518 between sequential uses of p().
519 multiline
521 p $somevar, multiline => 0;
523 When set to 0, disables array index and linebreaks, uses ':' as hash
525 separator and '(...)' as overflow for hashes, arrays and strings, and
526 also disables 'caller_message_newline' so any caller message is shown
527 on the same line as the variable being printed. If this is set on a
528 global configuration or on the ".dataprinter" file, Can be "undone" by
529 setting it to "1".
530 fulldump
532 p $somevar, fulldump => 1;
534 By default, Data::Printer limits the size of string/array/hash dumps to
536 a (hopefully) reasonable size. Still, sometimes you really need to see
537 everything. To completely disable such limits, just set this option to
538 true.
539 Methods and Accessors for Filter Writers
541 The following attributes could be useful if you're writing your own
542 custom filters or maybe even a non-obvious profile. Otherwise, no need
543 to worry about any of them ;)
544 And make sure to check out the current filter list for real usage
546 examples!
547 indent
549 outdent
551 newline
553 These methods are used to control the indentation level of the string
555 being created to represent your data. While "indent" and "outdent"
556 respectively increase and decrease the indentation level, "newline"
557 will add a linebreak and position the "cursor" where you are expected
558 to continue your dump string:
559 my $output = $ddp->newline . 'this is a new line';
561 $ddp->indent;
562 $output .= $ddp->newline . 'this is indented';
563 $ddp->outdent;
564 $output .= $ddp->newline . 'back to our previous indentation!';
565 Unless multiline was set to 0, the code above should print something
567 like:
568 this is a new line
570 this is indented
571 back to our previous indentation
572 extra_config
574 Data::Printer will read and pass-through any unrecognized settings in
576 either your ".dataprinter" file or your inline arguments inside this
577 structure. This is useful to create custom settings for your filters.
578 While any and all unknown settings will be readable here, we recommend
580 you prepend them with a namespace like "filter_xxx" as those are
581 reserved for filters and thus guaranteed not to colide with any core
582 Data::Printer settings now or in the future.
583 For example, on the Web filter we have the "expand_headers" option, and
585 even though Data::Printer itself doesn't have this option, we prepend
586 everything with the "filter_web" namespace, either in the config file:
587 filter_web.expand_headers = 1
589 or inline:
591 p $http_response, filters => ['Web'], filter_web => { expand_headers => 1 };
593 maybe_colorize( $string, $label )
595 maybe_colorize( $string, $label, $default_color )
597 my $output = $ddp->maybe_colorize( 12.3, 'number');
599 Instead of simply adding raw content to your dump string, you should
601 wrap it with this method, as it will look up colors on the current
602 theme and print them (or not, depending on whether the terminal
603 supports color or the user has explicitly turned them off).
604 If you are writing a custom filter and don't want to use the core
606 labels to colorize your content, you may want to set your own label and
607 pass a default color. For example:
608 my $output = $ddp->maybe_colorize( $data, 'filter_myclass', '#ffccb3' );
610 In the code above, if the user has "colors.filter_myclass" set either
612 on the ".dataprinter" file or the runtime hashref, that one will be
613 used. Otherwise, Data::Printer will use '#ffccb3'.
614 current_depth
616 Shows the current depth level, from 0 onwards.
618 current_name
620 Gets/sets the name for the current posistion, to be printed when the
622 parser visits that data again. E.g. "var[0]{abc}[2]".
623 parse( $data_ref )
625 parse( $data_ref, %options )
627 This method receives a reference to a data structure to parse, and
629 returns the parsed string. It will call each filter and colorize the
630 output accordingly.
631 Use this inside filters whenever you want to use the result of a parsed
633 data strucure.
634 my $output = $ddp->parse( [3,2,1] );
636 An optional set of parameters may be passed:
638 • "force_type => $type" - forces data to be treated as that type,
640 where $type is the name of the Perl data strucuture as returned by
641 Scalar::Util::reftype (e.g. 'HASH', 'ARRAY' etc). This is used when
642 a filter wants to show the internals of blessed data. Otherwise
643 parse would just call the same filter over and over again.
644 • "seen_override => 1" - Data::Printer::Object tries to remember if
646 it has already seen a data structure before, so it can show the
647 circular reference instead of entenring an infinite loop. However,
648 there are cases when you want to print the same data structure
649 twice, like when you're doing a second pass on a blessed object to
650 print its internals, or if you're using the same object over and
651 over again. This setting overrides the internal counter and prints
652 the same data again. Check unsee below for another way to achieve
653 this.
654 parse_as( $type, $data_ref )
656 This is a convenience method to force some data to be interpreted as a
658 particular type. It is the same as:
659 $ddp->parse( $data, force_type => $type, seen_override => 1 );
661 unsee( $data )
663 Sometimes you are writing a filter for data that you know will be
664 repeated several times, like JSON Boolean objects. To prevent
665 Data::Printer from showing this content as repeated, you can use the
666 "unsee" method to make the current object forget about having ever
667 visited this data.
668
670 You'll most like never need this unless you're planning on extending
671 Data::Printer itself.
672 new( %options )
674 Creates a new Data::Printer::Object instance. It may (optionally)
675 receive a hash or hash reference with custom settings for any of its
676 properties.
677
679 Data::Printer
680perl v5.38.0 2023-07-31 Data::Printer::Object(3)