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