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