NAME¶
Data::Printer::Filter - Create powerful stand-alone filters for Data::Printer
SYNOPSIS¶
Create your filter module:
package Data::Printer::Filter::MyFilter;
use strict;
use warnings;
use Data::Printer::Filter;
# type filter
filter 'SCALAR', sub {
my ($ref, $properties) = @_;
my $val = $$ref;
if ($val > 100) {
return 'too big!!';
}
else {
return $val;
}
};
# you can also filter objects of any class
filter 'Some::Class', sub {
my ($object, $properties) = @_;
return $ref->some_method; # or whatever
# see L</HELPER FUNCTIONS> below for
# customization options, including
# proper indentation.
}
1;
Later, in your main code:
use Data::Printer {
filters => {
-external => [ 'MyFilter', 'OtherFilter' ],
# you can still add regular (inline) filters
SCALAR => sub {
...
}
},
};
WARNING - ALPHA CODE (VERY LOOSE API)¶
We are still experimenting with the standalone filter syntax, so
filters
written like so may break in the future without any warning!
If you care, or have any suggestions, please drop me a line via RT,
email, or find me ('garu') on irc.perl.org.
You have been warned.
DESCRIPTION¶
Data::Printer lets you add custom filters to display data structures and
objects, by either specifying them during "use", in the
".dataprinter" configuration file, or even in runtime
customizations.
But there are times when you may want to group similar filters, or make them
standalone in order to be easily reutilized in other environments and
applications, or even upload them to CPAN so other people can benefit from a
cleaner - and clearer - object/structure dump.
This is where "Data::Printer::Filter" comes in. It
exports into
your package's namespace the "filter" function, along with some
helpers to create custom filter packages.
Data::Printer recognizes all filters in the "Data::Printer::Filter::*"
namespace. You can load them by specifying them in the '-external' filter list
(note the dash, to avoid clashing with a potential class or pragma labelled
'external'):
use Data::Printer {
filters => {
-external => 'MyFilter',
},
};
This will load all filters defined by the
"Data::Printer::Filter::MyFilter" module.
If there are more than one filter, use an array reference instead:
-external => [ 'MyFilter', 'MyOtherFilter' ]
IMPORTANT: THIS WAY OF LOADING EXTERNAL PLUGINS IS EXPERIMENTAL AND
SUBJECT TO SUDDEN CHANGE! IF YOU CARE, AND/OR HAVE IDEAS ON A BETTER
API, PLEASE LET US KNOW
HELPER FUNCTIONS¶
filter TYPE, sub { ... };¶
The "filter" function creates a new filter for
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 properties in effect
(so you can inspect for certain options, etc). The subroutine is expected to
return a string containing whatever it wants "Data::Printer" to
display on screen.
p()¶
This is the same as "Data::Printer"'s p(), only you can't rename it.
You can use this to throw some data structures back at
"Data::Printer" and use the results in your own return string - like
when manipulating hashes or arrays.
newline()¶
This helper returns a string using the linebreak as specified by the caller's
settings. For instance, it provides the proper indentation level of spaces for
you and considers the "multiline" option to avoid line breakage.
In other words, if you do this:
filter ARRAY => {
my ($ref, $p) = @_;
my $string = "Hey!! I got this array:";
foreach my $val (@$ref) {
$string .= newline . p($val);
}
return $string;
};
... your "p($val)" returns will be properly indented, vertically
aligned to your level of the data structure, while simply using "\n"
would just make things messy if your structure has more than one level of
depth.
indent()¶
outdent()¶
These two helpers let you increase/decrease the indentation level of your data
display, for "newline()" and nested "p()" calls inside
your filters.
For example, the filter defined in the "newline" explanation above
would show the values on the same (vertically aligned) level as the "I
got this array" message. If you wanted your array to be one level further
deep, you could use this instead:
filter ARRAY => {
my ($ref, $p) = @_;
my $string = "Hey!! I got this array:";
indent;
foreach my $val (@$ref) {
$string .= newline . p($val);
}
outdent;
return $string;
};
COLORIZATION¶
You can use Term::ANSIColor's "colored()"' for string colorization.
Data::Printer will automatically enable/disable colors for you.
EXISTING FILTERS¶
This is meant to provide a complete list of standalone filters for Data::Printer
available on CPAN. If you write one, please put it under the
"Data::Printer::Filter::*" namespace, and drop me a line so I can
add it to this list!
Databases¶
Data::Printer::Filter::DB provides filters for Database objects. So far only DBI
is covered, but more to come!
Dates & Times¶
Data::Printer::Filter::DateTime pretty-prints several date and time objects (not
just DateTime) for you on the fly, including duration/delta objects!
URIs¶
Data::Printer::Filter::URI filters through several URI manipulation classes and
displays the URI as a colored string. A very nice addition by Stanislaw Pusep
(SYP).
USING MORE THAN ONE FILTER FOR THE SAME TYPE/CLASS¶
As of version 0.13, standalone filters let you stack together filters for the
same type or class. Filters of the same type are called in order, until one of
them returns a string. This lets you have several filters inspecting the same
given value until one of them decides to actually treat it somehow.
If your filter catched a value and you don't want to treat it, simply return and
the next filter will be called. If there are no other filters for that
particular class or type available, the standard Data::Printer calls will be
used.
For example:
filter SCALAR => sub {
my ($ref, $properties) = @_;
if ( Scalar::Util::looks_like_number $$ref ) {
return sprintf "%.8d", $$ref;
}
return; # lets the other SCALAR filter have a go
};
filter SCALAR => sub {
my ($ref, $properties) = @_;
return qq["$$ref"];
};
Note that this "filter stack" is not possible on inline filters, since
it's a hash and keys with the same name are overwritten. Instead, you can pass
them as an array reference:
use Data::Printer filters => {
SCALAR => [ sub { ... }, sub { ... } ],
};
SEE ALSO¶
Data::Printer
LICENSE AND COPYRIGHT¶
Copyright 2011 Breno G. de Oliveira "<garu at cpan.org>". All
rights reserved.
This module is free software; you can redistribute it and/or modify it under the
same terms as Perl itself. See perlartistic.