1Data::Printer::Filter(3U)ser Contributed Perl DocumentatiDoanta::Printer::Filter(3)
2
6 Data::Printer::Filter - Create powerful stand-alone filters for
7 Data::Printer
8
10 Create your filter module:
11 package Data::Printer::Filter::MyFilter;
13 use strict;
14 use warnings;
15 use Data::Printer::Filter;
17 # type filter
19 filter 'SCALAR', sub {
20 my ($ref, $properties) = @_;
21 my $val = $$ref;
22 if ($val > 100) {
24 return 'too big!!';
25 }
26 else {
27 return $val;
28 }
29 };
30 # you can also filter objects of any class
32 filter 'Some::Class', sub {
33 my ($object, $properties) = @_;
34 return $ref->some_method; # or whatever
36 # see 'HELPER FUNCTIONS' below for
38 # customization options, including
39 # proper indentation.
40 };
41 1;
43 Later, in your main code:
45 use Data::Printer {
47 filters => {
48 -external => [ 'MyFilter', 'OtherFilter' ],
49 # you can still add regular (inline) filters
51 SCALAR => sub {
52 ...
53 }
54 },
55 };
56
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 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 You have been warned.
65
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 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 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 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 use Data::Printer {
86 filters => {
87 -external => 'MyFilter',
88 },
89 };
90 This will load all filters defined by the
92 "Data::Printer::Filter::MyFilter" module.
93 If there are more than one filter, use an array reference instead:
95 -external => [ 'MyFilter', 'MyOtherFilter' ]
97 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
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 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 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 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 In other words, if you do this:
129 filter ARRAY => {
131 my ($ref, $p) = @_;
132 my $string = "Hey!! I got this array:";
133 foreach my $val (@$ref) {
135 $string .= newline . p($val);
136 }
137 return $string;
139 };
140 ... 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 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 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 filter ARRAY => {
158 my ($ref, $p) = @_;
159 my $string = "Hey!! I got this array:";
160 indent;
162 foreach my $val (@$ref) {
163 $string .= newline . p($val);
164 }
165 outdent;
166 return $string;
168 };
169
171 You can use Term::ANSIColor's "colored()"' for string colorization.
172 Data::Printer will automatically enable/disable colors for you.
173
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 Databases
181 Data::Printer::Filter::DB provides filters for Database objects. So far
182 only DBI is covered, but more to come!
183 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 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 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 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 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 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
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 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 For example:
227 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 filter SCALAR => sub {
237 my ($ref, $properties) = @_;
238 return qq["$$ref"];
239 };
240 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 use Data::Printer filters => {
246 SCALAR => [ sub { ... }, sub { ... } ],
247 };
248
250 Data::Printer
251
253 Copyright 2011 Breno G. de Oliveira "<garu at cpan.org>". All rights
254 reserved.
255 This module is free software; you can redistribute it and/or modify it
257 under the same terms as Perl itself. See perlartistic.
258perl v5.32.0 2020-07-28 Data::Printer::Filter(3)