Data::Printer::Filter(3pm)

1Data::Printer::Filter(3U)ser Contributed Perl DocumentatiDoanta::Printer::Filter(3)
2
3
4

NAME

6       Data::Printer::Filter - Create powerful stand-alone filters for
7       Data::Printer
8

SYNOPSIS

10       Every time you say in your ".dataprinter" file:
11
12           filters = SomeFilter, OtherFilter
13
14       Data::Printer will look for "Data::Printer::Filter::SomeFilter" and
15       "Data::Printer::Filter::OtherFilter" on your @INC and load them.  To
16       load filters without a configuration file:
17
18           use DDP filters => ['SomeFilter', 'OtherFilter'];
19
20       Creating your own filter module is super easy:
21
22           package Data::Printer::Filter::MyFilter;
23           use Data::Printer::Filter;
24
25           # this filter will run every time DDP runs into a string/number
26           filter 'SCALAR' => sub {
27               my ($scalar_ref, $ddp) = @_;
28
29               if ($$scalar_ref =~ /password/) {
30                   return '*******';
31               }
32               return; # <-- let other SCALAR filters have a go!
33           };
34
35           # you can also filter objects of any class!
36           filter 'Some::Class' => sub {
37               my ($object, $ddp) = @_;
38
39               if (exists $object->{some_data}) {
40                   return $ddp->parse( $object->{some_data} );
41               }
42               else {
43                   return $object->some_method;
44               }
45           };
46
47       Later, in your main code:
48
49           use DDP filters => ['MyFilter'];
50
51       Or, in your ".dataprinter" file:
52
53           filters = MyFilter
54

DESCRIPTION

56       Data::Printer lets you add custom filters to display data structures
57       and objects as you see fit to better understand and inspect/debug its
58       contents.
59
60       While you can put your filters inline in either your "use" statements
61       or your inline calls to p(), like so:
62
63           use DDP filters => [{
64               SCALAR => sub { 'OMG A SCALAR!!' }
65           }];
66
67           p @x, filters => [{ HASH => sub { die 'oh, noes! found a hash in my array' } }];
68
69       Most of the time you probably want to create full-featured filters as a
70       standalone module, to use in many different environments and maybe even
71       upload and share them on CPAN.
72
73       This is where "Data::Printer::Filter" comes in. Every time you "use" it
74       in a package it will export the "filter" keyword which you can use to
75       create your own filters.
76
77       Note: the loading order of filters matter. They will be called in order
78       and the first one to return something for the data being analysed will
79       be used.
80

HELPER FUNCTIONS

82   filter TYPE, sub { ... };
83       The "filter" function creates a new filter for TYPE, using the given
84       subref. The subref receives two arguments: the item itself - be it an
85       object or a reference to a standard Perl type - and the current
86       Data::Printer::Object being used to parse the data.
87
88       Inside your filter you are expected to either return a string with
89       whatever you want to display for that type/object, or an empty
90       ""return;"" statement meaning "Nothing to do, my mistake, let other
91       filters have a go" (which includes core filters from Data::Printer
92       itself).
93
94       You may use the current Data::Printer::Object to issue formatting calls
95       like:
96
97       •   "$ddp->indent" - adds to the current indentation level.
98
99       •   "$ddp->outdent" - subtracts from the current indentation level.
100
101       •   "$ddp->newline" - returns a string containing a lineabreak and the
102           proper number of spaces for the right indentation. It also accounts
103           for the "multiline" option so you don't have to worry about it.
104
105       •   "$ddp->maybe_colorize( $string, 'label', 'default_color' )" -
106           returns the given string either unmodified (if the output is not
107           colored) or with the color set for 'label' (e.g. "class", "array",
108           "brackets"). You are encouraged to provide your own custom colors
109           by labelling them "filter_*", which is guaranteed to never collide
110           with a core color label.
111
112       •   "$ddp->extra_config" - all options set by the user either in calls
113           to DDP or in the ".dataprinter" file that are not used by
114           Data::Printer itself will be put here. You are encouraged to
115           provide your own customization options by labelling them
116           "filter_*", which is guaranteed to never collide with a local
117           setting.
118
119       •   "$ddp->parse( $data )" - parses and returns the string output of
120           the given data structure.
121

COMPLETE ANNOTATED EXAMPLE

123       As an example, let's create a custom filter for arrays using all the
124       options above:
125
126           filter ARRAY => sub {
127               my ($array_ref, $ddp) = @_;
128               my $output;
129
130               if ($ddp->extra_config->{filter_array}{header}) {
131                   $output = $ddp->maybe_colorize(
132                       'got this array:',
133                       'filter_array_header',
134                       '#cc7fa2'
135                   );
136               }
137
138               $ddp->indent;
139               foreach my $element (@$ref) {
140                   $output .= $ddp->newline . $ddp->parse($element);
141               }
142               $ddp->outdent;
143
144               return $output;
145           };
146
147       Then whenever you pass an array to Data::Printer, it will call this
148       code.  First it checks if the user has our made up custom option
149       'filter_array.header'. It can be set either with:
150
151           use DDP filter_array => { header => 1 };
152
153       Or on ".dataprinter" as:
154
155           filter_array.header = 1
156
157       If it is set, we'll start the output string with "got this array",
158       colored in whatever color was set by the user under the
159       "filter_array_header" color tag - and defaulting to '#cc7fa2' in this
160       case.
161
162       Then it updates the indentation, so any call to "$ddp->newline" will
163       add an extra level of indentation to our output.
164
165       After that we walk through the array using "foreach" and append each
166       element to our output string as newline + content, where the content is
167       whatever string was returned from "$ddp->parse". Note that, if the
168       element or any of its subelements is an array, our filter will be
169       called again, this time for the new content.
170
171       Check Data::Printer::Object for extra documentation on the methods used
172       above and many others!
173

DECORATING EXISTING FILTERS

175       It may be the case where you want to call this filter and manipulate
176       the result. To do so, make sure you make a named subroutine for your
177       filters instead of using an anonymous one. For instance, all of
178       Data::Printer's filters for core types have a 'parse' public function
179       you can use:
180
181           my $str = Data::Printer::Filter::HASH::parse($ref, $ddp);
182

AVAILABLE FILTERS

184       Data::Printer comes with filters for all Perl data types and several
185       filters for popular Perl modules available on CPAN. Take a look at the
186       Data::Printer::Filter namespace
187       <https://metacpan.org/search?q=Data%3A%3APrinter%3A%3AFilter> for a
188       complete list!
189