Data::Printer::Filter - Create powerful stand-alone filters for Data::Printer
Every time you say in your .dataprinter file:
.dataprinter
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:
Data::Printer::Filter::SomeFilter
Data::Printer::Filter::OtherFilter
@INC
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
Data::Printer 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
p()
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.
Data::Printer::Filter
filter
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 Data::Printer::Object 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).
return;
You may use the current Data::Printer::Object to issue formatting calls like:
$ddp->indent - adds to the current indentation level.
$ddp->indent
$ddp->outdent - subtracts from the current indentation level.
$ddp->outdent
$ddp->newline - returns a string containing a lineabreak and the proper number of spaces for the right indentation. It also accounts for the multiline option so you don't have to worry about it.
$ddp->newline
multiline
$ddp->maybe_colorize( $string, 'label', 'default_color' ) - returns the given string either unmodified (if the output is not colored) or with the color set for 'label' (e.g. "class", "array", "brackets"). You are encouraged to provide your own custom colors by labelling them filter_*, which is guaranteed to never collide with a core color label.
$ddp->maybe_colorize( $string, 'label', 'default_color' )
filter_*
$ddp->extra_config - all options set by the user either in calls to DDP or in the .dataprinter file that are not used by Data::Printer itself will be put here. You are encouraged to provide your own customization options by labelling them filter_*, which is guaranteed to never collide with a local setting.
$ddp->extra_config
$ddp->parse( $data ) - parses and returns the string output of the given data structure.
$ddp->parse( $data )
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.
filter_array_header
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.
foreach
$ddp->parse
Check Data::Printer::Object 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!
Data::Printer
To install Data::Printer, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Data::Printer
CPAN shell
perl -MCPAN -e shell install Data::Printer
For more information on module installation, please visit the detailed CPAN module installation guide.