1Data::Printer::Object(3U)ser Contributed Perl DocumentatiDoanta::Printer::Object(3)
2
3
4

NAME

6       Data::Printer::Object - underlying object for Data::Printer
7

SYNOPSIS

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

DESCRIPTION

14       This module implements the underlying object used by Data::Printer to
15       parse, format and print Perl data structures.
16
17       It is passed to plugins so they can rely on contextual information from
18       the caller like colors, spacing and other options.
19

COMMON PROPERTIES / ATTRIBUTES

21   Scalar Options
22       show_tainted
23
24       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
29       show_unicode
30
31       Whether to label data that has the unicode flag set. (default: 1)
32
33       show_dualvar
34
35       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
41       show_lvalue
42
43       Let's you know whenever a value is an lvalue (default: 1)
44
45       string_max
46
47       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
53       string_overflow
54
55       Message to display once string_max is reached. Defaults to
56       "(...skipping __SKIPPED__ chars...)".
57
58       string_preserve
59
60       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
64       scalar_quotes
65
66       Which quotation character to use when printing strings (default: ")
67
68       escape_chars
69
70       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
75       unicode_charnames
76
77       whether to use the character's names when escaping unicode (e.g.
78       SNOWMAN instead of \x{2603}) (default: 0)
79
80       print_escapes
81
82       Wether to print invisible characters in strings, like \b, \n and \t
83       (default: 0)
84
85       resolve_scalar_refs
86
87       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
94   Array Options
95       array_max
96
97       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
103       array_overflow
104
105       Message to display once array_max is reached. Defaults to "(...skipping
106       __SKIPPED__ items...)".
107
108       array_preserve
109
110       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
114       index
115
116       When set, shows the index number before each array element. (default:
117       1)
118
119       Hash Options
120
121       align_hash
122
123       If this option is set, hash keys  will be vertically aligned by the
124       length of the longest key.
125
126       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
129           a => 123,
130           aaaaaa => 456
131
132       and this is what it looks like with "align_hash = 1":
133
134           a      => 123,
135           aaaaaa => 456
136
137       (default: 1)
138
139       hash_max
140
141       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
147       hash_overflow
148
149       Message to display once hash_max is reached. Defaults to "(...skipping
150       __SKIPPED__ keys...)".
151
152       hash_preserve
153
154       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
161       hash_separator
162
163       What to use to separate keys from values. Default is '   ' (three
164       spaces)
165
166       sort_keys
167
168       Whether to sort keys when printing the contents of a hash (default: 1)
169
170       quote_keys
171
172       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
176   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
180           my $var = "meep!";
181           p $var, caller_info => 1;
182
183       this will output something like:
184
185           Printing in line 2 of myapp.pl:
186           "meep!"
187
188       The following options let you customize the message and how it is
189       displayed.
190
191       caller_info
192
193       Set this option to a true value to display a message next to the data
194       being printed. (default: 0)
195
196       caller_message
197
198       What message to print when caller_info is true.
199
200       Defaults to ""Printing in line __LINE__ of __FILENAME__"".
201
202       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
206           caller_message = "[__PACKAGE__:__LINE__]"
207
208       caller_message_newline
209
210       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
213       caller_message_position
214
215       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
221   General Options
222       arrows
223
224       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
230       colored
231
232       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
238       deparse
239
240       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
244       end_separator
245
246       When set, the last item on an array or hash will always contain a
247       trailing separator. (default: 0)
248
249       show_memsize
250
251       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
254       memsize_unit
255
256       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
261       output
262
263       Where you want the output to be printed. Can be set to the following
264       values:
265
266       •   'stderr' - outputs to the standard error handle.
267
268       •   'stdout' - outputs to the standard output handle.
269
270       •   reference to a scalar (e.g. "\$string") - outputs to the scalar
271           reference.
272
273       •   file handle - any open file handle:
274
275               open my $fh, '>>', '/path/to/some/file.log' or die $!;
276               p @{[ 1,2,3 ]}, output => $fh;
277
278       •   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
283               output = /path/to/some/file.log
284
285           By default, Data::Printer will print to the standard error
286           (stderr).
287
288       max_depth
289
290       This setting controls how far inside the data structure we should go
291       (default: 0 for no depth limit)
292
293       return_value
294
295       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
299       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
303       separator
304
305       The separator character(s) to use for arrays and hashes. The default is
306       the comma ",".
307
308       show_readonly
309
310       When this option is set, Data::Printer will let you know whenever a
311       value is read-only. (default: 1)
312
313       show_refcount
314
315       Whether to show data refcount it's above 1 (default: 0)
316
317       show_weak
318
319       When this option is set, Data::Printer will let you know whenever it
320       finds a weak reference (default: 1)
321
322       show_tied
323
324       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
327       theme
328
329           theme = Monokai
330
331       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
335       warnings
336
337       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
342   Class / Object Options
343       class_method
344
345       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
349       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
354       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
358       class - class properties to override.
359
360       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
365       In your ".dataprinter" file, the defaults would look like this:
366
367           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
381       In code, you should use the "class" namespace as a key to a hash
382       reference:
383
384           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
400       Or inline:
401
402           p $some_object, class => { internals => 1,  ... };
403
404       parents
405
406       When set, shows all superclasses of the object being printed. (default:
407       1)
408
409       linear_isa
410
411       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
417       universal
418
419       Set this option to 1 to include UNIVERSAL methods to the list of public
420       methods (like "can" and "isa"). (default: 0)
421
422       expand
423
424       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
431       stringify
432
433       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
438       show_reftype
439
440       If set to a true value, Data::Printer will show the internal reference
441       type of the object. (default: 0)
442
443       show_overloads
444
445       This option includes a list of all overloads implemented by the object.
446       (default: 1)
447
448       show_methods
449
450       Controls which of the object's direct methods to show. Can be set to
451       'none', 'all', 'private' or 'public'. (default: 'all')
452
453       sort_methods
454
455       When listing methods, this option will order them alphabetically,
456       rather than on whatever order the list of methods returned. (default:
457       1)
458
459       inherited
460
461       Controls which of the object's parent methods to show. Can be set to
462       'none', 'all', 'private' or 'public'. (default: 'public')
463
464       format_inheritance
465
466       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
470           public methods (5):
471               foo, bar
472               Parent::Class:
473                   baz, meep
474               Other::Parent:
475                   moop
476
477       Setting it to 'string', it will put all methods on the same line:
478
479           public methods (5): foo, bar, baz (Parent::Class), meep (Parent::CLass), moop (Other::Parent)
480
481       Default is: 'lines'.
482
483       parent_filters
484
485       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
490       internals
491
492       Shows the object's internal data structure. (default: 1)
493
494   "Shortcuts"
495       Some options are so often used together we have created shortcuts for
496       them.
497
498       as
499
500           p $somevar, as => 'is this right?';
501
502       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
506       multiline
507
508           p $somevar, multiline => 0;
509
510       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
517       fulldump
518
519           p $somevar, fulldump => 1;
520
521       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
526   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
531       And make sure to check out the current filter list for real usage
532       examples!
533
534       indent
535
536       outdent
537
538       newline
539
540       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
546           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
552       Unless multiline was set to 0, the code above should print something
553       like:
554
555           this is a new line
556               this is indented
557           back to our previous indentation
558
559       extra_config
560
561       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
565       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
570       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
574           filter_web.expand_headers = 1
575
576       or inline:
577
578           p $http_response, filters => ['Web'], filter_web => { expand_headers => 1 };
579
580       maybe_colorize( $string, $label )
581
582       maybe_colorize( $string, $label, $default_color )
583
584           my $output = $ddp->maybe_colorize( 12.3, 'number');
585
586       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
591       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
595           my $output = $ddp->maybe_colorize( $data, 'filter_myclass', '#ffccb3' );
596
597       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
601       current_depth
602
603       Shows the current depth level, from 0 onwards.
604
605       current_name
606
607       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
610       parse( $data_ref )
611
612       parse( $data_ref, %options )
613
614       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
618       Use this inside filters whenever you want to use the result of a parsed
619       data strucure.
620
621           my $output = $ddp->parse( [3,2,1] );
622
623       An optional set of parameters may be passed:
624
625       •   "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
631       •   "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
641       parse_as( $type, $data_ref )
642
643       This is a convenience method to force some data to be interpreted as a
644       particular type. It is the same as:
645
646           $ddp->parse( $data, force_type => $type, seen_override => 1 );
647
648   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

OBJECT CONSTRUCTION

656       You'll most like never need this unless you're planning on extending
657       Data::Printer itself.
658
659   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

SEE ALSO

665       Data::Printer
666
667
668
669perl v5.34.0                      2022-01-21          Data::Printer::Object(3)
Impressum