NAME

Data::Printer::Filter - Create powerful stand-alone filters for Data::Printer

SYNOPSIS

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

DESCRIPTION

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 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.

HELPER FUNCTIONS

COMPLETE ANNOTATED EXAMPLE

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 Data::Printer::Object for extra documentation on the methods used above and many others!

DECORATING EXISTING FILTERS

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);

AVAILABLE FILTERS

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 <https://metacpan.org/search?q=Data%3A%3APrinter%3A%3AFilter> for a complete list!

SEE ALSO

Data::Printer