.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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" ''
.    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 "Test::NiceDump 3pm"
.TH Test::NiceDump 3pm "2019-12-27" "perl v5.30.0" "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"
Test::NiceDump \- let's have a nice and human readable dump of our objects!
.SH "VERSION"
.IX Header "VERSION"
version 1.0.1
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use Test::Deep;
\&    use Test::NiceDump \*(Aqnice_explain\*(Aq;
\&
\&    cmp_deeply($got,$expected,\*(Aqit works\*(Aq)
\&        or nice_explain($got,$expected);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module uses \f(CW\*(C`Data::Dump::Filtered\*(C'\fR and a set of sensible
filters to dump test data in a more readable way.
.PP
For example, \f(CW\*(C`DateTime\*(C'\fR objects get printed in the full \s-1ISO
8601\s0 format, and \f(CW\*(C`DBIx::Class::Row\*(C'\fR objects get printed as
hashes of their inflated columns.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.ie n .SS """nice_dump"""
.el .SS "\f(CWnice_dump\fP"
.IX Subsection "nice_dump"
.Vb 1
\&    my $dumped_string = nice_dump $data;
.Ve
.PP
Serialise \f(CW$data\fR in a nice, readable way.
.ie n .SS """nice_explain"""
.el .SS "\f(CWnice_explain\fP"
.IX Subsection "nice_explain"
.Vb 2
\&    nice_explain $data;
\&    nice_explain $data, $comparator;
.Ve
.PP
Calls "\f(CW\*(C`nice_dump\*(C'\fR" on \f(CW$data\fR and \f(CW$comparator\fR (if
provided), and uses \f(CW\*(C`diag\*(C'\fR to provide test
failure feedback with the dumped strings.
.SH "HOW TO ADD FILTERS"
.IX Header "HOW TO ADD FILTERS"
If the built-in filtering of input data is not enough for you, you can
add extra filters. A filter is a coderef that takes a single argument
(the value to be dumped), and returns either:
.IP "nothing at all" 4
.IX Item "nothing at all"
to signal that it won't handle this particular value
.IP "any single value" 4
.IX Item "any single value"
which will be dumped instead
.PP
Let's say you have a class \f(CW\*(C`My::Class\*(C'\fR, and you don't want its
instances to be dumped directly (maybe they contain cached data that's
not very useful to see). That class may have a \f(CW\*(C`as_data_for_log\*(C'\fR
method that returns only the important bits of data (as a hashref,
probably), so you want the return value of that method to be dumped
instead. You could say:
.PP
.Vb 1
\&    use Safe::Isa;
\&
\&    Test::NiceDump::add_filter(
\&        my_filter => sub {
\&            $_[0]\->$_isa(\*(AqMy::Class\*(Aq)
\&                ? $_[0]\->as_data_for_log
\&                : ();
\&        },
\&    );
.Ve
.PP
or, if you want to do the same for any object with that method:
.PP
.Vb 1
\&    use Safe::Isa;
\&
\&    Test::NiceDump::add_filter(
\&        my_filter => sub { $_[0]\->$_call_if_can(\*(Aqas_data_for_log\*(Aq) },
\&    );
.Ve
.ie n .SS """add_filter"""
.el .SS "\f(CWadd_filter\fP"
.IX Subsection "add_filter"
.Vb 1
\&  Test::NiceDump::add_filter($name => $code);
.Ve
.PP
Adds a new filter. Adding a filter with an existing name overrides it.
.PP
Filters are invoked in \f(CW\*(C`cmp\*(C'\fR order of name. The names of all built-in
filters match \f(CW\*(C`/^Test::NiceDump::/\*(C'\fR.
.PP
Try to be specific with your checks, to avoid surprises due to the
interaction of different filters.
.PP
Your filter \fImust\fR return nothing at all if it didn't handle the
value. Failure to do so will probably lead to infinite recursion.
.ie n .SS """remove_filter"""
.el .SS "\f(CWremove_filter\fP"
.IX Subsection "remove_filter"
.Vb 1
\&  Test::NiceDump::remove_filter($name);
.Ve
.PP
Removes the filter with the given name. Nothing happens if such a
filter does not exist.
.SH "AUTHOR"
.IX Header "AUTHOR"
Gianni Ceccarelli <gianni.ceccarelli@broadbean.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2019 by BroadBean \s-1UK,\s0 a CareerBuilder Company.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.