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