view release on metacpan or  search on metacpan

lib/Lexical/Failure.pm  view on Meta::CPAN

sub _uplevel_die {
    my $exception = @_ ? join(q{},@_)
                  : $@ ? qq{$@\t...propagated}
                  :      q{Died};

    die $exception if ref $exception;

    if (!ref $exception && substr($exception, -1) ne "\n") {
        my (undef, $file, $line) = caller(2);
        $exception .= " at $file line $line\n";
    }

    die $exception;
}

1; # Magic true value required at end of module

__END__

=head1 NAME

Lexical::Failure - User-selectable lexically-scoped failure signaling


=head1 VERSION

This document describes Lexical::Failure version 0.001001


=head1 SYNOPSIS

    package Your::Module;

    # Set up this module for lexical failure handling...
    use Lexical::Failure;

    # Each time module is imported, set up failure handler...
    sub import {
        my ($package, %named_arg) = @_;

        ON_FAILURE( $named_arg{'fail'} );
    }

    # Then, in the module's subs/methods, call fail() to fail...
    sub inverse_square {
        my ($n) = @_;

        if ($n == 0) {
            fail "Can't invert zero";
        }

        return 1/$n**2;
    }

    sub load_file {
        my ($filename) = @_;

        fail 'No such file: ', $filename
            if ! -r $filename;

        local (@ARGV, $/) = $filename;
        return readline;
    }



=head1 DESCRIPTION

This module sets up two new keywords: C<fail> and C<ON_FAILURE>,
with which you can quickly create modules whose failure signaling
is lexicially scoped, under the control of client code.

Normally, modules specify some fixed mechanism for error handling and
require client code to adapt to that policy. One module may signal
errors by returning C<undef>, or perhaps some special "error object".
Another may C<die> or C<croak> on failure. A third may set a flag
variable. A fourth may require the client code to set up a callback,
which is executed on failure.

If you are using all four modules, your own code now has to check for
failure in four different ways, depending on where the failing
component originated. If you would rather that I<all> components throw
exceptions, or all return C<undef>, you will probably have to write
wrappers around 3/4 of them, to convert from their "native" failure
mechanism to your preferred one.

Lexical::Failure offers an alternative: a simple mechanism with which
module authors can generically specify "fail here with this message"
(using the C<fail> keyword), but then allow each block of client
code to decide how that failure is reported to it within its own lexical
scope (using the C<ON_FAILURE> keyword).

Module authors can still provide a default failure signaling mechanism,
for when client code does not specify how errors are to be reported.
This is handy for ensuring backwards compatibility in existing modules
that are converted to this new failure signaling approach.


=head1 INTERFACE

=head2 Accessing the API

To install the new C<fail> and C<ON_FAILURE> keywords, simple
load the module:

    use Lexical::Failure;

=head3 Changing the names of the API keywords

To avoid name conflicts, you can change the name of either (or both) of
the keywords that the module sets up, by passing a named argument when
loading the module. The name of the argument should be the standard name
of the keyword you want to rename, and the value of the argument should
be a string containing the new name. For example:

    use Lexical::Failure (
        fail       => 'return_error',
        ON_FAILURE => 'set_error_handler',
    );

    sub import {