line
stmt
bran
cond
sub
pod
time
code
1
package Data::Pretty::Filtered;
2
2
2
932
use strict;
2
5
2
58
3
2
2
9
use warnings;
2
3
2
53
4
2
2
10
use vars qw( $VERSION );
2
4
2
103
5
our $VERSION = 'v0.1.0';
6
7
2
2
9
use Data::Pretty ();
2
9
2
46
8
2
2
11
use Carp ();
2
3
2
51
9
10
2
2
913
use parent 'Exporter';
2
561
2
10
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
10
my $filter = pop;
29
8
50
33
42
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
22
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