.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Data::Printer::Filter 3pm"
.TH Data::Printer::Filter 3pm "2012-11-11" "perl v5.14.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"
Create your filter module:
.PP
.Vb 3
\&  package Data::Printer::Filter::MyFilter;
\&  use strict;
\&  use warnings;
\&
\&  use Data::Printer::Filter;
\&
\&  # type filter
\&  filter \*(AqSCALAR\*(Aq, sub {
\&      my ($ref, $properties) = @_;
\&      my $val = $$ref;
\&      
\&      if ($val > 100) {
\&          return \*(Aqtoo big!!\*(Aq;
\&      }
\&      else {
\&          return $val;
\&      }
\&  };
\&
\&  # you can also filter objects of any class
\&  filter \*(AqSome::Class\*(Aq, sub {
\&      my ($object, $properties) = @_;
\&
\&      return $ref\->some_method;   # or whatever
\&
\&      # see \*(AqHELPER FUNCTIONS\*(Aq below for
\&      # customization options, including
\&      # proper indentation.
\&  };
\&
\&  1;
.Ve
.PP
Later, in your main code:
.PP
.Vb 3
\&  use Data::Printer {
\&      filters => {
\&          \-external => [ \*(AqMyFilter\*(Aq, \*(AqOtherFilter\*(Aq ],
\&
\&          # you can still add regular (inline) filters
\&          SCALAR => sub {
\&              ...
\&          }
\&      },
\&  };
.Ve
.SH "WARNING \- ALPHA CODE (VERY LOOSE API)"
.IX Header "WARNING - ALPHA CODE (VERY LOOSE API)"
We are still experimenting with the standalone filter syntax, so
\&\fBfilters written like so may break in the future without any warning!\fR
.PP
\&\fBIf you care, or have any suggestions\fR, please drop me a line via \s-1RT\s0, email,
or find me ('garu') on irc.perl.org.
.PP
You have been warned.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Data::Printer lets you add custom filters to display data structures and
objects, by either specifying them during \*(L"use\*(R", in the \f(CW\*(C`.dataprinter\*(C'\fR
configuration file, or even in runtime customizations.
.PP
But there are times when you may want to group similar filters, or make
them standalone in order to be easily reutilized in other environments and
applications, or even upload them to \s-1CPAN\s0 so other people can benefit from
a cleaner \- and clearer \- object/structure dump.
.PP
This is where \f(CW\*(C`Data::Printer::Filter\*(C'\fR comes in. It \fBexports\fR into your
package's namespace the \*(L"filter\*(R" function, along with some helpers to
create custom filter packages.
.PP
Data::Printer recognizes all filters in the \f(CW\*(C`Data::Printer::Filter::*\*(C'\fR
namespace. You can load them by specifying them in the '\-external' filter
list (note the dash, to avoid clashing with a potential class or pragma
labelled 'external'):
.PP
.Vb 5
\&  use Data::Printer {
\&      filters => {
\&          \-external => \*(AqMyFilter\*(Aq,
\&      },
\&  };
.Ve
.PP
This will load all filters defined by the \f(CW\*(C`Data::Printer::Filter::MyFilter\*(C'\fR
module.
.PP
If there are more than one filter, use an array reference instead:
.PP
.Vb 1
\&  \-external => [ \*(AqMyFilter\*(Aq, \*(AqMyOtherFilter\*(Aq ]
.Ve
.PP
\&\fB\s-1IMPORTANT:\s0 \s-1THIS\s0 \s-1WAY\s0 \s-1OF\s0 \s-1LOADING\s0 \s-1EXTERNAL\s0 \s-1PLUGINS\s0 \s-1IS\s0 \s-1EXPERIMENTAL\s0 \s-1AND\s0
\&\s-1SUBJECT\s0 \s-1TO\s0 \s-1SUDDEN\s0 \s-1CHANGE\s0! \s-1IF\s0 \s-1YOU\s0 \s-1CARE\s0, \s-1AND/OR\s0 \s-1HAVE\s0 \s-1IDEAS\s0 \s-1ON\s0 A \s-1BETTER\s0 \s-1API\s0,
\&\s-1PLEASE\s0 \s-1LET\s0 \s-1US\s0 \s-1KNOW\s0\fR
.SH "HELPER FUNCTIONS"
.IX Header "HELPER FUNCTIONS"
.SS "filter \s-1TYPE\s0, sub { ... };"
.IX Subsection "filter TYPE, sub { ... };"
The \f(CW\*(C`filter\*(C'\fR function creates a new filter for \fI\s-1TYPE\s0\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 properties in effect (so you can inspect for certain
options, etc). The subroutine is expected to return a string
containing whatever it wants \f(CW\*(C`Data::Printer\*(C'\fR to display on screen.
.SS "p()"
.IX Subsection "p()"
This is the same as \f(CW\*(C`Data::Printer\*(C'\fR's p(), only you can't rename it.
You can use this to throw some data structures back at \f(CW\*(C`Data::Printer\*(C'\fR
and use the results in your own return string \- like when manipulating
hashes or arrays.
.SS "\fInewline()\fP"
.IX Subsection "newline()"
This helper returns a string using the linebreak as specified by the
caller's settings. For instance, it provides the proper indentation
level of spaces for you and considers the \f(CW\*(C`multiline\*(C'\fR option to
avoid line breakage.
.PP
In other words, if you do this:
.PP
.Vb 3
\&   filter ARRAY => {
\&       my ($ref, $p) = @_;
\&       my $string = "Hey!! I got this array:";
\&
\&       foreach my $val (@$ref) {
\&           $string .= newline . p($val);
\&       }
\&
\&       return $string;
\&   };
.Ve
.PP
\&... your \f(CW\*(C`p($val)\*(C'\fR returns will be properly indented, vertically aligned
to your level of the data structure, while simply using \*(L"\en\*(R" would just
make things messy if your structure has more than one level of depth.
.SS "\fIindent()\fP"
.IX Subsection "indent()"
.SS "\fIoutdent()\fP"
.IX Subsection "outdent()"
These two helpers let you increase/decrease the indentation level of
your data display, for \f(CW\*(C`newline()\*(C'\fR and nested \f(CW\*(C`p()\*(C'\fR calls inside your filters.
.PP
For example, the filter defined in the \f(CW\*(C`newline\*(C'\fR explanation above would
show the values on the same (vertically aligned) level as the \*(L"I got this array\*(R"
message. If you wanted your array to be one level further deep, you could use
this instead:
.PP
.Vb 3
\&  filter ARRAY => {
\&      my ($ref, $p) = @_;
\&      my $string = "Hey!! I got this array:";
\&
\&      indent;
\&      foreach my $val (@$ref) {
\&          $string .= newline . p($val);
\&      }
\&      outdent;
\&
\&      return $string;
\&  };
.Ve
.SH "COLORIZATION"
.IX Header "COLORIZATION"
You can use Term::ANSIColor's \f(CW\*(C`colored()\*(C'\fR' for string
colorization. Data::Printer will automatically enable/disable
colors for you.
.SH "EXISTING FILTERS"
.IX Header "EXISTING FILTERS"
This is meant to provide a complete list of standalone filters for
Data::Printer available on \s-1CPAN\s0. If you write one, please put it under
the \f(CW\*(C`Data::Printer::Filter::*\*(C'\fR namespace, and drop me a line so I can
add it to this list!
.SS "Databases"
.IX Subsection "Databases"
Data::Printer::Filter::DB provides filters for Database objects. So
far only \s-1DBI\s0 is covered, but more to come!
.SS "Dates & Times"
.IX Subsection "Dates & Times"
Data::Printer::Filter::DateTime pretty-prints several date
and time objects (not just DateTime) for you on the fly, including
duration/delta objects!
.SS "Digest"
.IX Subsection "Digest"
Data::Printer::Filter::Digest displays a string containing the
hash of the actual message digest instead of the object. Works on
\&\f(CW\*(C`Digest::MD5\*(C'\fR, \f(CW\*(C`Digest::SHA\*(C'\fR, any digest class that inherits from
\&\f(CW\*(C`Digest::base\*(C'\fR and some others that implement their own thing!
.SS "ClassicRegex"
.IX Subsection "ClassicRegex"
Data::Printer::Filter::ClassicRegex changes the way Data::Printer
dumps regular expressions, doing it the classic \f(CW\*(C`qr//\*(C'\fR way that got
popular in \f(CW\*(C`Data::Dumper\*(C'\fR.
.SS "\s-1URI\s0"
.IX Subsection "URI"
Data::Printer::Filter::URI pretty-prints \s-1URI\s0 objects, displaying
the \s-1URI\s0 as a string instead of dumping the object.
.SS "\s-1JSON\s0"
.IX Subsection "JSON"
Data::Printer::Filter::JSON lets you see your \s-1JSON\s0 structures
replacing boolean objects with simple \f(CW\*(C`true/false\*(C'\fR strings!
.SS "URIs"
.IX Subsection "URIs"
Data::Printer::Filter::URI filters through several \s-1URI\s0 manipulation
classes and displays the \s-1URI\s0 as a colored string. A very nice addition
by Stanislaw Pusep (\s-1SYP\s0).
.SH "USING MORE THAN ONE FILTER FOR THE SAME TYPE/CLASS"
.IX Header "USING MORE THAN ONE FILTER FOR THE SAME TYPE/CLASS"
As of version 0.13, standalone filters let you stack together
filters for the same type or class. Filters of the same type are
called in order, until one of them returns a string. This lets
you have several filters inspecting the same given value until
one of them decides to actually treat it somehow.
.PP
If your filter catched a value and you don't want to treat it,
simply return and the next filter will be called. If there are no
other filters for that particular class or type available, the
standard Data::Printer calls will be used.
.PP
For example:
.PP
.Vb 7
\&  filter SCALAR => sub {
\&      my ($ref, $properties) = @_;
\&      if ( Scalar::Util::looks_like_number $$ref ) {
\&          return sprintf "%.8d", $$ref;
\&      }
\&      return; # lets the other SCALAR filter have a go
\&  };
\&
\&  filter SCALAR => sub {
\&      my ($ref, $properties) = @_;
\&      return qq["$$ref"];
\&  };
.Ve
.PP
Note that this \*(L"filter stack\*(R" is not possible on inline filters, since
it's a hash and keys with the same name are overwritten. Instead, you
can pass them as an array reference:
.PP
.Vb 3
\&  use Data::Printer filters => {
\&      SCALAR => [ sub { ... }, sub { ... } ],
\&  };
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Data::Printer
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright 2011 Breno G. de Oliveira \f(CW\*(C`<garu at cpan.org>\*(C'\fR. All rights reserved.
.PP
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself. See perlartistic.