NAME

    result - simple and powerfull error handling support

SYNOPSIS

      use result qw(:ERR);
  
      ...
      sub mySub {
        ...
            return err 'some err message' if errorDetectedUsingAnyCustomWay();
            ... continue
            return 'the value that should be returned normal way';
      }
      ...
      my $ResultValue_or_ErrObject = mySub;
      doSomethingProbablyDie() if iserr $ResultValue_or_ErrObject;
  
    see also DEMO CODE which is the fully functional demo example.

DEMO CODE

      use result qw(:ERR);

      sub mySub1 { 
  
        my $param = shift;

            unless( defined( $param ))
        { return err errAsSimpleMsg => 'undefined parameter' }
        
            if( ref( $param ))
            { return err errAsFormatMsg => ['parameter is "%s" reference', ref($param) ] }

            if( $param eq 'force-err' )
            { return err 'As Standalone Key or Message' }
        
            return $param;
        
      }
  
      sub mySub2_chain_test {
        my $rv = mySub1();
            if( iserr($rv) )
            {
              return $rv->errChain( errBubbled => 'use dump to see error history' ) ;
            }
            else
            {
              return 'ok, no chained errors';
            }
      }
  
      my $val;

      $val = mySub1(); 
      if( iserr( $val )) { PrintErrReport( $val ) }
      else               { PrintOkReport( $val ) }
  
      $val = mySub1( ['force-err'] );
      if( iserr( $val )) { PrintErrReport( $val ) }
      else               { PrintOkReport( $val ) }

      $val = mySub1( 'force-err' );
      if( iserr( $val )) { PrintErrReport( $val ) }
      else               { PrintOkReport( $val ) }

      $val = mySub1( 'ok value' );
      if( iserr( $val )) { PrintErrReport( $val ) }
      else               { PrintOkReport( $val ) }

      $val = mySub2_chain_test();
      if( iserr( $val )) { PrintErrReport( $val ) }
      else               { PrintOkReport( $val ) }

      sub PrintErrReport {
            my $val = shift;
            print join( "\n", '---', $val->msg, $val->dump, '' );
      }
        
      sub PrintOkReport {
            my $val = shift;
            print "\n---\n non-err-result: ", $val, "\n";
      }
  
DESCRIPTION

  EXPORT

    by default : none

    by tag ':ERR' : err, iserr

    by tag ':ALL' : err, iserr

METHODS

    err (class method, exported)
          $ResultValue_or_ErrObject = result::err( errKey [ => \@errParameters ] )

        Returns the detectable error blessed object. See SYNOPSIS.

    errChain (object method)
          $ResultValue_or_ErrObject = $ResultValue_or_ErrObject->errChain( errKey => \@errParameters )

        Adds chain item to the detectable error object. Used to add higher
        level err messagess, while the ErrorObject bubbles backwards the
        calls until catched and processed.

        It could be understand as error history or as err stack.

    iserr (class method, exported)
          $bool = result::iserr( $ResultValue_or_ErrObject )

        Returns true if the $ResultValue_or_ErrObject contains ErrorObject.
        See SYNOPSIS.

    msg (object method)
          $string = $ResultValue_or_ErrObject->msg

        Returns the string value of contained ErrorMessage. See SYNOPSIS.

    dump (object method)
          $string = $ResultValue_or_ErrObject->dump

        Dumps the whole object using Data::Dump. See SYNOPSIS. Intended for
        further diagnostical use with bubbling/stacking errors.

FILES

    none

REVISION

     project started: 2003/12/08

     $Id: result.pm_rev 1.15 2003/12/12 08:49:18 root Exp $

AUTHOR

     Daniel Peder

     <Daniel.Peder@Infoset.COM>
     http://www.infoset.com

     Czech Republic national flag: 
     LeftSideBlueTriangleRightSideHorizontalSplitTopWhiteBottomRed

SEE ALSO

    Class::ReturnValue