NAME

       Test::NiceDump - let's have a nice and human readable dump of our objects!

VERSION

       version 1.0.1

SYNOPSIS

           use Test::Deep;
           use Test::NiceDump 'nice_explain';

           cmp_deeply($got,$expected,'it works')
               or nice_explain($got,$expected);

DESCRIPTION

       This module uses "Data::Dump::Filtered" and a set of sensible filters to dump test data in a more
       readable way.

       For example, "DateTime" objects get printed in the full ISO 8601 format, and "DBIx::Class::Row" objects
       get printed as hashes of their inflated columns.

FUNCTIONS

   "nice_dump"
           my $dumped_string = nice_dump $data;

       Serialise $data in a nice, readable way.

   "nice_explain"
           nice_explain $data;
           nice_explain $data, $comparator;

       Calls ""nice_dump"" on $data and $comparator (if provided), and uses "diag" to provide test failure
       feedback with the dumped strings.

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:

       nothing at all
           to signal that it won't handle this particular value

       any single value
           which will be dumped instead

       Let's  say  you  have  a class "My::Class", 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  "as_data_for_log"  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:

           use Safe::Isa;

           Test::NiceDump::add_filter(
               my_filter => sub {
                   $_[0]->$_isa('My::Class')
                       ? $_[0]->as_data_for_log
                       : ();
               },
           );

       or, if you want to do the same for any object with that method:

           use Safe::Isa;

           Test::NiceDump::add_filter(
               my_filter => sub { $_[0]->$_call_if_can('as_data_for_log') },
           );

   "add_filter"
         Test::NiceDump::add_filter($name => $code);

       Adds a new filter. Adding a filter with an existing name overrides it.

       Filters  are  invoked  in  "cmp"  order  of   name.   The   names   of   all   built-in   filters   match
       "/^Test::NiceDump::/".

       Try to be specific with your checks, to avoid surprises due to the interaction of different filters.

       Your filter must return nothing at all if it didn't handle the value. Failure to do so will probably lead
       to infinite recursion.

   "remove_filter"
         Test::NiceDump::remove_filter($name);

       Removes the filter with the given name. Nothing happens if such a filter does not exist.

AUTHOR

       Gianni Ceccarelli <gianni.ceccarelli@broadbean.com>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2019 by BroadBean UK, a CareerBuilder Company.

       This  is  free  software;  you  can  redistribute  it and/or modify it under the same terms as the Perl 5
       programming language system itself.

perl v5.36.0                                       2022-10-14                                Test::NiceDump(3pm)