File Coverage

lib/Data/Pretty/Filtered.pm
Criterion Covered Total %
statement 22 30 73.3
branch 2 6 33.3
condition 1 3 33.3
subroutine 7 9 77.7
pod 3 3 100.0
total 35 51 68.6


line stmt bran cond sub pod time code
1             package Data::Pretty::Filtered;
2 2     2   952 use strict;
  2         4  
  2         58  
3 2     2   10 use warnings;
  2         12  
  2         54  
4 2     2   8 use vars qw( $VERSION );
  2         4  
  2         129  
5             our $VERSION = 'v0.1.0';
6              
7 2     2   12 use Data::Pretty ();
  2         2  
  2         40  
8 2     2   9 use Carp ();
  2         3  
  2         72  
9              
10 2     2   940 use parent 'Exporter';
  2         613  
  2         16  
11             our @EXPORT_OK = qw(add_dump_filter remove_dump_filter dump_filtered);
12              
13             sub add_dump_filter {
14 0     0 1 0 my $filter = shift;
15 0 0       0 unless (ref($filter) eq "CODE") {
16 0         0 Carp::croak("add_dump_filter argument must be a code reference");
17             }
18 0         0 push(@Data::Pretty::FILTERS, $filter);
19 0         0 return $filter;
20             }
21              
22             sub remove_dump_filter {
23 0     0 1 0 my $filter = shift;
24 0         0 @Data::Pretty::FILTERS = grep $_ ne $filter, @Data::Pretty::FILTERS;
25             }
26              
27             sub dump_filtered {
28 8     8 1 13 my $filter = pop;
29 8 50 33     41 if (defined($filter) && ref($filter) ne "CODE") {
30 0         0 Carp::croak("Last argument to dump_filtered must be undef or a code reference");
31             }
32 8 50       27 local @Data::Pretty::FILTERS = ($filter ? $filter : ());
33 8         17 return &Data::Pretty::dump;
34             }
35              
36             1;
37              
38             =head1 NAME
39              
40             Data::Pretty::Filtered - Pretty printing with filtering
41              
42             =head1 DESCRIPTION
43              
44             The following functions are provided:
45              
46             =head1 FUNCTIONS
47              
48             =head2 add_dump_filter( \&filter )
49              
50             This registers a filter function to be used by the regular L function. By default no filters are active.
51              
52             Since registering filters has a global effect is might be more appropriate to use the dump_filtered() function instead.
53              
54             =head2 remove_dump_filter( \&filter )
55              
56             Unregister the given callback function as filter callback. This undoes the effect of L.
57              
58             =head2 dump_filtered(..., \&filter )
59              
60             Works like L, but the last argument should be a filter callback function. As objects are visited the filter callback is invoked at it might influence how objects are dumped.
61              
62             Any filters registered with L are ignored when this interface is invoked. Actually, passing C as C<\&filter> is allowed and C<< dump_filtered(..., undef) >> is the official way to force unfiltered dumps.
63              
64             =head1 FILTER CALLBACK
65              
66             A filter callback is a function that will be invoked with 2 arguments: a context object and reference to the object currently visited.
67              
68             The return value should either be a hash reference or C.
69              
70             sub filter_callback {
71             my($ctx, $object_ref) = @_;
72             ...
73             return { ... }
74             }
75              
76             If the filter callback returns C (or nothing) then normal processing and formatting of the visited object happens.
77              
78             If the filter callback returns a hash it might replace or annotate the representation of the current object.
79              
80             =head1 FILTER CONTEXT
81              
82             The L provides methods that can be used to determine what kind of object is currently visited and where it's located. Please check the L
83              
84             =head2 FILTER RETURN HASH
85              
86             The following elements has significance in the returned hash:
87              
88             =over 4
89              
90             =item * C => C<$string>
91              
92             Incorporates the given string as the representation for the current value
93              
94             =item * C => C<$value>
95              
96             C the given value instead of the one visited and passed in as $object.
97              
98             This is basically the same as specifying C<< dump => Data::Pretty::dump($value) >>.
99              
100             =item * C => C<$comment>
101              
102             Prefixes the value with the given comment string
103              
104             =item * C => C<$class>
105              
106             Makes it look as if the current object is of the given C<$class> instead of the class it really has (if any). The internals of the object is dumped in the regular way. The C<$class> can be the empty string to make C pretend the object was not blessed at all.
107              
108             =item * C => ['key1', 'key2',...]
109              
110             =item * C => \&code
111              
112             If the C<$object> is a hash dump is as normal but pretend that the listed keys did not exist. If the argument is a function then the function is called to determine if the given key should be hidden.
113              
114             =back
115              
116             =head1 SEE ALSO
117              
118             L, L
119              
120             =head1 CREDITS
121              
122             Credits to Gisle Aas for the original L version and to Breno G. de Oliveira for maintaining it.
123              
124             =head1 COPYRIGHT & LICENSE
125              
126             Copyright(c) 2023 DEGUEST Pte. Ltd.
127              
128             All rights reserved
129              
130             This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
131              
132             =cut