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()"
178 or "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, this options can
241 be set to deparse it and print the underlying code, which hopefully
242 resembles the original source code. (default: 0)
243 end_separator
245 When set, the last item on an array or hash will always contain a
247 trailing separator. (default: 0)
248 show_memsize
250 Set to true and Data::Printer will show the estimate memory size of the
252 data structure being printed. Requires Devel::Size. (default: 0)
253 memsize_unit
255 If show_memsize is on, this option lets you specify the unit in which
257 to show the memory size. Can be set to "b" to show size in bytes, "k"
258 for kilobytes, "m" for megabytes or "auto", which will use the biggest
259 unit that makes sense. (default: auto)
260 output
262 Where you want the output to be printed. Can be set to the following
264 values:
265 • 'stderr' - outputs to the standard error handle.
267 • 'stdout' - outputs to the standard output handle.
269 • reference to a scalar (e.g. "\$string") - outputs to the scalar
271 reference.
272 • file handle - any open file handle:
274 open my $fh, '>>', '/path/to/some/file.log' or die $!;
276 p @{[ 1,2,3 ]}, output => $fh;
277 • file path - if you pass a non-empty string that is not 'stderr' nor
279 'stdout', Data::Printer will consider it to be a file path and
280 create/append to it automatically for you. So you can do this in
281 your ".dataprinter":
282 output = /path/to/some/file.log
284 By default, Data::Printer will print to the standard error
286 (stderr).
287 max_depth
289 This setting controls how far inside the data structure we should go
291 (default: 0 for no depth limit)
292 return_value
294 Whether the user wants the return value to be a pass-through of the
296 source data ('pass'), the dump content itself ('dump') or nothing at
297 all ('void').
298 Defaults to 'pass' since version 0.36. NOTE: if you set it to 'dump',
300 make sure it's not the last statement of a subroutine or that, if it
301 is, the sub is only called in void context.
302 separator
304 The separator character(s) to use for arrays and hashes. The default is
306 the comma ",".
307 show_readonly
309 When this option is set, Data::Printer will let you know whenever a
311 value is read-only. (default: 1)
312 show_refcount
314 Whether to show data refcount it's above 1 (default: 0)
316 show_weak
318 When this option is set, Data::Printer will let you know whenever it
320 finds a weak reference (default: 1)
321 show_tied
323 When set to true, this option will let you know whenever a tied
325 variable is detected, including what is tied to it (default: 1)
326 theme
328 theme = Monokai
330 This setting gets/sets the current color theme module. The default
332 theme is Material. Data::Printer ships with several themes for you to
333 choose, and you can create your own theme or use any other from CPAN.
334 warnings
336 If something goes wrong when parsing your data or printing it to the
338 selected output, Data::Printer by default shows you a warning from the
339 standpoint of the actual call to "p()" or "np()". To silence those
340 warnings, set this option to 0.
341 Class / Object Options
343 class_method
344 When Data::Printer is printing an object, it first looks for a method
346 named ""_dataprinter"" and, if one is found, we call it instead of
347 actually parsing the structure.
348 This way, module authors can control how Data::Printer outputs their
350 objects the best possible way by simply adding a private method instead
351 of having to write a full filter or even adding Data::Printer as a
352 dependency.
353 To disable this behavior, simply set this option to false or an empty
355 string. You can also change it to a different name and Data::Printer
356 will look for that instead.
357 class - class properties to override.
359 This "namespace" gets/sets all class properties that are used by the
361 standard class filter that ships with Data::Printer. Note that, if you
362 are using a specific filter for that object, most (if not all) of the
363 settings below will not apply.
364 In your ".dataprinter" file, the defaults would look like this:
366 class.parents = 1
368 class.linear_isa = auto
369 class.universal = 0
370 class.expand = 1
371 class.stringify = 1
372 class.show_reftype = 0
373 class.show_overloads = 1
374 class.show_methods = all
375 class.sort_methods = 1
376 class.inherited = public
377 class.format_inheritance = lines
378 class.parent_filters = 1
379 class.internals = 1
380 In code, you should use the "class" namespace as a key to a hash
382 reference:
383 use Data::Printer class => {
385 parents => 1,
386 linear_isa => 'auto',
387 universal => 0,
388 expand => 1,
389 stringify => 1,
390 show_reftype => 0,
391 show_overloads => 1,
392 show_methods => 'all',
393 sort_methods => 1,
394 inherited => 'public',
395 format_inheritance => 'lines',
396 parent_filters => 1,
397 internals => 1,
398 };
399 Or inline:
401 p $some_object, class => { internals => 1, ... };
403 parents
405 When set, shows all superclasses of the object being printed. (default:
407 1)
408 linear_isa
410 This setting controls whether to show the linearized @ISA, which is the
412 order of preference in which the object's methods and attributes are
413 resolved according to its inheritance. Can be set to 1 (always show), 0
414 (never show) or 'auto', which shows only when the object has more than
415 one superclass. (default: 'auto')
416 universal
418 Set this option to 1 to include UNIVERSAL methods to the list of public
420 methods (like "can" and "isa"). (default: 0)
421 expand
423 Sets how many levels to descend when printing classes, in case their
425 internals point to other classes. Set this to 0 to never expand any
426 objects, just show their name. Set to any integer number and when
427 Data::Printer reaches that depth, only the class name will be printed.
428 Set to 'all' to always expand objects found inside your object.
429 (default: 1)
430 stringify
432 When this option is set, Data::Printer will check if the object being
434 printed contains any methods named "as_string", "to_string" or
435 "stringify". If it does, Data::Printer will use it as the object's
436 output instead of the generic class plugin. (default: 1)
437 show_reftype
439 If set to a true value, Data::Printer will show the internal reference
441 type of the object. (default: 0)
442 show_overloads
444 This option includes a list of all overloads implemented by the object.
446 (default: 1)
447 show_methods
449 Controls which of the object's direct methods to show. Can be set to
451 'none', 'all', 'private' or 'public'. (default: 'all')
452 sort_methods
454 When listing methods, this option will order them alphabetically,
456 rather than on whatever order the list of methods returned. (default:
457 1)
458 inherited
460 Controls which of the object's parent methods to show. Can be set to
462 'none', 'all', 'private' or 'public'. (default: 'public')
463 format_inheritance
465 This option controls how to format the list of methods set by a parent
467 class (and not the class itself). Setting it to 'lines' it will print
468 one line for each parent, like so:
469 public methods (5):
471 foo, bar
472 Parent::Class:
473 baz, meep
474 Other::Parent:
475 moop
476 Setting it to 'string', it will put all methods on the same line:
478 public methods (5): foo, bar, baz (Parent::Class), meep (Parent::CLass), moop (Other::Parent)
480 Default is: 'lines'.
482 parent_filters
484 If there is no filter for the given object's class, there may still be
486 a filter for one of its parent classes. When this option is set,
487 Data::Printer will traverse the object's superclass and use the first
488 filter it finds, if one is present. (default: 1)
489 internals
491 Shows the object's internal data structure. (default: 1)
493 "Shortcuts"
495 Some options are so often used together we have created shortcuts for
496 them.
497 as
499 p $somevar, as => 'is this right?';
501 The ""as"" shortcut activates caller_info and sets caller_message to
503 whatever you set it to. It's really useful to quickly differentiate
504 between sequential uses of "p()".
505 multiline
507 p $somevar, multiline => 0;
509 When set to 0, disables array index and linebreaks, uses ':' as hash
511 separator and '(...)' as overflow for hashes, arrays and strings, and
512 also disables 'caller_message_newline' so any caller message is shown
513 on the same line as the variable being printed. If this is set on a
514 global configuration or on the ".dataprinter" file, Can be "undone" by
515 setting it to "1".
516 fulldump
518 p $somevar, fulldump => 1;
520 By default, Data::Printer limits the size of string/array/hash dumps to
522 a (hopefully) reasonable size. Still, sometimes you really need to see
523 everything. To completely disable such limits, just set this option to
524 true.
525 Methods and Accessors for Filter Writers
527 The following attributes could be useful if you're writing your own
528 custom filters or maybe even a non-obvious profile. Otherwise, no need
529 to worry about any of them ;)
530 And make sure to check out the current filter list for real usage
532 examples!
533 indent
535 outdent
537 newline
539 These methods are used to control the indentation level of the string
541 being created to represent your data. While "indent" and "outdent"
542 respectively increase and decrease the indentation level, "newline"
543 will add a linebreak and position the "cursor" where you are expected
544 to continue your dump string:
545 my $output = $ddp->newline . 'this is a new line';
547 $ddp->indent;
548 $output .= $ddp->newline . 'this is indented';
549 $ddp->outdent;
550 $output .= $ddp->newline . 'back to our previous indentation!';
551 Unless multiline was set to 0, the code above should print something
553 like:
554 this is a new line
556 this is indented
557 back to our previous indentation
558 extra_config
560 Data::Printer will read and pass-through any unrecognized settings in
562 either your ".dataprinter" file or your inline arguments inside this
563 structure. This is useful to create custom settings for your filters.
564 While any and all unknown settings will be readable here, we recommend
566 you prepend them with a namespace like "filter_xxx" as those are
567 reserved for filters and thus guaranteed not to colide with any core
568 Data::Printer settings now or in the future.
569 For example, on the Web filter we have the "expand_headers" option, and
571 even though Data::Printer itself doesn't have this option, we prepend
572 everything with the "filter_web" namespace, either in the config file:
573 filter_web.expand_headers = 1
575 or inline:
577 p $http_response, filters => ['Web'], filter_web => { expand_headers => 1 };
579 maybe_colorize( $string, $label )
581 maybe_colorize( $string, $label, $default_color )
583 my $output = $ddp->maybe_colorize( 12.3, 'number');
585 Instead of simply adding raw content to your dump string, you should
587 wrap it with this method, as it will look up colors on the current
588 theme and print them (or not, depending on whether the terminal
589 supports color or the user has explicitly turned them off).
590 If you are writing a custom filter and don't want to use the core
592 labels to colorize your content, you may want to set your own label and
593 pass a default color. For example:
594 my $output = $ddp->maybe_colorize( $data, 'filter_myclass', '#ffccb3' );
596 In the code above, if the user has "colors.filter_myclass" set either
598 on the ".dataprinter" file or the runtime hashref, that one will be
599 used. Otherwise, Data::Printer will use '#ffccb3'.
600 current_depth
602 Shows the current depth level, from 0 onwards.
604 current_name
606 Gets/sets the name for the current posistion, to be printed when the
608 parser visits that data again. E.g. "var[0]{abc}[2]".
609 parse( $data_ref )
611 parse( $data_ref, %options )
613 This method receives a reference to a data structure to parse, and
615 returns the parsed string. It will call each filter and colorize the
616 output accordingly.
617 Use this inside filters whenever you want to use the result of a parsed
619 data strucure.
620 my $output = $ddp->parse( [3,2,1] );
622 An optional set of parameters may be passed:
624 • "force_type => $type" - forces data to be treated as that type,
626 where $type is the name of the Perl data strucuture as returned by
627 Scalar::Util::reftype (e.g. 'HASH', 'ARRAY' etc). This is used when
628 a filter wants to show the internals of blessed data. Otherwise
629 parse would just call the same filter over and over again.
630 • "seen_override => 1" - Data::Printer::Object tries to remember if
632 it has already seen a data structure before, so it can show the
633 circular reference instead of entenring an infinite loop. However,
634 there are cases when you want to print the same data structure
635 twice, like when you're doing a second pass on a blessed object to
636 print its internals, or if you're using the same object over and
637 over again. This setting overrides the internal counter and prints
638 the same data again. Check unsee below for another way to achieve
639 this.
640 parse_as( $type, $data_ref )
642 This is a convenience method to force some data to be interpreted as a
644 particular type. It is the same as:
645 $ddp->parse( $data, force_type => $type, seen_override => 1 );
647 unsee( $data )
649 Sometimes you are writing a filter for data that you know will be
650 repeated several times, like JSON Boolean objects. To prevent
651 Data::Printer from showing this content as repeated, you can use the
652 "unsee" method to make the current object forget about having ever
653 visited this data.
654
656 You'll most like never need this unless you're planning on extending
657 Data::Printer itself.
658 new( %options )
660 Creates a new Data::Printer::Object instance. It may (optionally)
661 receive a hash or hash reference with custom settings for any of its
662 properties.
663
665 Data::Printer
666perl v5.34.0 2022-01-21 Data::Printer::Object(3)