File Coverage

blib/lib/Data/Dump/Filtered.pm
Criterion Covered Total %
statement 13 21 61.9
branch 2 6 33.3
condition 1 3 33.3
subroutine 4 6 66.6
pod 3 3 100.0
total 23 39 58.9


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