/src/lib/perl5/ORAC/Error.pm
Perl | 292 lines | 219 code | 62 blank | 11 comment | 3 complexity | 8ca6f1b2bb3d848c9955b8a31b46a051 MD5 | raw file
- # ORAC::Error --------------------------------------------------------------
- package ORAC::Error;
- =head1 NAME
- ORAC::Error - Exception handling in an object orientated manner.
- =head1 SYNOPSIS
- use ORAC::Error qw /:try/;
- use ORAC::Constants qw /:status/;
- # throw an error to be caught
- throw ORAC::Error::UserAbort( $message, ORAC__ABORT );
- throw ORAC::Error::FatalError( $message, ORAC__FATAL );
- # record and then retrieve an error
- do_stuff();
- my $Error = ORAC::Error->prior;
- ORAC::Error->flush if defined $Error;
- sub do_stuff {
- record ORAC::Error::FatalError( $message, ORAC__FATAL);
- }
- # try and catch blocks
- try {
- stuff();
- }
- catch ORAC::Error::UserAbort with
- {
- # normally we just want to catch and then ignore UserAborts
- my $Error = shift;
- orac_exit_normally();
- }
- catch ORAC::Error::FatalError with
- {
- # its a fatal error
- my $Error = shift;
- orac_exit_normally($Error);
- }
- otherwise
- {
- # this block catches croaks and other dies
- my $Error = shift;
- orac_exit_normally($Error);
- }; # Don't forget the trailing semi-colon to close the catch block
- =head1 DESCRIPTION
- C<ORAC::Error> is based on a modifed version of Graham Barr's C<Error>
- package, and more documentation about the (many) features present in
- the module but currently unused by ORAC-DR can be found in the
- documentation for that module.
- As with the C<Error> package, C<ORAC::Error> provides two interfaces.
- Firstly it provides a procedural interface to exception handling, and
- secondly C<ORAC::Error> is a base class for exceptions that can either
- be thrown, for subsequent catch, or can simply be recorded.
- If you wish to throw an C<FatalError> or C<UserAbort> then you should
- also C<use ORAC::Constants qw / :status /> so that the ORAC constants
- are available.
- =head1 PROCEDURAL INTERFACE
- C<ORAC::Error> exports subroutines to perform exception
- handling. These will be exported if the C<:try> tag is used in the
- C<use> line.
- =over 4
- =item try BLOCK CLAUSES
- C<try> is the main subroutine called by the user. All other
- subroutines exported are clauses to the try subroutine.
- The BLOCK will be evaluated and, if no error is throw, try will return
- the result of the block.
- C<CLAUSES> are the subroutines below, which describe what to do in the
- event of an error being thrown within BLOCK.
- =item catch CLASS with BLOCK
- This clauses will cause all errors that satisfy
- C<$err-E<gt>isa(CLASS)> to be caught and handled by evaluating
- C<BLOCK>.
- C<BLOCK> will be passed two arguments. The first will be the error
- being thrown. The second is a reference to a scalar variable. If this
- variable is set by the catch block then, on return from the catch
- block, try will continue processing as if the catch block was never
- found.
- To propagate the error the catch block may call C<$err-E<gt>throw>
- If the scalar reference by the second argument is not set, and the
- error is not thrown. Then the current try block will return with the
- result from the catch block.
- =item otherwise BLOCK
- Catch I<any> error by executing the code in C<BLOCK>
- When evaluated C<BLOCK> will be passed one argument, which will be the
- error being processed.
- Only one otherwise block may be specified per try block
- =back
- =head1 CLASS INTERFACE
- =head2 CONSTRUCTORS
- The C<ORAC::Error> object is implemented as a HASH. This HASH is
- initialized with the arguments that are passed to it's
- constructor. The elements that are used by, or are retrievable by the
- C<ORAC::Error> class are listed below, other classes may add to these.
- -file
- -line
- -text
- -value
- If C<-file> or C<-line> are not specified in the constructor arguments
- then these will be initialized with the file name and line number
- where the constructor was called from.
- The C<ORAC::Error> package remembers the last error created, and also
- the last error associated with a package.
- =over 4
- =item throw ( [ ARGS ] )
- Create a new C<ORAC::Error> object and throw an error, which will be
- caught by a surrounding C<try> block, if there is one. Otherwise it
- will cause the program to exit.
- C<throw> may also be called on an existing error to re-throw it.
- =item with ( [ ARGS ] )
- Create a new C<ORAC::Error> object and returns it. This is defined for
- syntactic sugar, eg
- die with ORAC::Error::FatalError ( $message, ORAC__FATAL );
- =item record ( [ ARGS ] )
- Create a new C<ORAC::Error> object and returns it. This is defined for
- syntactic sugar, eg
- record ORAC::Error::UserAbort ( $message, ORAC__ABORT )
- and return;
- =back
- =head2 METHODS
- =over 4
- =item prior ( [ PACKAGE ] )
- Return the last error created, or the last error associated with
- C<PACKAGE>
- my $Error = ORAC::Error->prior;
- =item flush ( [ PACKAGE ] )
- Flush the last error created, or the last error associated with
- C<PACKAGE>.It is necessary to clear the error stack before exiting the
- package or uncaught errors generated using C<record> will be reported.
- $Error->flush;
- =back
- =head2 OVERLOAD METHODS
- =over 4
- =item stringify
- A method that converts the object into a string. By default it returns
- the C<-text> argument that was passed to the constructor, appending
- the line and file where the exception was generated.
- =item value
- A method that will return a value that can be associated with the
- error. By default this method returns the C<-value> argument that was
- passed to the constructor.
- =back
- =head1 PRE-DEFINED ERROR CLASSES
- =over 4
- =item ORAC::Error::FatalError
- Used for fatal errors where we want the pipeline to die with cause.
- This class can be used to hold simple error strings and values. It's
- constructor takes two arguments. The first is a text value, the second
- is a numeric value, C<ORAC__FATAL>. These values are what will be
- returned by the overload methods.
- =item ORAC::Error::UserAbort
- Used for user generated pipeline aborts, which are handled slightly
- differently than fatal errors generated by the pipeline itself. The
- constructor for a C<UserAbort> is similar to that for a C<FatalError>
- except that the numeric value C<ORAC__ABORT> is passed.
- =item ORAC::Error::TermProcessing
- Terminate processing of this recipe but continue on as if everything
- is fine. This can be used to stop a recipe early but will not
- trigger any long term errors to propagate through the pipeline.
- =item ORAC::Error::TermProcessingErr
- As for TermProcessing except that whilst the pipeline will continue
- to run the exit status of the pipeline will be non-zero to indicate
- that a problem was found. This can be used when the pipeline can
- work around the problem but would like the final exit status to
- reflect that there is a problem to be investigated.
- =back
- =head1 KNOWN PROBLEMS
- C<ORAC::Error> which are thrown and not caught inside a C<try> block
- will in turn be caught by C<Tk::Error> if used inside a Tk
- environment, as will C<croak> and C<die>. However if is a C<croak> or
- C<die> is generated inside a try block and no C<otherwise> block
- exists to catch the exception it will be silently ignored until the
- application exits, when it will be reported.
- =head1 AUTHORS
- Tim Jenness E<lt>t.jenness@jach.hawaii.eduE<gt>,
- Alasdair Allan E<lt>aa@astro.ex.ac.ukE<gt>
- =head1 ACKNOWLEDGMENTS
- This class is a slightly modified, with the addition of the C<flush>
- method, version of Graham Barr's (gbarr@pobox.com) C<Error>
- class. That code was in turn based on code written by Peter Seibel
- (peter@weblogic.com) and Jesse Glick (jglick@sig.bsh.com).
- =cut
- use Error qw/ :try /;
- use warnings;
- use strict;
- use vars qw/$VERSION/;
- $VERSION = '1.0';
- # flush method added to the base class
- use base qw/ Error::Simple /;
- # ORAC::Error::UserAbort ---------------------------------------------------
- package ORAC::Error::UserAbort;
- use base qw/ ORAC::Error /;
- # ORAC::Error::FatalError --------------------------------------------------
- package ORAC::Error::FatalError;
- use base qw/ ORAC::Error /;
- package ORAC::Error::TermProcessing;
- use base qw/ ORAC::Error /;
- package ORAC::Error::TermProcessingErr;
- use base qw/ ORAC::Error::TermProcessing /;
- # --------------------------------------------------------------------------
- 1;