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