1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
|
package Data::Printer::Filter;
use strict;
use warnings;
use Data::Printer::Common;
use Scalar::Util;
sub import {
my $caller = caller;
my %_filters_for = ();
my $filter = sub {
my ($name, $code) = @_;
Data::Printer::Common::_die( "syntax: filter 'Class', sub { ... }" )
unless defined $name
&& defined $code
&& Scalar::Util::reftype($code) eq 'CODE';
my $target = Data::Printer::Common::_filter_category_for($name);
unshift @{$_filters_for{$target}{$name}}, sub {
my ($item, $ddp) = @_;
$code->($item, $ddp);
};
};
{
no strict 'refs';
*{"$caller\::filter"} = $filter;
*{"$caller\::_filter_list"} = sub { \%_filters_for };
}
};
1;
__END__
=head1 NAME
Data::Printer::Filter - Create powerful stand-alone filters for Data::Printer
=head1 SYNOPSIS
Every time you say in your C<.dataprinter> file:
filters = SomeFilter, OtherFilter
Data::Printer will look for C<Data::Printer::Filter::SomeFilter> and
C<Data::Printer::Filter::OtherFilter> on your C<@INC> and load them.
To load filters without a configuration file:
use DDP filters => ['SomeFilter', 'OtherFilter'];
Creating your own filter module is super easy:
package Data::Printer::Filter::MyFilter;
use Data::Printer::Filter;
# this filter will run every time DDP runs into a string/number
filter 'SCALAR' => sub {
my ($scalar_ref, $ddp) = @_;
if ($$scalar_ref =~ /password/) {
return '*******';
}
return; # <-- let other SCALAR filters have a go!
};
# you can also filter objects of any class!
filter 'Some::Class' => sub {
my ($object, $ddp) = @_;
if (exists $object->{some_data}) {
return $ddp->parse( $object->{some_data} );
}
else {
return $object->some_method;
}
};
Later, in your main code:
use DDP filters => ['MyFilter'];
Or, in your C<.dataprinter> file:
filters = MyFilter
=head1 DESCRIPTION
L<Data::Printer> lets you add custom filters to display data structures and
objects as you see fit to better understand and inspect/debug its contents.
While you I<can> put your filters inline in either your C<use> statements
or your inline calls to C<p()>, like so:
use DDP filters => [{
SCALAR => sub { 'OMG A SCALAR!!' }
}];
p @x, filters => [{ HASH => sub { die 'oh, noes! found a hash in my array' } }];
Most of the time you probably want to create full-featured filters as a
standalone module, to use in many different environments and maybe even
upload and share them on CPAN.
This is where C<Data::Printer::Filter> comes in. Every time you C<use> it
in a package it will export the C<filter> keyword which you can use to
create your own filters.
Note: the loading B<order of filters matter>. They will be called in order
and the first one to return something for the data being analysed will be
used.
=head1 HELPER FUNCTIONS
=head2 filter TYPE, sub { ... };
The C<filter> function creates a new filter for I<TYPE>, using the given
subref. The subref receives two arguments: the item itself - be it an object
or a reference to a standard Perl type - and the current
L<Data::Printer::Object> being used to parse the data.
Inside your filter you are expected to either return a string with whatever
you want to display for that type/object, or an empty "C<return;>" statement
meaning I<"Nothing to do, my mistake, let other filters have a go"> (which
includes core filters from Data::Printer itself).
You may use the current L<Data::Printer::Object> to issue formatting calls
like:
=over 4
=item * C<< $ddp->indent >> - adds to the current indentation level.
=item * C<< $ddp->outdent >> - subtracts from the current indentation level.
=item * C<< $ddp->newline >> - returns a string containing a lineabreak
and the proper number of spaces for the right indentation. It also
accounts for the C<multiline> option so you don't have to worry about it.
=item * C<< $ddp->maybe_colorize( $string, 'label', 'default_color' ) >> -
returns the given string either unmodified (if the output is not colored) or
with the color set for I<'label'> (e.g. "class", "array", "brackets"). You are
encouraged to provide your own custom colors by labelling them C<filter_*>,
which is guaranteed to never collide with a core color label.
=item * C<< $ddp->extra_config >> - all options set by the user either in
calls to DDP or in the C<.dataprinter> file that are not used by
Data::Printer itself will be put here. You are encouraged to provide your
own customization options by labelling them C<filter_*>, which is guaranteed
to never collide with a local setting.
=item * C<< $ddp->parse( $data ) >> - parses and returns the string output of
the given data structure.
=back
=head1 COMPLETE ANNOTATED EXAMPLE
As an example, let's create a custom filter for arrays using
all the options above:
filter ARRAY => sub {
my ($array_ref, $ddp) = @_;
my $output;
if ($ddp->extra_config->{filter_array}{header}) {
$output = $ddp->maybe_colorize(
'got this array:',
'filter_array_header',
'#cc7fa2'
);
}
$ddp->indent;
foreach my $element (@$ref) {
$output .= $ddp->newline . $ddp->parse($element);
}
$ddp->outdent;
return $output;
};
Then whenever you pass an array to Data::Printer, it will call this code.
First it checks if the user has our made up custom option
I<'filter_array.header'>. It can be set either with:
use DDP filter_array => { header => 1 };
Or on C<.dataprinter> as:
filter_array.header = 1
If it is set, we'll start the output string with I<"got this array">, colored
in whatever color was set by the user under the C<filter_array_header>
color tag - and defaulting to '#cc7fa2' in this case.
Then it updates the indentation, so any call to C<< $ddp->newline >> will add
an extra level of indentation to our output.
After that we walk through the array using C<foreach> and append each element
to our output string as I<newline + content>, where the content is whatever
string was returned from C<< $ddp->parse >>. Note that, if the element or any
of its subelements is an array, our filter will be called again, this time
for the new content.
Check L<Data::Printer::Object> for extra documentation on the methods used
above and many others!
=head1 DECORATING EXISTING FILTERS
It may be the case where you want to call this filter and manipulate the
result. To do so, make sure you make a named subroutine for your filters
instead of using an anonymous one. For instance, all of Data::Printer's
filters for core types have a 'parse' public function you can use:
my $str = Data::Printer::Filter::HASH::parse($ref, $ddp);
=head1 AVAILABLE FILTERS
Data::Printer comes with filters for all Perl data types and several filters
for popular Perl modules available on CPAN. Take a look at
L<< the Data::Printer::Filter namespace|https://metacpan.org/search?q=Data%3A%3APrinter%3A%3AFilter >> for a complete list!
=head1 SEE ALSO
L<Data::Printer>
|
