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       Create your filter module:
11
12         package Data::Printer::Filter::MyFilter;
13         use strict;
14         use warnings;
15
16         use Data::Printer::Filter;
17
18         # type filter
19         filter 'SCALAR', sub {
20             my ($ref, $properties) = @_;
21             my $val = $$ref;
22
23             if ($val > 100) {
24                 return 'too big!!';
25             }
26             else {
27                 return $val;
28             }
29         };
30
31         # you can also filter objects of any class
32         filter 'Some::Class', sub {
33             my ($object, $properties) = @_;
34
35             return $ref->some_method;   # or whatever
36
37             # see 'HELPER FUNCTIONS' below for
38             # customization options, including
39             # proper indentation.
40         };
41
42         1;
43
44       Later, in your main code:
45
46         use Data::Printer {
47             filters => {
48                 -external => [ 'MyFilter', 'OtherFilter' ],
49
50                 # you can still add regular (inline) filters
51                 SCALAR => sub {
52                     ...
53                 }
54             },
55         };
56

WARNING - ALPHA CODE (VERY LOOSE API)

58       We are still experimenting with the standalone filter syntax, so
59       filters written like so may break in the future without any warning!
60
61       If you care, or have any suggestions, please drop me a line via RT,
62       email, or find me ('garu') on irc.perl.org.
63
64       You have been warned.
65

DESCRIPTION

67       Data::Printer lets you add custom filters to display data structures
68       and objects, by either specifying them during "use", in the
69       ".dataprinter" configuration file, or even in runtime customizations.
70
71       But there are times when you may want to group similar filters, or make
72       them standalone in order to be easily reutilized in other environments
73       and applications, or even upload them to CPAN so other people can
74       benefit from a cleaner - and clearer - object/structure dump.
75
76       This is where "Data::Printer::Filter" comes in. It exports into your
77       package's namespace the "filter" function, along with some helpers to
78       create custom filter packages.
79
80       Data::Printer recognizes all filters in the "Data::Printer::Filter::*"
81       namespace. You can load them by specifying them in the '-external'
82       filter list (note the dash, to avoid clashing with a potential class or
83       pragma labelled 'external'):
84
85         use Data::Printer {
86             filters => {
87                 -external => 'MyFilter',
88             },
89         };
90
91       This will load all filters defined by the
92       "Data::Printer::Filter::MyFilter" module.
93
94       If there are more than one filter, use an array reference instead:
95
96         -external => [ 'MyFilter', 'MyOtherFilter' ]
97
98       IMPORTANT: THIS WAY OF LOADING EXTERNAL PLUGINS IS EXPERIMENTAL AND
99       SUBJECT TO SUDDEN CHANGE! IF YOU CARE, AND/OR HAVE IDEAS ON A BETTER
100       API, PLEASE LET US KNOW
101

HELPER FUNCTIONS

103   filter TYPE, sub { ... };
104       The "filter" function creates a new filter for TYPE, using the given
105       subref. The subref receives two arguments: the item itself - be it an
106       object or a reference to a standard Perl type - and the properties in
107       effect (so you can inspect for certain options, etc). The subroutine is
108       expected to return a string containing whatever it wants
109       "Data::Printer" to display on screen.
110
111   p()
112       This is the same as "Data::Printer"'s p(), only you can't rename it.
113       You can use this to throw some data structures back at "Data::Printer"
114       and use the results in your own return string - like when manipulating
115       hashes or arrays.
116
117   np()
118       This is the same as "Data::Printer"'s np().  You can use this to throw
119       some data structures back at "Data::Printer" and use the results in
120       your own return string - like when manipulating hashes or arrays.
121
122   newline()
123       This helper returns a string using the linebreak as specified by the
124       caller's settings. For instance, it provides the proper indentation
125       level of spaces for you and considers the "multiline" option to avoid
126       line breakage.
127
128       In other words, if you do this:
129
130          filter ARRAY => {
131              my ($ref, $p) = @_;
132              my $string = "Hey!! I got this array:";
133
134              foreach my $val (@$ref) {
135                  $string .= newline . p($val);
136              }
137
138              return $string;
139          };
140
141       ... your "p($val)" returns will be properly indented, vertically
142       aligned to your level of the data structure, while simply using "\n"
143       would just make things messy if your structure has more than one level
144       of depth.
145
146   indent()
147   outdent()
148       These two helpers let you increase/decrease the indentation level of
149       your data display, for "newline()" and nested "p()" calls inside your
150       filters.
151
152       For example, the filter defined in the "newline" explanation above
153       would show the values on the same (vertically aligned) level as the "I
154       got this array" message. If you wanted your array to be one level
155       further deep, you could use this instead:
156
157         filter ARRAY => {
158             my ($ref, $p) = @_;
159             my $string = "Hey!! I got this array:";
160
161             indent;
162             foreach my $val (@$ref) {
163                 $string .= newline . p($val);
164             }
165             outdent;
166
167             return $string;
168         };
169

