Data::Printer::Object(User Contributed Perl DocumentData::Printer::Object(3pm)
NAME
Data::Printer::Object - underlying object for Data::Printer
SYNOPSIS
Unless you're writing a plugin, or looking for some configuration
property details the documentation you want is probably on
Data::Printer. Seriously!
DESCRIPTION
This module implements the underlying object used by Data::Printer to
parse, format and print Perl data structures.
It is passed to plugins so they can rely on contextual information from
the caller like colors, spacing and other options.
COMMON PROPERTIES / ATTRIBUTES
Scalar Options
show_tainted
When set, will detect and let you know of any tainted data (default: 1)
Note that this is a no-op unless your script is in taint mode, meaning
it's running with different real and effective user/group IDs, or with
the -T flag. See perlsec for extra information.
show_unicode
Whether to label data that has the unicode flag set. (default: 1)
show_dualvar
Perl can interpret strings as numbers and vice-versa, but that doesn't
mean it always gets it right. When this option is set to "lax",
Data::Printer will show both values if they differ. If set to "strict",
it will always show both values, and when set to "off" it will never
show the second value. (default: lax)
show_lvalue
Let's you know whenever a value is an lvalue (default: 1)
string_max
The maximum number of characters to display in a string. If the string
is bigger than that, Data::Printer will trim a part of the string (set
by string_preserve) and replace it with the message set on
string_overflow. Set "string_max" to 0 to show all characters (default:
4096)
string_overflow
Message to display once string_max is reached. Defaults to
"(...skipping __SKIPPED__ chars...)".
string_preserve
When the string has more characters than string_max, this option
defines which part of the string to preserve. Can be set to 'begin',
'middle' or 'end'. (default: 'begin')
scalar_quotes
Which quotation character to use when printing strings (default: ")
escape_chars
Use this to escape certain characters from strings, which could be
useful if your terminal is in a different encoding than the data being
printed. Can be set to 'nonascii', 'nonlatin1', 'all' or 'none'
(default: none).
unicode_charnames
whether to use the character's names when escaping unicode (e.g.
SNOWMAN instead of \x{2603}) (default: 0)
print_escapes
Wether to print invisible characters in strings, like \b, \n and \t
(default: 0)
resolve_scalar_refs
If a reference to a scalar value is found more than once, print the
resolved value. For example, you may have an object that you reuse to
represent 'true' or 'false'. If you have more than one of those in your
data, Data::Printer will by default print the second one as a circular
reference. When this option is set to true, it will instead resolve the
scalar value and keep going. (default: false)
Array Options
array_max
The maximum number of array elements to show. If the array is bigger
than that, Data::Printer will trim the offending slice (set by
array_preserve) and replace it with the message set on array_overflow.
Set "array_max" to 0 to show all elements in the array, regardless of
array size (default: 100)
array_overflow
Message to display once array_max is reached. Defaults to "(...skipping
__SKIPPED__ items...)".
array_preserve
When an array has more elements than array_max, this option defines
which part of the array to preserve. Can be set to 'begin', 'middle' or
'end'. (default: 'begin')
index
When set, shows the index number before each array element. (default:
1)
Hash Options
align_hash
If this option is set, hash keys will be vertically aligned by the
length of the longest key.
This is better explained with an example, so consider the hash "my %h =
( a => 123, aaaaaa => 456 )". This would be an unaligned output:
a => 123,
aaaaaa => 456
and this is what it looks like with "align_hash = 1":
a => 123,
aaaaaa => 456
(default: 1)
hash_max
The maximum number of hash key/value pairs to show. If the hash is
bigger than that, Data::Printer will trim the offending slice (set by
hash_preserve) and replace it with the message set on hash_overflow.
Set "hash_max" to 0 to show all elements in the hash, regardless of the
total keys. (default: 100)
hash_overflow
Message to display once hash_max is reached. Defaults to "(...skipping
__SKIPPED__ keys...)".
hash_preserve
When a hash has more elements than hash_max, this option defines which
part of the hash to preserve. Can be set to 'begin', 'middle' or 'end'.
Note that Perl makes no promises regarding key order, so this option
only makes sense if keys are sorted. In other words, if you have
disabled sort_keys, expect random keys to be shown regardless of which
part was preserved. (default: 'begin')
hash_separator
What to use to separate keys from values. Default is ' ' (three
spaces)
sort_keys
Whether to sort keys when printing the contents of a hash (default: 1)
quote_keys
Whether to quote hash keys or not. Can be set to 1 (always quote), 0
(never quote) or 'auto' to quote only when a key contains spaces or
linebreaks. (default: 'auto')
Caller Information
Data::Printer can add an informational message to every call to "p()"
or "np()" if you enable "caller_info". So for example if you write:
my $var = "meep!";
p $var, caller_info => 1;
this will output something like:
Printing in line 2 of myapp.pl:
"meep!"
The following options let you customize the message and how it is
displayed.
caller_info
Set this option to a true value to display a message next to the data
being printed. (default: 0)
caller_message
What message to print when caller_info is true.
Defaults to ""Printing in line __LINE__ of __FILENAME__"".
If the special strings "__LINE__", "__FILENAME__" or "__PACKAGE__" are
present in the message, they'll be interpolated into their according
value so you can customize the message at will:
caller_message = "[__PACKAGE__:__LINE__]"
caller_message_newline
When true, skips a line when printing caller_message. When false, only
a single space is added between the message and the data. (default: 1)
caller_message_position
This option controls where the caller_message will appear in relation
to the code being printed. Can be set to 'before' or 'after'. A line is
always skipped between the message and the data (either before or
after), unless you set caller_message_newline to 0. (default:
'before')
General Options
arrows
Data::Printer shows circular references as a data path, indicating
where in the data that reference points to. You may use this option to
control if/when should it print reference arrows. Possible values are
'all' (e.g "var->{x}->[y]->[z]"), 'first' ("var->{x}[y][z]") or 'none'
("var{x}[y][z]"). Default is 'none'.
colored
Whether to colorize the output or not. Can be set to 1 (always
colorize), 0 (never colorize) or 'auto'. Default is 'auto', meaning it
will colorize only when printing to STDOUT or STDERR, never to a file
or to a variable. The 'auto' setting also respects the
"ANSI_COLORS_DISABLED" environment variable.
deparse
If the data structure contains a subroutine reference, this options can
be set to deparse it and print the underlying code, which hopefully
resembles the original source code. (default: 0)
end_separator
When set, the last item on an array or hash will always contain a
trailing separator. (default: 0)
show_memsize
Set to true and Data::Printer will show the estimate memory size of the
data structure being printed. Requires Devel::Size. (default: 0)
memsize_unit
If show_memsize is on, this option lets you specify the unit in which
to show the memory size. Can be set to "b" to show size in bytes, "k"
for kilobytes, "m" for megabytes or "auto", which will use the biggest
unit that makes sense. (default: auto)
output
Where you want the output to be printed. Can be set to the following
values:
• 'stderr' - outputs to the standard error handle.
• 'stdout' - outputs to the standard output handle.
• reference to a scalar (e.g. "\$string") - outputs to the scalar
reference.
• file handle - any open file handle:
open my $fh, '>>', '/path/to/some/file.log' or die $!;
p @{[ 1,2,3 ]}, output => $fh;
• file path - if you pass a non-empty string that is not 'stderr' nor
'stdout', Data::Printer will consider it to be a file path and
create/append to it automatically for you. So you can do this in
your ".dataprinter":
output = /path/to/some/file.log
By default, Data::Printer will print to the standard error
(stderr).
max_depth
This setting controls how far inside the data structure we should go
(default: 0 for no depth limit)
return_value
Whether the user wants the return value to be a pass-through of the
source data ('pass'), the dump content itself ('dump') or nothing at
all ('void').
Defaults to 'pass' since version 0.36. NOTE: if you set it to 'dump',
make sure it's not the last statement of a subroutine or that, if it
is, the sub is only called in void context.
separator
The separator character(s) to use for arrays and hashes. The default is
the comma ",".
show_readonly
When this option is set, Data::Printer will let you know whenever a
value is read-only. (default: 1)
show_refcount
Whether to show data refcount it's above 1 (default: 0)
show_weak
When this option is set, Data::Printer will let you know whenever it
finds a weak reference (default: 1)
show_tied
When set to true, this option will let you know whenever a tied
variable is detected, including what is tied to it (default: 1)
theme
theme = Monokai
This setting gets/sets the current color theme module. The default
theme is Material. Data::Printer ships with several themes for you to
choose, and you can create your own theme or use any other from CPAN.
warnings
If something goes wrong when parsing your data or printing it to the
selected output, Data::Printer by default shows you a warning from the
standpoint of the actual call to "p()" or "np()". To silence those
warnings, set this option to 0.
Class / Object Options
class_method
When Data::Printer is printing an object, it first looks for a method
named ""_dataprinter"" and, if one is found, we call it instead of
actually parsing the structure.
This way, module authors can control how Data::Printer outputs their
objects the best possible way by simply adding a private method instead
of having to write a full filter or even adding Data::Printer as a
dependency.
To disable this behavior, simply set this option to false or an empty
string. You can also change it to a different name and Data::Printer
will look for that instead.
class - class properties to override.
This "namespace" gets/sets all class properties that are used by the
standard class filter that ships with Data::Printer. Note that, if you
are using a specific filter for that object, most (if not all) of the
settings below will not apply.
In your ".dataprinter" file, the defaults would look like this:
class.parents = 1
class.linear_isa = auto
class.universal = 0
class.expand = 1
class.stringify = 1
class.show_reftype = 0
class.show_overloads = 1
class.show_methods = all
class.sort_methods = 1
class.inherited = public
class.format_inheritance = lines
class.parent_filters = 1
class.internals = 1
In code, you should use the "class" namespace as a key to a hash
reference:
use Data::Printer class => {
parents => 1,
linear_isa => 'auto',
universal => 0,
expand => 1,
stringify => 1,
show_reftype => 0,
show_overloads => 1,
show_methods => 'all',
sort_methods => 1,
inherited => 'public',
format_inheritance => 'lines',
parent_filters => 1,
internals => 1,
};
Or inline:
p $some_object, class => { internals => 1, ... };
parents
When set, shows all superclasses of the object being printed. (default:
1)
linear_isa
This setting controls whether to show the linearized @ISA, which is the
order of preference in which the object's methods and attributes are
resolved according to its inheritance. Can be set to 1 (always show), 0
(never show) or 'auto', which shows only when the object has more than
one superclass. (default: 'auto')
universal
Set this option to 1 to include UNIVERSAL methods to the list of public
methods (like "can" and "isa"). (default: 0)
expand
Sets how many levels to descend when printing classes, in case their
internals point to other classes. Set this to 0 to never expand any
objects, just show their name. Set to any integer number and when
Data::Printer reaches that depth, only the class name will be printed.
Set to 'all' to always expand objects found inside your object.
(default: 1)
stringify
When this option is set, Data::Printer will check if the object being
printed contains any methods named "as_string", "to_string" or
"stringify". If it does, Data::Printer will use it as the object's
output instead of the generic class plugin. (default: 1)
show_reftype
If set to a true value, Data::Printer will show the internal reference
type of the object. (default: 0)
show_overloads
This option includes a list of all overloads implemented by the object.
(default: 1)
show_methods
Controls which of the object's direct methods to show. Can be set to
'none', 'all', 'private' or 'public'. (default: 'all')
sort_methods
When listing methods, this option will order them alphabetically,
rather than on whatever order the list of methods returned. (default:
1)
inherited
Controls which of the object's parent methods to show. Can be set to
'none', 'all', 'private' or 'public'. (default: 'public')
format_inheritance
This option controls how to format the list of methods set by a parent
class (and not the class itself). Setting it to 'lines' it will print
one line for each parent, like so:
public methods (5):
foo, bar
Parent::Class:
baz, meep
Other::Parent:
moop
Setting it to 'string', it will put all methods on the same line:
public methods (5): foo, bar, baz (Parent::Class), meep (Parent::CLass), moop (Other::Parent)
Default is: 'lines'.
parent_filters
If there is no filter for the given object's class, there may still be
a filter for one of its parent classes. When this option is set,
Data::Printer will traverse the object's superclass and use the first
filter it finds, if one is present. (default: 1)
internals
Shows the object's internal data structure. (default: 1)
"Shortcuts"
Some options are so often used together we have created shortcuts for
them.
as
p $somevar, as => 'is this right?';
The ""as"" shortcut activates caller_info and sets caller_message to
whatever you set it to. It's really useful to quickly differentiate
between sequential uses of "p()".
multiline
p $somevar, multiline => 0;
When set to 0, disables array index and linebreaks, uses ':' as hash
separator and '(...)' as overflow for hashes, arrays and strings, and
also disables 'caller_message_newline' so any caller message is shown
on the same line as the variable being printed. If this is set on a
global configuration or on the ".dataprinter" file, Can be "undone" by
setting it to "1".
fulldump
p $somevar, fulldump => 1;
By default, Data::Printer limits the size of string/array/hash dumps to
a (hopefully) reasonable size. Still, sometimes you really need to see
everything. To completely disable such limits, just set this option to
true.
Methods and Accessors for Filter Writers
The following attributes could be useful if you're writing your own
custom filters or maybe even a non-obvious profile. Otherwise, no need
to worry about any of them ;)
And make sure to check out the current filter list for real usage
examples!
indent
outdent
newline
These methods are used to control the indentation level of the string
being created to represent your data. While "indent" and "outdent"
respectively increase and decrease the indentation level, "newline"
will add a linebreak and position the "cursor" where you are expected
to continue your dump string:
my $output = $ddp->newline . 'this is a new line';
$ddp->indent;
$output .= $ddp->newline . 'this is indented';
$ddp->outdent;
$output .= $ddp->newline . 'back to our previous indentation!';
Unless multiline was set to 0, the code above should print something
like:
this is a new line
this is indented
back to our previous indentation
extra_config
Data::Printer will read and pass-through any unrecognized settings in
either your ".dataprinter" file or your inline arguments inside this
structure. This is useful to create custom settings for your filters.
While any and all unknown settings will be readable here, we recommend
you prepend them with a namespace like "filter_xxx" as those are
reserved for filters and thus guaranteed not to colide with any core
Data::Printer settings now or in the future.
For example, on the Web filter we have the "expand_headers" option, and
even though Data::Printer itself doesn't have this option, we prepend
everything with the "filter_web" namespace, either in the config file:
filter_web.expand_headers = 1
or inline:
p $http_response, filters => ['Web'], filter_web => { expand_headers => 1 };
maybe_colorize( $string, $label )
maybe_colorize( $string, $label, $default_color )
my $output = $ddp->maybe_colorize( 12.3, 'number');
Instead of simply adding raw content to your dump string, you should
wrap it with this method, as it will look up colors on the current
theme and print them (or not, depending on whether the terminal
supports color or the user has explicitly turned them off).
If you are writing a custom filter and don't want to use the core
labels to colorize your content, you may want to set your own label and
pass a default color. For example:
my $output = $ddp->maybe_colorize( $data, 'filter_myclass', '#ffccb3' );
In the code above, if the user has "colors.filter_myclass" set either
on the ".dataprinter" file or the runtime hashref, that one will be
used. Otherwise, Data::Printer will use '#ffccb3'.
current_depth
Shows the current depth level, from 0 onwards.
current_name
Gets/sets the name for the current posistion, to be printed when the
parser visits that data again. E.g. "var[0]{abc}[2]".
parse( $data_ref )
parse( $data_ref, %options )
This method receives a reference to a data structure to parse, and
returns the parsed string. It will call each filter and colorize the
output accordingly.
Use this inside filters whenever you want to use the result of a parsed
data strucure.
my $output = $ddp->parse( [3,2,1] );
An optional set of parameters may be passed:
• "force_type => $type" - forces data to be treated as that type,
where $type is the name of the Perl data strucuture as returned by
Scalar::Util::reftype (e.g. 'HASH', 'ARRAY' etc). This is used when
a filter wants to show the internals of blessed data. Otherwise
parse would just call the same filter over and over again.
• "seen_override => 1" - Data::Printer::Object tries to remember if
it has already seen a data structure before, so it can show the
circular reference instead of entenring an infinite loop. However,
there are cases when you want to print the same data structure
twice, like when you're doing a second pass on a blessed object to
print its internals, or if you're using the same object over and
over again. This setting overrides the internal counter and prints
the same data again. Check unsee below for another way to achieve
this.
parse_as( $type, $data_ref )
This is a convenience method to force some data to be interpreted as a
particular type. It is the same as:
$ddp->parse( $data, force_type => $type, seen_override => 1 );
unsee( $data )
Sometimes you are writing a filter for data that you know will be
repeated several times, like JSON Boolean objects. To prevent
Data::Printer from showing this content as repeated, you can use the
"unsee" method to make the current object forget about having ever
visited this data.
OBJECT CONSTRUCTION
You'll most like never need this unless you're planning on extending
Data::Printer itself.
new( %options )
Creates a new Data::Printer::Object instance. It may (optionally)
receive a hash or hash reference with custom settings for any of its
properties.
SEE ALSO
Data::Printer
perl v5.32.1 2021-05-03 Data::Printer::Object(3pm)
Generated by dwww version 1.14 on Sun Feb 2 14:21:50 CET 2025.