.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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::Dump::Filtered 3pm"
.TH Data::Dump::Filtered 3pm "2021-09-26" "perl v5.32.1" "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::Dump::Filtered \- Pretty printing with filtering
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The following functions are provided:
.IP "add_dump_filter( \e&filter )" 4
.IX Item "add_dump_filter( &filter )"
This registers a filter function to be used by the regular \fBData::Dump::dump()\fR
function.  By default no filters are active.
.Sp
Since registering filters has a global effect is might be more appropriate
to use the \fBdump_filtered()\fR function instead.
.IP "remove_dump_filter( \e&filter )" 4
.IX Item "remove_dump_filter( &filter )"
Unregister the given callback function as filter callback.
This undoes the effect of add_filter.
.IP "dump_filtered(..., \e&filter )" 4
.IX Item "dump_filtered(..., &filter )"
Works like \fBData::Dump::dump()\fR, but the last argument should
be a filter callback function.  As objects are visited the
filter callback is invoked at it might influence how objects are dumped.
.Sp
Any filters registered with \fBadd_filter()\fR are ignored when
this interface is invoked.  Actually, passing \f(CW\*(C`undef\*(C'\fR as \e&filter
is allowed and \f(CW\*(C`dump_filtered(..., undef)\*(C'\fR is the official way to
force unfiltered dumps.
.SS "Filter callback"
.IX Subsection "Filter callback"
A filter callback is a function that will be invoked with 2 arguments;
a context object and reference to the object currently visited.  The return
value should either be a hash reference or \f(CW\*(C`undef\*(C'\fR.
.PP
.Vb 5
\&    sub filter_callback {
\&        my($ctx, $object_ref) = @_;
\&        ...
\&        return { ... }
\&    }
.Ve
.PP
If the filter callback returns \f(CW\*(C`undef\*(C'\fR (or nothing) then normal
processing and formatting of the visited object happens.
If the filter callback returns a hash it might replace
or annotate the representation of the current object.
.SS "Filter context"
.IX Subsection "Filter context"
The context object provide methods that can be used to determine what kind of
object is currently visited and where it's located.  The context object has the
following interface:
.ie n .IP "$ctx\->object_ref" 4
.el .IP "\f(CW$ctx\fR\->object_ref" 4
.IX Item "$ctx->object_ref"
Alternative way to obtain a reference to the current object
.ie n .IP "$ctx\->class" 4
.el .IP "\f(CW$ctx\fR\->class" 4
.IX Item "$ctx->class"
If the object is blessed this return the class.  Returns ""
for objects not blessed.
.ie n .IP "$ctx\->reftype" 4
.el .IP "\f(CW$ctx\fR\->reftype" 4
.IX Item "$ctx->reftype"
Returns what kind of object this is.  It's a string like \*(L"\s-1SCALAR\*(R",
\&\*(L"ARRAY\*(R", \*(L"HASH\*(R", \*(L"CODE\*(R",...\s0
.ie n .IP "$ctx\->is_ref" 4
.el .IP "\f(CW$ctx\fR\->is_ref" 4
.IX Item "$ctx->is_ref"
Returns true if a reference was provided.
.ie n .IP "$ctx\->is_blessed" 4
.el .IP "\f(CW$ctx\fR\->is_blessed" 4
.IX Item "$ctx->is_blessed"
Returns true if the object is blessed.  Actually, this is just an alias
for \f(CW\*(C`$ctx\->class\*(C'\fR.
.ie n .IP "$ctx\->is_array" 4
.el .IP "\f(CW$ctx\fR\->is_array" 4
.IX Item "$ctx->is_array"
Returns true if the object is an array
.ie n .IP "$ctx\->is_hash" 4
.el .IP "\f(CW$ctx\fR\->is_hash" 4
.IX Item "$ctx->is_hash"
Returns true if the object is a hash
.ie n .IP "$ctx\->is_scalar" 4
.el .IP "\f(CW$ctx\fR\->is_scalar" 4
.IX Item "$ctx->is_scalar"
Returns true if the object is a scalar (a string or a number)
.ie n .IP "$ctx\->is_code" 4
.el .IP "\f(CW$ctx\fR\->is_code" 4
.IX Item "$ctx->is_code"
Returns true if the object is a function (aka subroutine)
.ie n .IP "$ctx\->container_class" 4
.el .IP "\f(CW$ctx\fR\->container_class" 4
.IX Item "$ctx->container_class"
Returns the class of the innermost container that contains this object.
Returns "" if there is no blessed container.
.ie n .IP "$ctx\->container_self" 4
.el .IP "\f(CW$ctx\fR\->container_self" 4
.IX Item "$ctx->container_self"
Returns an textual expression relative to the container object that names this
object.  The variable \f(CW$self\fR in this expression is the container itself.
.ie n .IP "$ctx\->object_isa( $class )" 4
.el .IP "\f(CW$ctx\fR\->object_isa( \f(CW$class\fR )" 4
.IX Item "$ctx->object_isa( $class )"
Returns \s-1TRUE\s0 if the current object is of the given class or is of a subclass.
.ie n .IP "$ctx\->container_isa( $class )" 4
.el .IP "\f(CW$ctx\fR\->container_isa( \f(CW$class\fR )" 4
.IX Item "$ctx->container_isa( $class )"
Returns \s-1TRUE\s0 if the innermost container is of the given class or is of a
subclass.
.ie n .IP "$ctx\->depth" 4
.el .IP "\f(CW$ctx\fR\->depth" 4
.IX Item "$ctx->depth"
Returns how many levels deep have we recursed into the structure (from the
original \fBdump_filtered()\fR arguments).
.ie n .IP "$ctx\->expr" 4
.el .IP "\f(CW$ctx\fR\->expr" 4
.IX Item "$ctx->expr"
.PD 0
.ie n .IP "$ctx\->expr( $top_level_name )" 4
.el .IP "\f(CW$ctx\fR\->expr( \f(CW$top_level_name\fR )" 4
.IX Item "$ctx->expr( $top_level_name )"
.PD
Returns an textual expression that denotes the current object.  In the
expression \f(CW$var\fR is used as the name of the top level object dumped.  This
can be overridden by providing a different name as argument.
.SS "Filter return hash"
.IX Subsection "Filter return hash"
The following elements has significance in the returned hash:
.ie n .IP "dump => $string" 4
.el .IP "dump => \f(CW$string\fR" 4
.IX Item "dump => $string"
incorporate the given string as the representation for the
current value
.ie n .IP "object => $value" 4
.el .IP "object => \f(CW$value\fR" 4
.IX Item "object => $value"
dump the given value instead of the one visited and passed in as \f(CW$object\fR.
Basically the same as specifying \f(CW\*(C`dump => Data::Dump::dump($value)\*(C'\fR.
.ie n .IP "comment => $comment" 4
.el .IP "comment => \f(CW$comment\fR" 4
.IX Item "comment => $comment"
prefix the value with the given comment string
.ie n .IP "bless => $class" 4
.el .IP "bless => \f(CW$class\fR" 4
.IX Item "bless => $class"
make it look as if the current object is of the given \f(CW$class\fR
instead of the class it really has (if any).  The internals of the object
is dumped in the regular way.  The \f(CW$class\fR can be the empty string
to make Data::Dump pretend the object wasn't blessed at all.
.IP "hide_keys => ['key1', 'key2',...]" 4
.IX Item "hide_keys => ['key1', 'key2',...]"
.PD 0
.IP "hide_keys => \e&code" 4
.IX Item "hide_keys => &code"
.PD
If the \f(CW$object\fR is a hash dump is as normal but pretend that the
listed keys did not exist.  If the argument is a function then
the function is called to determine if the given key should be
hidden.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Data::Dump