COLORIZATION

171       You can use Term::ANSIColor's "colored()"' for string colorization.
172       Data::Printer will automatically enable/disable colors for you.
173

EXISTING FILTERS

175       This is meant to provide a complete list of standalone filters for
176       Data::Printer available on CPAN. If you write one, please put it under
177       the "Data::Printer::Filter::*" namespace, and drop me a line so I can
178       add it to this list!
179
180   Databases
181       Data::Printer::Filter::DB provides filters for Database objects. So far
182       only DBI is covered, but more to come!
183
184   Dates & Times
185       Data::Printer::Filter::DateTime pretty-prints several date and time
186       objects (not just DateTime) for you on the fly, including
187       duration/delta objects!
188
189   Digest
190       Data::Printer::Filter::Digest displays a string containing the hash of
191       the actual message digest instead of the object. Works on
192       "Digest::MD5", "Digest::SHA", any digest class that inherits from
193       "Digest::base" and some others that implement their own thing!
194
195   ClassicRegex
196       Data::Printer::Filter::ClassicRegex changes the way Data::Printer dumps
197       regular expressions, doing it the classic "qr//" way that got popular
198       in "Data::Dumper".
199
200   JSON
201       Data::Printer::Filter::JSON, by Nuba Princigalli, lets you see your
202       JSON structures replacing boolean objects with simple "true/false"
203       strings!
204
205   URIs
206       Data::Printer::Filter::URI filters through several URI manipulation
207       classes and displays the URI as a colored string. A very nice addition
208       by Stanislaw Pusep (SYP).
209
210   Perl Data Language (PDL)
211       Data::Printer::Filter::PDL, by Zakariyya Mughal, lets you quickly see
212       the relevant contents of a PDL variable.
213

USING MORE THAN ONE FILTER FOR THE SAME TYPE/CLASS

215       As of version 0.13, standalone filters let you stack together filters
216       for the same type or class. Filters of the same type are called in
217       order, until one of them returns a string. This lets you have several
218       filters inspecting the same given value until one of them decides to
219       actually treat it somehow.
220
221       If your filter caught a value and you don't want to treat it, simply
222       return and the next filter will be called. If there are no other
223       filters for that particular class or type available, the standard
224       Data::Printer calls will be used.
225
226       For example:
227
228         filter SCALAR => sub {
229             my ($ref, $properties) = @_;
230             if ( Scalar::Util::looks_like_number $$ref ) {
231                 return sprintf "%.8d", $$ref;
232             }
233             return; # lets the other SCALAR filter have a go
234         };
235
236         filter SCALAR => sub {
237             my ($ref, $properties) = @_;
238             return qq["$$ref"];
239         };
240
241       Note that this "filter stack" is not possible on inline filters, since
242       it's a hash and keys with the same name are overwritten. Instead, you
243       can pass them as an array reference:
244
245         use Data::Printer filters => {
246             SCALAR => [ sub { ... }, sub { ... } ],
247         };
248

SEE ALSO

250       Data::Printer
251
253       Copyright 2011 Breno G. de Oliveira "<garu at cpan.org>". All rights
254       reserved.
255
256       This module is free software; you can redistribute it and/or modify it
257       under the same terms as Perl itself. See perlartistic.
258
259
260
261perl v5.32.0                      2020-07-28          Data::Printer::Filter(3)
Impressum