NAME
    returning - define subs that act like "return"

SYNOPSIS
            use Test::Simple tests => 1;
        
            use returning {
                    Yes   => 1,
                    No    => 0,
            };
        
            sub beats_sissors
            {
                    local $_ = shift;
                    No  if /paper/i;
                    Yes if /rock/i;
                    No  if /scissors/;
            }
        
            ok beats_scissors("rock");

DESCRIPTION
    The "returning" module allows you to define subs which act like
    "return". That is, they break out of their caller sub. In the SYNPOSIS
    example, the "/scissors/i" regexp is never even evaluated because the
    "Yes" statement breaks out of the the sub, returning "1". The
    "beats_scissors" function could have alternatively been written as:

            sub beats_sissors
            {
                    local $_ = shift;
                    return 0 if /paper/i;
                    return 1 if /rock/i;
                    return 0 if /scissors/;
            }

    "returning" may be especially useful for domain-specific languages.

  Usage
    There are three ways to define a returning sub using this module:

            use returning { subname => 'value' };

    This creates the sub in the caller's namespace called " subname " with
    an empty prototype. (So when calling the sub, you don't need to use
    parentheses; just like with constant subs, but without as much
    optimization.)

            use returning { subname => sub { ... } }

    This installs the provided sub into the caller's namespace. This allows
    you to define non-constant subs, including subs that take parameters and
    do interesting stuff with them.

            BEGIN {
                    sub subname { ... }
            };
            use returning 'subname'; # look, no hashref!

    This does not install any sub into the caller's namespace, but modifies
    an existing sub to act in a returning way. Note that because "use"
    operates at compile time, you need to take a lot of care to ensure that
    the sub has already been defined.

    These can be combined, a la...

            use constant ZeroButTrue => '0E0';
            use returning 'ZeroButTrue', {
                    Affirm   => !!1,
                    Deny     => !!0,
                    Mu       => sub { return; },
            }

  Implementation Notes
    My first stab at this used Devel::Declare, but I couldn't quite get it
    working, and nobody in "#devel-declare" seemed sure why it was not. It
    seems possible that the ability to do this lies slightly beyond what
    Devel::Declare is capable of.

    Instead Scope::Upper has been used to create wrappers which jump up one
    more subroutine than expected when they return. This means that some of
    the magic happens at run-time rather than compile-time, so it perhaps
    executes slightly slower, but probably compiled slightly faster.

    An advantage of Scope::Upper is that you can re-export your "returning"
    subs to other packages with no problem, and they'll continue to have
    their special behaviour with no extra effort.

    A feature I had been hoping to achieve with Devel::Declare would be for
    calling a sub with an ampersand ("&Affirm()") to act as a way of
    avoiding the magic behaviour. This has not been possible with
    Scope::Upper.

  Class Method
    "returning->setup_for($package, $subname)"
        Given the package name and subname of an *existing* sub, sets up the
        magic.

BUGS
    Please report any bugs to
    <http://rt.cpan.org/Dist/Display.html?Queue=returning>.

SEE ALSO
    "Scope::Upper" takes care of most of the black magic.

AUTHOR
    Toby Inkster <tobyink@cpan.org>.

CREDITS
    Thanks OSFAMERON, Matt S Trout (MSTROUT), and Ash Berlin (ASH), for
    helping me through some of the tricky bits.

COPYRIGHT AND LICENCE
    This software is copyright (c) 2012 by Toby Inkster.

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

DISCLAIMER OF WARRANTIES
    THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
    WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
    MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.