1Data::Dump::Filtered(3)User Contributed Perl DocumentatioDnata::Dump::Filtered(3)
2
3
4

NAME

6       Data::Dump::Filtered - Pretty printing with filtering
7

DESCRIPTION

9       The following functions are provided:
10
11       add_dump_filter( \&filter )
12           This registers a filter function to be used by the regular
13           Data::Dump::dump() function.  By default no filters are active.
14
15           Since registering filters has a global effect is might be more
16           appropriate to use the dump_filtered() function instead.
17
18       remove_dump_filter( \&filter )
19           Unregister the given callback function as filter callback.  This
20           undoes the effect of add_filter.
21
22       dump_filtered(..., \&filter )
23           Works like Data::Dump::dump(), but the last argument should be a
24           filter callback function.  As objects are visited the filter
25           callback is invoked at it might influence how objects are dumped.
26
27           Any filters registered with add_filter() are ignored when this
28           interface is invoked.  Actually, passing "undef" as \&filter is
29           allowed and "dump_filtered(..., undef)" is the official way to
30           force unfiltered dumps.
31
32   Filter callback
33       A filter callback is a function that will be invoked with 2 arguments;
34       a context object and reference to the object currently visited.  The
35       return value should either be a hash reference or "undef".
36
37           sub filter_callback {
38               my($ctx, $object_ref) = @_;
39               ...
40               return { ... }
41           }
42
43       If the filter callback returns "undef" (or nothing) then normal
44       processing and formatting of the visited object happens.  If the filter
45       callback returns a hash it might replace or annotate the representation
46       of the current object.
47
48   Filter context
49       The context object provide methods that can be used to determine what
50       kind of object is currently visited and where it's located.  The
51       context object has the following interface:
52
53       $ctx->object_ref
54           Alternative way to obtain a reference to the current object
55
56       $ctx->class
57           If the object is blessed this return the class.  Returns "" for
58           objects not blessed.
59
60       $ctx->reftype
61           Returns what kind of object this is.  It's a string like "SCALAR",
62           "ARRAY", "HASH", "CODE",...
63
64       $ctx->is_ref
65           Returns true if a reference was provided.
66
67       $ctx->is_blessed
68           Returns true if the object is blessed.  Actually, this is just an
69           alias for "$ctx->class".
70
71       $ctx->is_array
72           Returns true if the object is an array
73
74       $ctx->is_hash
75           Returns true if the object is a hash
76
77       $ctx->is_scalar
78           Returns true if the object is a scalar (a string or a number)
79
80       $ctx->is_code
81           Returns true if the object is a function (aka subroutine)
82
83       $ctx->container_class
84           Returns the class of the innermost container that contains this
85           object.  Returns "" if there is no blessed container.
86
87       $ctx->container_self
88           Returns an textual expression relative to the container object that
89           names this object.  The variable $self in this expression is the
90           container itself.
91
92       $ctx->object_isa( $class )
93           Returns TRUE if the current object is of the given class or is of a
94           subclass.
95
96       $ctx->container_isa( $class )
97           Returns TRUE if the innermost container is of the given class or is
98           of a subclass.
99
100       $ctx->depth
101           Returns how many levels deep have we recursed into the structure
102           (from the original dump_filtered() arguments).
103
104       $ctx->expr
105       $ctx->expr( $top_level_name )
106           Returns an textual expression that denotes the current object.  In
107           the expression $var is used as the name of the top level object
108           dumped.  This can be overridden by providing a different name as
109           argument.
110
111   Filter return hash
112       The following elements has significance in the returned hash:
113
114       dump => $string
115           incorporate the given string as the representation for the current
116           value
117
118       object => $value
119           dump the given value instead of the one visited and passed in as
120           $object.  Basically the same as specifying "dump =>
121           Data::Dump::dump($value)".
122
123       comment => $comment
124           prefix the value with the given comment string
125
126       bless => $class
127           make it look as if the current object is of the given $class
128           instead of the class it really has (if any).  The internals of the
129           object is dumped in the regular way.  The $class can be the empty
130           string to make Data::Dump pretend the object wasn't blessed at all.
131
132       hide_keys => ['key1', 'key2',...]
133       hide_keys => \&code
134           If the $object is a hash dump is as normal but pretend that the
135           listed keys did not exist.  If the argument is a function then the
136           function is called to determine if the given key should be hidden.
137

SEE ALSO

139       Data::Dump
140
141
142
143perl v5.38.0                      2023-07-20           Data::Dump::Filtered(3)
Impressum