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