Dump/Filtered.pm

filter: Statementstmt 65.2% 15 / 23 Branchbran 33.3% 2 / 6 Conditioncond 33.3% 1 / 3 MC/DCmcdc 0.0% 0 / 2 Subroutinesub 66.6% 4 / 6 Podpod 100% 3 / 3 totaltotal 58.1% 25 / 43 CC 5 SCAR 13.3
CC
5
Cov
56%
add_dump_filter
6.0
dump_filtered
5.2
remove_dump_filter
2.0
CRAP 3.8
« Dump/Trace.pm ↑ Summary Dump/FilterContext.pm »
1 package Data::Dump::Filtered;
2  
3 1 ▶use Data::Dump ();
Subroutine BEGIN: called CC=1 SCAR=0.0
4 1 ▶use Carp ();
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 1 ▶use base 'Exporter';
Subroutine BEGIN: called CC=1 SCAR=0.0
7 1 our @EXPORT_OK = qw(add_dump_filter remove_dump_filter dump_filtered);
8  
9 0 ▶sub add_dump_filter {
Subroutine add_dump_filter: not called CC=2 SCAR=17.9
Pod documented
10 0 my $filter = shift;
11 0 ▶ unless (ref($filter) eq "CODE") {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $filter eq "CODE") 0 0 0
12 0 Carp::croak("add_dump_filter argument must be a code reference");
13 }
14 0 push(@Data::Dump::FILTERS, $filter);
15 0 return $filter;
16 }
17  
18 0 ▶sub remove_dump_filter {
Subroutine remove_dump_filter: not called CC=1 SCAR=6.9
Pod documented
19 0 my $filter = shift;
20 0 @Data::Dump::FILTERS = grep $_ ne $filter, @Data::Dump::FILTERS;
21 }
22  
23 8 ▶sub dump_filtered {
Subroutine dump_filtered: called CC=4 SCAR=16.4
Pod documented
24 8 my $filter = pop;
25 8 ▶ if (defined($filter) && ref($filter) ne "CODE") {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $filter and ref $filter ne "CODE") 0 8 8
Condition33%1/3
defined $filter and ref $filter ne "CODE"
!ll&&!rl&&r
080
MC/DC0%0/2
defined $filter and ref $filter ne "CODE"
defined $filter ref $filter ne "CODE"
Truth table33%1/3
A and B
A= defined $filterB= ref $filter ne "CODE"
ABresult
0X0
100
111
26 0 Carp::croak("Last argument to dump_filtered must be undef or a code reference");
27 }
28 8 ▶ local @Data::Dump::FILTERS = ($filter ? $filter : ());
Branch: 1 branch
BranchTrueFalseTotal
$filter ? : 8 0 8
29 8 return &Data::Dump::dump;
30 }
31  
32 1 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<add_filter>.
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<add_filter()> are ignored when
64 this interface is invoked. Actually, passing C<undef> 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<undef>.
75  
76 sub filter_callback {
77 my($ctx, $object_ref) = @_;
78 ...
79 return { ... }
80 }
81  
82 If the filter callback returns C<undef> (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<Data::Dump>
« Dump/Trace.pm ↑ Summary Dump/FilterContext.pm »