| 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
| |||||||||||||||||||||||||||||
| 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
Condition33%1/3
defined $filter and ref $filter ne "CODE"
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"
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 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> | ||||||||||||||||||||||||||||