.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Data::Printer::Object 3"
.TH Data::Printer::Object 3 "2021-03-02" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Data::Printer::Object \- underlying object for Data::Printer
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Unless you're writing a plugin, or looking for some
configuration property details
the documentation you want is probably on Data::Printer. Seriously!
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements the underlying object used by Data::Printer to parse,
format and print Perl data structures.
.PP
It is passed to plugins so they can rely on contextual information from the
caller like colors, spacing and other options.
.SH "COMMON PROPERTIES / ATTRIBUTES"
.IX Header "COMMON PROPERTIES / ATTRIBUTES"
.SS "Scalar Options"
.IX Subsection "Scalar Options"
\fIshow_tainted\fR
.IX Subsection "show_tainted"
.PP
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.
.PP
\fIshow_unicode\fR
.IX Subsection "show_unicode"
.PP
Whether to label data that has the unicode flag set. (default: 1)
.PP
\fIshow_dualvar\fR
.IX Subsection "show_dualvar"
.PP
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 \*(L"lax\*(R", Data::Printer will
show both values if they differ. If set to \*(L"strict\*(R", it will always show both
values, and when set to \*(L"off\*(R" it will never show the second value. (default: lax)
.PP
\fIshow_lvalue\fR
.IX Subsection "show_lvalue"
.PP
Let's you know whenever a value is an lvalue (default: 1)
.PP
\fIstring_max\fR
.IX Subsection "string_max"
.PP
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 \f(CW\*(C`string_max\*(C'\fR to 0 to show all
characters (default: 4096)
.PP
\fIstring_overflow\fR
.IX Subsection "string_overflow"
.PP
Message to display once string_max is reached. Defaults to
\&\fI\*(L"(...skipping _\|_SKIPPED_\|_ chars...)\*(R"\fR.
.PP
\fIstring_preserve\fR
.IX Subsection "string_preserve"
.PP
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')
.PP
\fIscalar_quotes\fR
.IX Subsection "scalar_quotes"
.PP
Which quotation character to use when printing strings (default: ")
.PP
\fIescape_chars\fR
.IX Subsection "escape_chars"
.PP
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).
.PP
\fIunicode_charnames\fR
.IX Subsection "unicode_charnames"
.PP
whether to use the character's names when escaping unicode (e.g. \s-1SNOWMAN\s0 instead of \ex{2603}) (default: 0)
.PP
\fIprint_escapes\fR
.IX Subsection "print_escapes"
.PP
Wether to print invisible characters in strings, like \eb, \en and \et (default: 0)
.PP
\fIresolve_scalar_refs\fR
.IX Subsection "resolve_scalar_refs"
.PP
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)
.SS "Array Options"
.IX Subsection "Array Options"
\fIarray_max\fR
.IX Subsection "array_max"
.PP
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 \f(CW\*(C`array_max\*(C'\fR to 0 to show all elements
in the array, regardless of array size (default: 100)
.PP
\fIarray_overflow\fR
.IX Subsection "array_overflow"
.PP
Message to display once array_max is reached. Defaults to
\&\f(CW"(...skipping _\|_SKIPPED_\|_ items...)"\fR.
.PP
\fIarray_preserve\fR
.IX Subsection "array_preserve"
.PP
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')
.PP
\fIindex\fR
.IX Subsection "index"
.PP
When set, shows the index number before each array element. (default: 1)
.PP
Hash Options
.IX Subsection "Hash Options"
.PP
\fIalign_hash\fR
.IX Subsection "align_hash"
.PP
If this option is set, hash keys  will be vertically aligned by the length
of the longest key.
.PP
This is better explained with an example, so consider the hash
\&\f(CW\*(C`my %h = ( a => 123, aaaaaa => 456 )\*(C'\fR. This would be an unaligned output:
.PP
.Vb 2
\&    a => 123,
\&    aaaaaa => 456
.Ve
.PP
and this is what it looks like with \f(CW\*(C`align_hash = 1\*(C'\fR:
.PP
.Vb 2
\&    a      => 123,
\&    aaaaaa => 456
.Ve
.PP
(default: 1)
.PP
\fIhash_max\fR
.IX Subsection "hash_max"
.PP
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 \f(CW\*(C`hash_max\*(C'\fR to 0 to show all elements
in the hash, regardless of the total keys. (default: 100)
.PP
\fIhash_overflow\fR
.IX Subsection "hash_overflow"
.PP
Message to display once hash_max is reached. Defaults to
\&\f(CW"(...skipping _\|_SKIPPED_\|_ keys...)"\fR.
.PP
\fIhash_preserve\fR
.IX Subsection "hash_preserve"
.PP
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')
.PP
\fIhash_separator\fR
.IX Subsection "hash_separator"
.PP
What to use to separate keys from values. Default is '   ' (three spaces)
.PP
\fIsort_keys\fR
.IX Subsection "sort_keys"
.PP
Whether to sort keys when printing the contents of a hash (default: 1)
.PP
\fIquote_keys\fR
.IX Subsection "quote_keys"
.PP
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')
.SS "Caller Information"
.IX Subsection "Caller Information"
Data::Printer can add an informational message to every call to \f(CW\*(C`p()\*(C'\fR or
\&\f(CW\*(C`np()\*(C'\fR if you enable \f(CW\*(C`caller_info\*(C'\fR. So for example if you write:
.PP
.Vb 2
\&    my $var = "meep!";
\&    p $var, caller_info => 1;
.Ve
.PP
this will output something like:
.PP
.Vb 2
\&    Printing in line 2 of myapp.pl:
\&    "meep!"
.Ve
.PP
The following options let you customize the message and how it is displayed.
.PP
\fIcaller_info\fR
.IX Subsection "caller_info"
.PP
Set this option to a true value to display a message next
to the data being printed. (default: 0)
.PP
\fIcaller_message\fR
.IX Subsection "caller_message"
.PP
What message to print when caller_info is true.
.PP
Defaults to
"\f(CW\*(C`Printing in line _\|_LINE_\|_ of _\|_FILENAME_\|_\*(C'\fR".
.PP
If the special strings \f(CW\*(C`_\|_LINE_\|_\*(C'\fR, \f(CW\*(C`_\|_FILENAME_\|_\*(C'\fR or \f(CW\*(C`_\|_PACKAGE_\|_\*(C'\fR are
present in the message, they'll be interpolated into their according value
so you can customize the message at will:
.PP
.Vb 1
\&    caller_message = "[_\|_PACKAGE_\|_:_\|_LINE_\|_]"
.Ve
.PP
\fIcaller_message_newline\fR
.IX Subsection "caller_message_newline"
.PP
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)
.PP
\fIcaller_message_position\fR
.IX Subsection "caller_message_position"
.PP
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')
.SS "General Options"
.IX Subsection "General Options"
\fIarrows\fR
.IX Subsection "arrows"
.PP
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
\&\f(CW\*(C`var\->{x}\->[y]\->[z]\*(C'\fR), 'first' (\f(CW\*(C`var\->{x}[y][z]\*(C'\fR) or 'none'
(\f(CW\*(C`var{x}[y][z]\*(C'\fR). Default is 'none'.
.PP
\fIcolored\fR
.IX Subsection "colored"
.PP
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 \s-1STDOUT\s0 or \s-1STDERR,\s0 never to a file or to a variable. The 'auto'
setting also respects the \f(CW\*(C`ANSI_COLORS_DISABLED\*(C'\fR environment variable.
.PP
\fIdeparse\fR
.IX Subsection "deparse"
.PP
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)
.PP
\fIend_separator\fR
.IX Subsection "end_separator"
.PP
When set, the last item on an array or hash will always contain a
trailing separator. (default: 0)
.PP
\fIshow_memsize\fR
.IX Subsection "show_memsize"
.PP
Set to true and Data::Printer will show the estimate memory size of the data
structure being printed. Requires Devel::Size. (default: 0)
.PP
\fImemsize_unit\fR
.IX Subsection "memsize_unit"
.PP
If show_memsize is on, this option lets you specify the
unit in which to show the memory size. Can be set to \*(L"b\*(R" to show size in
bytes, \*(L"k\*(R" for kilobytes, \*(L"m\*(R" for megabytes or \*(L"auto\*(R", which will use the
biggest unit that makes sense. (default: auto)
.PP
\fIoutput\fR
.IX Subsection "output"
.PP
Where you want the output to be printed. Can be set to the following values:
.IP "\(bu" 4
\&\f(CW\*(Aqstderr\*(Aq\fR \- outputs to the standard error handle.
.IP "\(bu" 4
\&\f(CW\*(Aqstdout\*(Aq\fR \- outputs to the standard output handle.
.IP "\(bu" 4
reference to a scalar (e.g. \f(CW\*(C`\e$string\*(C'\fR) \- outputs to the scalar reference.
.IP "\(bu" 4
file handle \- any open file handle:
.Sp
.Vb 2
\&    open my $fh, \*(Aq>>\*(Aq, \*(Aq/path/to/some/file.log\*(Aq or die $!;
\&    p @{[ 1,2,3 ]}, output => $fh;
.Ve
.IP "\(bu" 4
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 \f(CW\*(C`.dataprinter\*(C'\fR:
.Sp
.Vb 1
\&    output = /path/to/some/file.log
.Ve
.Sp
By default, Data::Printer will print to the standard error (stderr).
.PP
\fImax_depth\fR
.IX Subsection "max_depth"
.PP
This setting controls how far inside the data structure we should go
(default: 0 for no depth limit)
.PP
\fIreturn_value\fR
.IX Subsection "return_value"
.PP
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').
.PP
Defaults to \f(CW\*(Aqpass\*(Aq\fR since version 0.36. \fB\s-1NOTE\s0\fR: 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.
.PP
\fIseparator\fR
.IX Subsection "separator"
.PP
The separator character(s) to use for arrays and hashes. The default is the
comma \*(L",\*(R".
.PP
\fIshow_readonly\fR
.IX Subsection "show_readonly"
.PP
When this option is set, Data::Printer will let you know whenever a value is
read-only. (default: 1)
.PP
\fIshow_refcount\fR
.IX Subsection "show_refcount"
.PP
Whether to show data refcount it's above 1 (default: 0)
.PP
\fIshow_weak\fR
.IX Subsection "show_weak"
.PP
When this option is set, Data::Printer will let you know whenever it finds a
weak reference (default: 1)
.PP
\fIshow_tied\fR
.IX Subsection "show_tied"
.PP
When set to true, this option will let you know whenever a tied variable
is detected, including what is tied to it (default: 1)
.PP
\fItheme\fR
.IX Subsection "theme"
.PP
.Vb 1
\&    theme = Monokai
.Ve
.PP
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 \s-1CPAN.\s0
.PP
\fIwarnings\fR
.IX Subsection "warnings"
.PP
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 \f(CW\*(C`p()\*(C'\fR or \f(CW\*(C`np()\*(C'\fR. To silence those warnings, set this
option to 0.
.SS "Class / Object Options"
.IX Subsection "Class / Object Options"
\fIclass_method\fR
.IX Subsection "class_method"
.PP
When Data::Printer is printing an object, it first looks for a method
named "\f(CW\*(C`_dataprinter\*(C'\fR" and, if one is found, we call it instead of actually
parsing the structure.
.PP
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.
.PP
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.
.PP
\fIclass \- class properties to override.\fR
.IX Subsection "class - class properties to override."
.PP
This \*(L"namespace\*(R" 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.
.PP
In your \f(CW\*(C`.dataprinter\*(C'\fR file, the defaults would look like this:
.PP
.Vb 10
\&    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
.Ve
.PP
In code, you should use the \*(L"class\*(R" namespace as a key to a hash reference:
.PP
.Vb 10
\&    use Data::Printer class => {
\&        parents            => 1,
\&        linear_isa         => \*(Aqauto\*(Aq,
\&        universal          => 0,
\&        expand             => 1,
\&        stringify          => 1,
\&        show_reftype       => 0,
\&        show_overloads     => 1,
\&        show_methods       => \*(Aqall\*(Aq,
\&        sort_methods       => 1,
\&        inherited          => \*(Aqpublic\*(Aq,
\&        format_inheritance => \*(Aqlines\*(Aq,
\&        parent_filters     => 1,
\&        internals          => 1,
\&    };
.Ve
.PP
Or inline:
.PP
.Vb 1
\&    p $some_object, class => { internals => 1,  ... };
.Ve
.PP
parents
.IX Subsection "parents"
.PP
When set, shows all superclasses of the object being printed. (default: 1)
.PP
linear_isa
.IX Subsection "linear_isa"
.PP
This setting controls whether to show the linearized \f(CW@ISA\fR, 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')
.PP
universal
.IX Subsection "universal"
.PP
Set this option to 1 to include \s-1UNIVERSAL\s0 methods to the list of public
methods (like \f(CW\*(C`can\*(C'\fR and \f(CW\*(C`isa\*(C'\fR). (default: 0)
.PP
expand
.IX Subsection "expand"
.PP
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)
.PP
stringify
.IX Subsection "stringify"
.PP
When this option is set, Data::Printer will check if the object being printed
contains any methods named \f(CW\*(C`as_string\*(C'\fR, \f(CW\*(C`to_string\*(C'\fR or \f(CW\*(C`stringify\*(C'\fR. If it
does, Data::Printer will use it as the object's output instead of the
generic class plugin. (default: 1)
.PP
show_reftype
.IX Subsection "show_reftype"
.PP
If set to a true value, Data::Printer will show the internal reference type
of the object. (default: 0)
.PP
show_overloads
.IX Subsection "show_overloads"
.PP
This option includes a list of all overloads implemented by the object.
(default: 1)
.PP
show_methods
.IX Subsection "show_methods"
.PP
Controls which of the object's direct methods to show. Can be set to 'none',
\&'all', 'private' or 'public'. (default: 'all')
.PP
sort_methods
.IX Subsection "sort_methods"
.PP
When listing methods, this option will order them alphabetically, rather than
on whatever order the list of methods returned. (default: 1)
.PP
inherited
.IX Subsection "inherited"
.PP
Controls which of the object's parent methods to show. Can be set to 'none',
\&'all', 'private' or 'public'. (default: 'public')
.PP
format_inheritance
.IX Subsection "format_inheritance"
.PP
This option controls how to format the list of methods set by a parent class
(and not the class itself). Setting it to \f(CW\*(Aqlines\*(Aq\fR it will print one line
for each parent, like so:
.PP
.Vb 6
\&    public methods (5):
\&        foo, bar
\&        Parent::Class:
\&            baz, meep
\&        Other::Parent:
\&            moop
.Ve
.PP
Setting it to \f(CW\*(Aqstring\*(Aq\fR, it will put all methods on the same line:
.PP
.Vb 1
\&    public methods (5): foo, bar, baz (Parent::Class), meep (Parent::CLass), moop (Other::Parent)
.Ve
.PP
Default is: 'lines'.
.PP
parent_filters
.IX Subsection "parent_filters"
.PP
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)
.PP
internals
.IX Subsection "internals"
.PP
Shows the object's internal data structure. (default: 1)
.ie n .SS """Shortcuts"""
.el .SS "``Shortcuts''"
.IX Subsection "Shortcuts"
Some options are so often used together we have created shortcuts for them.
.PP
\fIas\fR
.IX Subsection "as"
.PP
.Vb 1
\&    p $somevar, as => \*(Aqis this right?\*(Aq;
.Ve
.PP
The "\f(CW\*(C`as\*(C'\fR" 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 \f(CW\*(C`p()\*(C'\fR.
.PP
\fImultiline\fR
.IX Subsection "multiline"
.PP
.Vb 1
\&    p $somevar, multiline => 0;
.Ve
.PP
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
\&\f(CW\*(C`.dataprinter\*(C'\fR file, Can be \*(L"undone\*(R" by setting it to \*(L"1\*(R".
.PP
\fIfulldump\fR
.IX Subsection "fulldump"
.PP
.Vb 1
\&    p $somevar, fulldump => 1;
.Ve
.PP
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.
.SS "Methods and Accessors for Filter Writers"
.IX Subsection "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 ;)
.PP
And make sure to check out the current filter list for real usage examples!
.PP
\fIindent\fR
.IX Subsection "indent"
.PP
\fIoutdent\fR
.IX Subsection "outdent"
.PP
\fInewline\fR
.IX Subsection "newline"
.PP
These methods are used to control the indentation level of the string being
created to represent your data. While \f(CW\*(C`indent\*(C'\fR and \f(CW\*(C`outdent\*(C'\fR respectively
increase and decrease the indentation level, \f(CW\*(C`newline\*(C'\fR will add a linebreak
and position the \*(L"cursor\*(R" where you are expected to continue your dump string:
.PP
.Vb 5
\&    my $output = $ddp\->newline . \*(Aqthis is a new line\*(Aq;
\&    $ddp\->indent;
\&    $output .= $ddp\->newline . \*(Aqthis is indented\*(Aq;
\&    $ddp\->outdent;
\&    $output .= $ddp\->newline . \*(Aqback to our previous indentation!\*(Aq;
.Ve
.PP
Unless multiline was set to 0, the code above should print something like:
.PP
.Vb 3
\&    this is a new line
\&        this is indented
\&    back to our previous indentation
.Ve
.PP
\fIextra_config\fR
.IX Subsection "extra_config"
.PP
Data::Printer will read and pass-through any unrecognized settings in either
your \f(CW\*(C`.dataprinter\*(C'\fR file or your inline arguments inside this structure.
This is useful to create custom settings for your filters.
.PP
While any and all unknown settings will be readable here, we recommend you
prepend them with a namespace like \f(CW\*(C`filter_xxx\*(C'\fR as those are reserved for
filters and thus guaranteed not to colide with any core Data::Printer
settings now or in the future.
.PP
For example, on the Web filter we have the
\&\f(CW\*(C`expand_headers\*(C'\fR option, and even though Data::Printer itself doesn't have
this option, we prepend everything with the \f(CW\*(C`filter_web\*(C'\fR namespace, either
in the config file:
.PP
.Vb 1
\&    filter_web.expand_headers = 1
.Ve
.PP
or inline:
.PP
.Vb 1
\&    p $http_response, filters => [\*(AqWeb\*(Aq], filter_web => { expand_headers => 1 };
.Ve
.PP
\fImaybe_colorize( \f(CI$string\fI, \f(CI$label\fI )\fR
.IX Subsection "maybe_colorize( $string, $label )"
.PP
\fImaybe_colorize( \f(CI$string\fI, \f(CI$label\fI, \f(CI$default_color\fI )\fR
.IX Subsection "maybe_colorize( $string, $label, $default_color )"
.PP
.Vb 1
\&    my $output = $ddp\->maybe_colorize( 12.3, \*(Aqnumber\*(Aq);
.Ve
.PP
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).
.PP
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:
.PP
.Vb 1
\&    my $output = $ddp\->maybe_colorize( $data, \*(Aqfilter_myclass\*(Aq, \*(Aq#ffccb3\*(Aq );
.Ve
.PP
In the code above, if the user has \f(CW\*(C`colors.filter_myclass\*(C'\fR set either on the
\&\f(CW\*(C`.dataprinter\*(C'\fR file or the runtime hashref, that one will be used. Otherwise,
Data::Printer will use \f(CW\*(Aq#ffccb3\*(Aq\fR.
.PP
\fIcurrent_depth\fR
.IX Subsection "current_depth"
.PP
Shows the current depth level, from 0 onwards.
.PP
\fIcurrent_name\fR
.IX Subsection "current_name"
.PP
Gets/sets the name for the current posistion, to be printed when the parser
visits that data again. E.g. \f(CW\*(C`var[0]{abc}[2]\*(C'\fR.
.PP
\fIparse( \f(CI$data_ref\fI )\fR
.IX Subsection "parse( $data_ref )"
.PP
\fIparse( \f(CI$data_ref\fI, \f(CI%options\fI )\fR
.IX Subsection "parse( $data_ref, %options )"
.PP
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.
.PP
Use this inside filters whenever you want to use the result of a parsed data
strucure.
.PP
.Vb 1
\&    my $output = $ddp\->parse( [3,2,1] );
.Ve
.PP
An optional set of parameters may be passed:
.IP "\(bu" 4
\&\f(CW\*(C`force_type => $type\*(C'\fR \- forces data to be treated as that type,
where \f(CW$type\fR is the name of the Perl data strucuture as returned by
Scalar::Util::reftype (e.g. '\s-1HASH\s0', '\s-1ARRAY\s0' 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.
.IP "\(bu" 4
\&\f(CW\*(C`seen_override => 1\*(C'\fR \- 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.
.PP
\fIparse_as( \f(CI$type\fI, \f(CI$data_ref\fI )\fR
.IX Subsection "parse_as( $type, $data_ref )"
.PP
This is a convenience method to force some data to be interpreted as a
particular type. It is the same as:
.PP
.Vb 1
\&    $ddp\->parse( $data, force_type => $type, seen_override => 1 );
.Ve
.ie n .SS "unsee( $data )"
.el .SS "unsee( \f(CW$data\fP )"
.IX Subsection "unsee( $data )"
Sometimes you are writing a filter for data that you know will be repeated
several times, like \s-1JSON\s0 Boolean objects. To prevent Data::Printer from
showing this content as repeated, you can use the \f(CW\*(C`unsee\*(C'\fR method to make
the current object forget about having ever visited this data.
.SH "OBJECT CONSTRUCTION"
.IX Header "OBJECT CONSTRUCTION"
You'll most like never need this unless you're planning on extending
Data::Printer itself.
.ie n .SS "new( %options )"
.el .SS "new( \f(CW%options\fP )"
.IX Subsection "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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Data::Printer