NAME

FP::Show - give (nice) code representation for debugging purposes

SYNOPSIS

use FP::Show; # exports 'show'
use FP::List;

sub foo {
    my ($l)=@_;
    die "not what we wanted: ".show ($l)
      unless ref ($l) eq "ARRAY";
}

foo list 100-1, "bottles";
  # -> dies with: not what we wanted: list(99, 'bottles')
foo "list(99, 'bottles')" ;
  # -> dies with: not what we wanted: 'list(99, \'bottles\')'

DESCRIPTION

Unlike Data::Dumper, this allows classes to provide a 'FP_Show_show' method that gets a function it can itself recursively call on contained values, and that must return the string representation.

Data::Dumper *does* have a similar feature, $Data::Dumper::Freezer, but it needs the object to be mutated, which is not what one will want.

Why not use string overloading instead? Because '""' overloading is returning 'plain' strings, not perl code (or so it seems, is there any spec that defines exactly what it means?) Code couldn't know whether to quote the result:

sub foo2 {
    my ($l)=@_;
    die "not what we wanted: $l"
      unless ref ($l) eq "ARRAY";
}

foo2 list 100-1, "bottles";
  # would die with: not what we wanted: list(99, 'bottles')
foo2 "list(99, 'bottles')" ;
  # would die with: not what we wanted: list(99, 'bottles')
# so how would you tell which value foo2 really got in each case,
# just from looking at the message?

# also:
foo2 +{a=> 1, b=>10};
  # would die with something like:
  #   not what we wanted: HASH(0xEADBEEF)
  # which isn't very informative

Embedding pointer values in the output also means that it can't be used for automatic testing. (Even with a future implementation of cut-offs, values returned by `show` will be good enough when what one needs to do is compare against a short representation. Also, likely we would implement the cut-off value as an optional parameter.)

TODO

- cycle detection

- cut-offs at configurable size?

- modify Data::Dumper to allow for custom formatting instead?

- should the 'FP_Show_show' methods simply be called 'show'? Or '(show' and provide help for their installation like overload.pm? Although, there is a reason not to do that: the `show` method would not be usable directly, as it follows a private API.

Offer a mix-in that *does* offer a `show` method that works without
giving further arguments?  But then, like with equals, it's not safe
in the general case where the object argument might not be an object
or have the method. Users should really import and use the show and
equals functions.

- should `show` try to never use multiple lines, or to do pretty-printing?

- should constructor names be fully qualified? Any other idea to avoid this verbosity but still be unambiguous?

- make it good enough to be used by Chj::repl by default for the printing.

SEE ALSO

FP::Equals