Data::Printer::Filter - Create powerful stand-alone filters for Data::Printer
Every time you say in your .dataprinter file:
filters = SomeFilter, OtherFilter
Data::Printer will look for Data::Printer::Filter::SomeFilter and
Data::Printer::Filter::OtherFilter on your @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 .dataprinter file:
filters = MyFilter
the Data::Printer manpage 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 can put your filters inline in either your use statements
or your inline calls to 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 Data::Printer::Filter comes in. Every time you use it
in a package it will export the filter keyword which you can use to
create your own filters.
Note: the loading 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.
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 current
the Data::Printer::Object manpage 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 ``return;'' statement
meaning ``Nothing to do, my mistake, let other filters have a go'' (which
includes core filters from Data::Printer itself).
You may use the current the Data::Printer::Object manpage to issue formatting calls
like:
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
'filter_array.header'. It can be set either with:
use DDP filter_array => { header => 1 };
Or on .dataprinter as:
filter_array.header = 1
If it is set, we'll start the output string with ``got this array'', colored
in whatever color was set by the user under the filter_array_header
color tag - and defaulting to '#cc7fa2' in this case.
Then it updates the indentation, so any call to $ddp->newline will add
an extra level of indentation to our output.
After that we walk through the array using foreach and append each element
to our output string as newline + content, where the content is whatever
string was returned from $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 the Data::Printer::Object manpage for extra documentation on the methods used
above and many others!
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);
Data::Printer comes with filters for all Perl data types and several filters
for popular Perl modules available on CPAN. Take a look at
the Data::Printer::Filter namespace for a complete list!
the Data::Printer manpage
|