NAME

    result - simple but powerfull error handling support

SYNOPSIS

      use result;

      # use result qw( messages=/etc/messages ); # intended to use i18l messages addressed by errKey ...
  
      sub mySub1 { 
  
        my $param = shift;

            unless( defined( $param ))
        { return result::err( errAsSimpleMsg => 'undefined parameter' ) }
        
            if( ref( $param ))
            { return result::err( errAsFormatMsg => ['parameter as reference "%s"', ref($param) ] ) }
        
            return $param;
        
      }
  
      sub mySub2_chain_test {
        my $rv = mySub1();
            if( result::iserr($rv) )
            {
              return $rv->errChain( errBubbled => 'use dump to see error history' ) ;
            }
            else
            {
              return 'ok, no chained errors';
            }
      }
  
      my $val;

      $val = mySub1(); 
      if( result::iserr( $val )) { PrintErrReport( $val ) }
      else                       { PrintOkReport( $val ) }
  
      $val = mySub1( [1] );
      if( result::iserr( $val )) { PrintErrReport( $val ) }
      else                       { PrintOkReport( $val ) }

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

      $val = mySub2_chain_test();
      if( result::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

    nothing

METHODS

    err (class method)
          $ResultValue_or_ErrObject = result::err( errKey => \@errParameters )

        Returns the detectable error 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)
          $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

        Denerates complete dump using Data::Dump. See SYNOPSIS. Intended for
        further diagnostical use by bubbling/stacking errors.

FILES

    none

REVISION

     project started: 2003/05/09

     $Id: result.pm_rev 1.7 2003/12/08 16:27:33 root Exp root $

AUTHOR

     Daniel Peder

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

     Czech Republic national flag: 
     LeftSideBlueTriangleRightSideHorizontalSplitTopWhiteBottomRed

SEE ALSO

    Class::ReturnValue