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 (coderef), this option can be set to deparse it and print the underlying code, which hopefully resembles the original source code. (default: 0)

coderef_stub

If the data structure contains a subroutine reference (coderef) and the 'deparse' option above is set to false, Data::Printer will print this instead. (default: 'sub { ... }')

coderef_undefined

If the data structure contains a subroutine reference (coderef) that has not actually been defined at the time of inspection, Data::Printer will print this instead. Set it to '0' to disable this check, in which case Data::Printer will use whatever value you set on coderef_stub above. (default: '<undefined coderef>').

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 "_data_printer" 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'. When applicable (Moo, Moose) it will also show attributes and roles. (default: 'all')

sort_methods

When listing methods, attributes and roles, 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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)