/usr/share/perl5/Data/Dump/Filtered.pm is in libdata-dump-perl 1.23-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 | package Data::Dump::Filtered;
use Data::Dump ();
use Carp ();
use base 'Exporter';
our @EXPORT_OK = qw(add_dump_filter remove_dump_filter dump_filtered);
sub add_dump_filter {
my $filter = shift;
unless (ref($filter) eq "CODE") {
Carp::croak("add_dump_filter argument must be a code reference");
}
push(@Data::Dump::FILTERS, $filter);
return $filter;
}
sub remove_dump_filter {
my $filter = shift;
@Data::Dump::FILTERS = grep $_ ne $filter, @Data::Dump::FILTERS;
}
sub dump_filtered {
my $filter = pop;
if (defined($filter) && ref($filter) ne "CODE") {
Carp::croak("Last argument to dump_filtered must be undef or a code reference");
}
local @Data::Dump::FILTERS = ($filter ? $filter : ());
return &Data::Dump::dump;
}
1;
=head1 NAME
Data::Dump::Filtered - Pretty printing with filtering
=head1 DESCRIPTION
The following functions are provided:
=over
=item add_dump_filter( \&filter )
This registers a filter function to be used by the regular Data::Dump::dump()
function. By default no filters are active.
Since registering filters has a global effect is might be more appropriate
to use the dump_filtered() function instead.
=item remove_dump_filter( \&filter )
Unregister the given callback function as filter callback.
This undoes the effect of L<add_filter>.
=item dump_filtered(..., \&filter )
Works like Data::Dump::dump(), 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.
Any filters registered with L<add_filter()> are ignored when
this interface is invoked. Actually, passing C<undef> as \&filter
is allowed and C<< dump_filtered(..., undef) >> is the official way to
force unfiltered dumps.
=back
=head2 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 C<undef>.
sub filter_callback {
my($ctx, $object_ref) = @_;
...
return { ... }
}
If the filter callback returns C<undef> (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.
=head2 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:
=over
=item $ctx->object_ref
Alternative way to obtain a reference to the current object
=item $ctx->class
If the object is blessed this return the class. Returns ""
for objects not blessed.
=item $ctx->reftype
Returns what kind of object this is. It's a string like "SCALAR",
"ARRAY", "HASH", "CODE",...
=item $ctx->is_ref
Returns true if a reference was provided.
=item $ctx->is_blessed
Returns true if the object is blessed. Actually, this is just an alias
for C<< $ctx->class >>.
=item $ctx->is_array
Returns true if the object is an array
=item $ctx->is_hash
Returns true if the object is a hash
=item $ctx->is_scalar
Returns true if the object is a scalar (a string or a number)
=item $ctx->is_code
Returns true if the object is a function (aka subroutine)
=item $ctx->container_class
Returns the class of the innermost container that contains this object.
Returns "" if there is no blessed container.
=item $ctx->container_self
Returns an textual expression relative to the container object that names this
object. The variable C<$self> in this expression is the container itself.
=item $ctx->object_isa( $class )
Returns TRUE if the current object is of the given class or is of a subclass.
=item $ctx->container_isa( $class )
Returns TRUE if the innermost container is of the given class or is of a
subclass.
=item $ctx->depth
Returns how many levels deep have we recursed into the structure (from the
original dump_filtered() arguments).
=item $ctx->expr
=item $ctx->expr( $top_level_name )
Returns an textual expression that denotes the current object. In the
expression C<$var> is used as the name of the top level object dumped. This
can be overridden by providing a different name as argument.
=back
=head2 Filter return hash
The following elements has significance in the returned hash:
=over
=item dump => $string
incorporate the given string as the representation for the
current value
=item object => $value
dump the given value instead of the one visited and passed in as $object.
Basically the same as specifying C<< dump => Data::Dump::dump($value) >>.
=item comment => $comment
prefix the value with the given comment string
=item bless => $class
make it look as if the current object is of the given $class
instead of the class it really has (if any). The internals of the object
is dumped in the regular way. The $class can be the empty string
to make Data::Dump pretend the object wasn't blessed at all.
=item hide_keys => ['key1', 'key2',...]
=item hide_keys => \&code
If the $object 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.
=back
=head1 SEE ALSO
L<Data::Dump>
|