doy/try-tiny — pull request #20 by pilcrow (2014-06-29 18:45:50+00:00)
Title: try, try_again and $TRIES

This change implements, tests, and documents the optionally exported `try_again()` (restart the `try{}` without running `finally{}`) and `$TRIES` (how many times has this `try{}` block been invoked?).

## Use case
I often want to do simple retries of `try{} catch{} finally {}` stanzas, but need to keep track of the number of tries myself, and have to go through some contortions if I want `finally{}` clauses to run _only_ when I have given up trying. `Try::Tiny::Retry` is too much / too stilted for my simple uses, but I am lazy and tired of doing all that bookkeeping myself.

Now I can say:

use Try::Tiny qw(:DEFAULT try_again $TRIES);

try { ... }
catch { try_again if $TRIES < $my_patience; } # BTW, $TRIES is correct for nested uses, too!
finally { ... }

## Implementation
The main work of `try(&;@)` now contains a labelled block, and `try_again` simply does a `goto`. `catch` blocks are run from a special function so that `try_again` can look for that function in the call stack and not `goto` willy nilly. Finally, `finally` scope guards are created only after the first `try{}`.

`$TRIES` is a simple tied scalar that tracks the (localized) number of passes through the labelled block.

## Testing
Tests are added for proper symbol exporting, for misuse of `try_again`, and for retries of nested `try{}` stanzas.

Your existing test suite is excellent and unaltered, by the way.

## Documentation
POD is updated for new functionality, and a reference to `Try::Tiny::Retry` is added.