NAME

Return::Deep - deeply returns through multiple layers at once, and special wantarray functions

SYNOPSIS

  use Return::Deep;

  sub a {
    b();
    # never goes here
  }

  sub b {
    my $wantarray = deep_wantarray(2);
        # got a true value, because of `@ret = a();`
    deep_ret(2, 'Hi', 42);
  }

  my @ret = a();
  # got ('Hi', 42) here

  my @outer_ret = ret_bound {
    my @regex_ret = ret_bound {
      my @inner_ret = ret_bound {
        my $wantarray = sym_wantarray('inner');
            # got a true value, because of
            #       `@inner_ret = ret_bound {...} 'inner';`
        if( .2 < rand ) {
            sym_ret('inner', 43); # @inner_ret got 43
        }
        elsif( .5 < rand ) {
            sym_ret('Error::SomeError', 45); # @regex_ret got 45
        }
        else {
            sym_ret('any', 43); # @outer_ret got 44
        }
      } 'inner'; # catch 'inner'
    } qr/^Error::/; # catch all symbols which begin with 'Error::' by regex
  }; # catch all symbols without a catch symbol

DESCRIPTION

Deeply returns through multiple layers at once.

EXPORT

deep_ret($depth, @return_value)

If $depth = 1, it performs like a normal return.

If $depth <= 0, it performs like a normal list.

If $depth > 1, it returns through many layers, including subs and eval blocks.

sym_ret($symbol, @return_value)

Return through many layers, until the $symbol is catched by a matched ret_bound.

ret_bound {CODE_BLOCK} $catch_symbol

ret_bound {CODE_BLOCK}

Catch matched sym_rets. Without the $catch_symbol, it will catch all the sym_ret.

$catch_symbol could be a string or a regular expression (qr/something/). If $catch_symbol is a string, it will catch sym_ret with an exactly match. If $catch_symbol is a regular expression, it will catch sym_ret with a regular expression test.

($catch_symbol with regular expresion is not supported before Perl 5.10)

$wantarray = deep_wantarray($depth)

Like builtin function wantarray, but at specified $depth.

$wantarray = sym_wantarray($symbol)

Like builtin function wantarray, but at certain ret_bound which catch the <$symbol>.

Tested on Perl version 5.30.2, 5.28.2, 5.26.3, 5.24.4, 5.22.4, 5.20.3, 5.18.4, 5.16.3, 5.14.4, 5.12.5, 5.10.1, 5.8.9.

SEE ALSO

This mod's github https://github.com/CindyLinz/Perl-Return-Deep. It's welcome to discuss with me when you encounter bugs, or if you think that some patterns are also useful but the mod didn't provide them yet.

AUTHOR

Cindy Wang (CindyLinz), <cindy@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2020 by Cindy Wang (CindyLinz)

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.30.1 or, at your option, any later version of Perl 5 you may have available.