NAME
    Exception::Class::Sugar - Syntactic sugar for use with Exception::Class

SYNOPSIS
        use Exception::Class::Sugar;
    
        # simple usage of catch()
    
        eval { Exception::Class::Base->throw('error') };
        catch my $err and warn $err->error;
    
        # caught() is a synonym for catch()
    
        eval { Exception::Class::Base->throw('error') };
        if ( caught my $err ) {
            if    ($err->isa('this') { warn "this: $err->error" }
            elsif ($err->isa('that') { warn "that: $err->error" }
            else                     { $err->rethrow }
        }
    
        # use "try eval" to push exceptions onto a stack to catch later
    
        try eval { 
            Exception::Class::Base->throw('error') 
        } and do {
            # cleanup that might use "try/catch" again
        };
        catch my $err;
  
DESCRIPTION
    Exception::Class::Sugar provides syntactic sugar for use with
    Exception::Class using the familiar keywords "try" and "catch". Its
    primary objective is to allow users to avoid dealing directly with $@ by
    ensuring that any exceptions caught in an "eval" are captured as
    Exception::Class objects, whether they were thrown objects to begin with
    or whether the error resulted from "die". This means that users may
    immediately use "isa" and various Exception::Class methods to process
    the exception.

    In addition, this module provides for a method to push errors onto a
    hidden error stack immediately after an "eval" so that cleanup code or
    other error handling may also call "eval" without the original error in
    $@ being lost.

    Inspiration for this module is due in part to Dave Rolsky's article
    "Exception Handling in Perl With Exception::Class" in *The Perl Journal*
    (Rolsky 2004).

    The "try/catch" syntax used in this module does not use code reference
    prototypes the way the Error.pm module does, but simply provides some
    helpful functionality when used in combination with "eval". As a result,
    it avoids the complexity and dangers involving nested closures and
    memory leaks inherent in Error.pm (Perrin 2003).

    Rolsky (2004) notes that these memory leaks may not occur in recent
    versions of Perl, but the approach used in Exception::Class::Sugar
    should be safe for all versions of Perl as it leaves all code execution
    to the "eval" in the current scope, avoiding closures altogether.

USAGE
  "catch, caught"
        my $err = catch;
        catch my $err;
        caught my $err;

    Returns an "Exception::Class::Base" object (or an object which is a
    subclass of it) if an exception has been caught by "eval" or else
    returns "undef" if no error exists. The exception is either popped from
    a hidden error stack (see "try") or, if the stack is empty, taken from
    the current value of $@.

    If the exception is not an "Exception::Class::Base" object (or subclass
    object), an "Exception::Class::Base" object will be created using the
    string contents of the exception. This means that calls to "die" will be
    wrapped and may be treated as exception objects. Other objects caught
    will be stringfied and wrapped likewise. Such wrapping will likely
    result in confusing stack traces and the like, so any methods other than
    "error" used on "Exception::Class::Base" objects caught should be used
    with caution.

    "catch" is prototyped to take an optional scalar argument. When passed a
    scalar variable, "catch" will also set that variable to the same value
    returned. This allows for the "catch my $err" idiom without parentheses.

    "caught" is a synonym for "catch" for syntactic convenience.

  "try"
        try eval {
          #dangerous code
        };
        catch my $err;
 
    Pushes the current error ($@) onto a hidden error stack for later use by
    "catch". "try" uses a prototype that expects a single scalar so that it
    can be used with eval without parentheses. As "eval { BLOCK }" is an
    argument to try, it will be evaluated just prior to "try", ensuring that
    "try" captures the correct error status. "try" does not itself handle
    any errors -- it merely records the results of "eval". "try { BLOCK }"
    will be interpreted as passing a hash reference and will (probably) not
    compile.

    "try" ignores the actual value returned by "eval" and always returns 1
    -- as *trying* is always successful regardless of whether the "eval" is
    successful or not. This allows compound idioms like the following:

        try eval {
         # code
        } and do {
         # cleanup
        };
        catch my $err;
 
    "try" must always be properly bracketed with a matching "catch" or
    unexpected behavior may result when "catch" pops the error off of the
    stack. "try" executes right after its "eval", so inconsistent usage of
    "try" like the following will work as expected:

        try eval {
            eval { die "inner" };
            catch my $inner_err
            die "outer" if $inner_err;
        };
        catch my $outer_err;
        # handle $outer_err;
    
    However, the following code is a problem:

        # BAD EXAMPLE
        try eval {
            try eval { die "inner" };
            die $@ if $@;
        };
        catch my $outer_err;
        # handle $outer_err;
    
    This code will appear to run correctly, but "catch" gets the exception
    from the inner "try", not the outer one, and there will still be an
    exception on the error stack which will be caught by the next "catch" in
    the program, causing unexpected (and likely hard to track) behavior.

    In short, if you use "try", you must "catch". The problem code above
    should be rewritten as:

        try eval {
            try eval { die "inner" };
            catch my $inner_err;
            $inner_err->rethrow if $inner_err;
        };
        catch my $outer_err;
        # handle $outer_err;

REFERENCES
    1.  perrin. (2003), "Re: Re2: Learning how to use the Error module by
        example", (perlmonks.org), Available:
        <http://www.perlmonks.org/index.pl?node_id=278900> (Accessed
        September 8, 2004).

    2.  Rolsky, D. (2004), "Exception Handling in Perl with
        Exception::Class", *The Perl Journal*, vol. 8, no. 7, pp. 9-13

SEE ALSO
    - Exception::Class

    - Test::Exception

    - Error [but see (Perrin 2003) before using]

INSTALLATION
    To install this module, type the following:

       perl Build.PL
       ./Build
       ./Build test
       ./Build install

BUGS
    Though this is a simple module, this version is an alpha release and may
    contain bugs or have unexpected behaviors.

    Please report bugs using the CPAN Request Tracker at
    <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Exception-Class-Sugar>

AUTHOR
    David A. Golden (DAGOLDEN), dagolden@dagolden.com

    http://dagolden.com/

COPYRIGHT
    Copyright (c) 2004 by David A. Golden

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

    The full text of the license can be found in the LICENSE file included
    with this module.

