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!

SEE ALSO

       Data::Printer