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

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

You may use the current Data::Printer::Object to issue formatting calls like:

"$ddp->indent" - adds to the current indentation level.
"$ddp->outdent" - subtracts from the current indentation level.
"$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->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->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->parse( $data )" - parses and returns the string output of the given data structure.

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!