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

perl v5.36.0                                       2023-10-21                         Data::Printer::Filter(3pm)