NAME
    Error::Return - return(), skipping a scope

VERSION
    version 1.100850

SYNOPSIS
        use Error ':try';
        use Error::Return;

        sub doit {
            print " in doit, before try\n";
            try {
                print "  in try: start\n";
                RETURN 456;
                print "  in try: end\n";
            } catch Error with {
                my $E = shift;
                print "  caught error [$E]\n";
            };
            print " in doit, after try\n";
        }

        print "before doit\n";
        my $x = doit();
        print "doit() returned [$x]\n";
        print "after doit\n";

        # prints:
        #
        # before doit
        #  in doit, before try
        #   in try: start
        # doit() returned [456]
        # after doit

DESCRIPTION
    The Error module provides "try()", which takes a coderef using the "&"
    prototype so it looks more like a normal Perl block or like "map()" or
    "grep()". But the "block" is still just an anonymous subroutine, so
    using "return" within the sub won't do what you think it will do. For
    example:

        sub doit {
            print " in doit, before try\n";
            try {
                print "  in try: start\n";
                return 456;
                print "  in try: end\n";
            } catch Error with {
                my $E = shift;
                print "  caught error [$E]\n";
            };
            print " in doit, after try\n";
        }

        print "before doit\n";
        my $x = doit();
        print "doit() returned [$x]\n";
        print "after doit\n";

    The "return" in the "try" block (we call it a block, but it really
    isn't) looks like it should return from "doit()", but it doesn't - it
    just returns from the anonymous sub that was passed to "try()".
    Therefore, this program prints the following:

        before doit
         in doit, before try
          in try: start
         in doit, after try
        doit() returned [1]
        after doit

    So "in doit, after try" is still reached, and "doit()" returns 1 because
    of its last "print" statement.

    While that is the correct behaviour, it is unintuitive. This module
    provides a more powerful way of returning.

METHODS
  RETURN
    Like "return" except that it doesn't just return to its upper scope but
    smashes right through it to the next-higher scope. Actually, it skips
    two scopes, because it has to return from the "try()" subroutine as
    well. It does take care of the cleanup that "try()" would normally
    perform.

    See the synopsis as an example - this way, the "try" block will "do what
    you mean".

INSTALLATION
    See perlmodinstall for information and options on installing Perl
    modules.

BUGS AND LIMITATIONS
    No bugs have been reported.

    Please report any bugs or feature requests through the web interface at
    <http://rt.cpan.org/Public/Dist/Display.html?Name=Error-Return>.

AVAILABILITY
    The latest version of this module is available from the Comprehensive
    Perl Archive Network (CPAN). Visit <http://www.perl.com/CPAN/> to find a
    CPAN site near you, or see <http://search.cpan.org/dist/Error-Return/>.

    The development version lives at
    <http://github.com/hanekomu/Error-Return/>. Instead of sending patches,
    please fork this project using the standard git and github
    infrastructure.

AUTHOR
      Marcel Gruenauer <marcel@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2009 by Marcel Gruenauer.

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