FP::Failure - failure values
use FP::Equal ':all'; use FP::Ops qw(the_method regex_substitute); use FP::List; use FP::Failure; is_equal \@FP::Failure::EXPORT, [qw(failure is_failure)]; # but there is more in EXPORT_OK... use FP::Failure '*trace_failures'; my $vals= do { local $trace_failures = 0; list(failure("not good"), failure(666), failure(undef), 666, 0, undef) }; is_equal $vals->map(*is_failure), list(1, 1, 1, undef, undef, undef); is_equal $vals->map(sub { my ($v)= @_; $v ? "t" : "f" }), list("f", "f", "f", "t", "f", "f"); # failure dies when called in void context (for safety, failures have # to be ignored *explicitly*): is((eval { failure("hello"); 1 } || ref $@), 'FP::Failure::Failure'); # get the wrapped value is_equal $vals->filter(*is_failure)->map(the_method "value"), list("not good", 666, undef); # get a nice message is_equal $vals->first->message, "failure: 'not good'\n"; # record backtraces my $v= do { local $trace_failures = 1; failure(666, [$vals->first]) }; is_equal $v->message, "failure: 666\n because:\n failure: 'not good'\n"; # request recorded backtrace to be shown is_equal regex_substitute(sub { # cleaning up bt s/line \d+/line .../g; my $btlines=0; $_= join("\n", grep { not /^ \S/ or ++$btlines < 2 } split /\n/) }, $v->message(1)), join("\n", "failure: 666 at lib/FP/Failure.pm line ...", " (eval) at t/pod_snippets.t line ...", " because:", " failure: 'not good'"); # Wrapper that just returns 0 unless configured to create a failure # object: use FP::Failure qw(*use_failure fails); use FP::Show; is show(do { local $use_failure=0; fails("hi") }), 0; is show(do { local $use_failure=1; fails("hi") }), "Failure('hi', undef, undef)"; # Utility container for holding both a message and values: use FP::Failure qw(message messagefmt); is failure(message "Hi", "foo", 9)->message, "failure: Hi: 'foo', 9\n"; is failure(message "Hi")->message, "failure: Hi\n"; # messagefmt is currently still passing everything through FP::Show; # what should it do, implement another fmt character? is failure(messagefmt "Hi %s %d", "foo", 9)->message, "failure: Hi 'foo' 9\n";
Values meant to represent errors/failures and to be distinguishable from non-error values. They are overloaded to be false in boolean context (although doing a boolean test is not safe to distinguish from non-failure values, as obviously those include false as well), or checked via the `is_failure` function.
The `value` method delivers the first argument given to `failure`, `maybe_parents` the second, which is an array of the parents, meant for chaining failures (reasons why this failure happened). `message` produces a somewhat nice to read string, multi-line if parents are chained in.
Calling the constructor in void context throws the constructed failure value as an exception.
If the variable `$FP::Failure::trace_failures` is set to true (it can be imported mutably via '*trace_failures'; default: false), then a stack trace is collected with the failures and displayed with `message` (if a true value is passed to message ?). (XX: use `BACKTRACE=1` idea here, too? Implement the same in `Chj::Backtrace`, too, and FP::Repl::Trap if fitting?)
If the variable `$FP::Failure::use_failure` is set to true (it can be imported mutably via '*use_failures'; default: false), then the optionally exported wrapper function `fails` calls `failure` with its arguments, otherwise it returns `0` (fully compatible with standard Perl booleans, and a little bit faster).
Instead of using `FP::Failure::Failure` as base class, create a failure protocol (FP::Abstract::Failure) instead?
This is alpha software! Read the status section in the package README or on the website.
To install FunctionalPerl, copy and paste the appropriate command in to your terminal.
cpanm
cpanm FunctionalPerl
CPAN shell
perl -MCPAN -e shell install FunctionalPerl
For more information on module installation, please visit the detailed CPAN module installation guide.