.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Data::Printer::Filter 3pm"
.TH Data::Printer::Filter 3pm 2024-04-27 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Data::Printer::Filter \- Create powerful stand\-alone filters for Data::Printer
.SH SYNOPSIS
.IX Header "SYNOPSIS"
Every time you say in your \f(CW\*(C`.dataprinter\*(C'\fR file:
.PP
.Vb 1
\&    filters = SomeFilter, OtherFilter
.Ve
.PP
Data::Printer will look for \f(CW\*(C`Data::Printer::Filter::SomeFilter\*(C'\fR and
\&\f(CW\*(C`Data::Printer::Filter::OtherFilter\*(C'\fR on your \f(CW@INC\fR and load them.
To load filters without a configuration file:
.PP
.Vb 1
\&    use DDP filters => [\*(AqSomeFilter\*(Aq, \*(AqOtherFilter\*(Aq];
.Ve
.PP
Creating your own filter module is super easy:
.PP
.Vb 2
\&    package Data::Printer::Filter::MyFilter;
\&    use Data::Printer::Filter;
\&
\&    # this filter will run every time DDP runs into a string/number
\&    filter \*(AqSCALAR\*(Aq => sub {
\&        my ($scalar_ref, $ddp) = @_;
\&
\&        if ($$scalar_ref =~ /password/) {
\&            return \*(Aq*******\*(Aq;
\&        }
\&        return; # <\-\- let other SCALAR filters have a go!
\&    };
\&
\&    # you can also filter objects of any class!
\&    filter \*(AqSome::Class\*(Aq => sub {
\&        my ($object, $ddp) = @_;
\&
\&        if (exists $object\->{some_data}) {
\&            return $ddp\->parse( $object\->{some_data} );
\&        }
\&        else {
\&            return $object\->some_method;
\&        }
\&    };
.Ve
.PP
Later, in your main code:
.PP
.Vb 1
\&    use DDP filters => [\*(AqMyFilter\*(Aq];
.Ve
.PP
Or, in your \f(CW\*(C`.dataprinter\*(C'\fR file:
.PP
.Vb 1
\&    filters = MyFilter
.Ve
.SH DESCRIPTION
.IX Header "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.
.PP
While you \fIcan\fR put your filters inline in either your \f(CW\*(C`use\*(C'\fR statements
or your inline calls to \f(CWp()\fR, like so:
.PP
.Vb 3
\&    use DDP filters => [{
\&        SCALAR => sub { \*(AqOMG A SCALAR!!\*(Aq }
\&    }];
\&
\&    p @x, filters => [{ HASH => sub { die \*(Aqoh, noes! found a hash in my array\*(Aq } }];
.Ve
.PP
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.
.PP
This is where \f(CW\*(C`Data::Printer::Filter\*(C'\fR comes in. Every time you \f(CW\*(C`use\*(C'\fR it
in a package it will export the \f(CW\*(C`filter\*(C'\fR keyword which you can use to
create your own filters.
.PP
Note: the loading \fBorder of filters matter\fR. They will be called in order
and the first one to return something for the data being analysed will be
used.
.SH "HELPER FUNCTIONS"
.IX Header "HELPER FUNCTIONS"
.SS "filter TYPE, sub { ... };"
.IX Subsection "filter TYPE, sub { ... };"
The \f(CW\*(C`filter\*(C'\fR function creates a new filter for \fITYPE\fR, 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.
.PP
Inside your filter you are expected to either return a string with whatever
you want to display for that type/object, or an empty "\f(CW\*(C`return;\*(C'\fR" statement
meaning \fI"Nothing to do, my mistake, let other filters have a go"\fR (which
includes core filters from Data::Printer itself).
.PP
You may use the current Data::Printer::Object to issue formatting calls
like:
.IP \(bu 4
\&\f(CW\*(C`$ddp\->indent\*(C'\fR \- adds to the current indentation level.
.IP \(bu 4
\&\f(CW\*(C`$ddp\->outdent\*(C'\fR \- subtracts from the current indentation level.
.IP \(bu 4
\&\f(CW\*(C`$ddp\->newline\*(C'\fR \- returns a string containing a lineabreak
and the proper number of spaces for the right indentation. It also
accounts for the \f(CW\*(C`multiline\*(C'\fR option so you don't have to worry about it.
.IP \(bu 4
\&\f(CW\*(C`$ddp\->maybe_colorize( $string, \*(Aqlabel\*(Aq, \*(Aqdefault_color\*(Aq )\*(C'\fR \-
returns the given string either unmodified (if the output is not colored) or
with the color set for \fI'label'\fR (e.g. "class", "array", "brackets"). You are
encouraged to provide your own custom colors by labelling them \f(CW\*(C`filter_*\*(C'\fR,
which is guaranteed to never collide with a core color label.
.IP \(bu 4
\&\f(CW\*(C`$ddp\->extra_config\*(C'\fR \- all options set by the user either in
calls to DDP or in the \f(CW\*(C`.dataprinter\*(C'\fR 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 \f(CW\*(C`filter_*\*(C'\fR, which is guaranteed
to never collide with a local setting.
.IP \(bu 4
\&\f(CW\*(C`$ddp\->parse( $data )\*(C'\fR \- parses and returns the string output of
the given data structure.
.SH "COMPLETE ANNOTATED EXAMPLE"
.IX Header "COMPLETE ANNOTATED EXAMPLE"
As an example, let's create a custom filter for arrays using
all the options above:
.PP
.Vb 3
\&    filter ARRAY => sub {
\&        my ($array_ref, $ddp) = @_;
\&        my $output;
\&
\&        if ($ddp\->extra_config\->{filter_array}{header}) {
\&            $output = $ddp\->maybe_colorize(
\&                \*(Aqgot this array:\*(Aq,
\&                \*(Aqfilter_array_header\*(Aq,
\&                \*(Aq#cc7fa2\*(Aq
\&            );
\&        }
\&
\&        $ddp\->indent;
\&        foreach my $element (@$ref) {
\&            $output .= $ddp\->newline . $ddp\->parse($element);
\&        }
\&        $ddp\->outdent;
\&
\&        return $output;
\&    };
.Ve
.PP
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
\&\fI'filter_array.header'\fR. It can be set either with:
.PP
.Vb 1
\&    use DDP filter_array => { header => 1 };
.Ve
.PP
Or on \f(CW\*(C`.dataprinter\*(C'\fR as:
.PP
.Vb 1
\&    filter_array.header = 1
.Ve
.PP
If it is set, we'll start the output string with \fI"got this array"\fR, colored
in whatever color was set by the user under the \f(CW\*(C`filter_array_header\*(C'\fR
color tag \- and defaulting to '#cc7fa2' in this case.
.PP
Then it updates the indentation, so any call to \f(CW\*(C`$ddp\->newline\*(C'\fR will add
an extra level of indentation to our output.
.PP
After that we walk through the array using \f(CW\*(C`foreach\*(C'\fR and append each element
to our output string as \fInewline + content\fR, where the content is whatever
string was returned from \f(CW\*(C`$ddp\->parse\*(C'\fR. 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.
.PP
Check Data::Printer::Object for extra documentation on the methods used
above and many others!
.SH "DECORATING EXISTING FILTERS"
.IX Header "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:
.PP
.Vb 1
\&    my $str = Data::Printer::Filter::HASH::parse($ref, $ddp);
.Ve
.SH "AVAILABLE FILTERS"
.IX Header "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!
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Data::Printer