NAME
Astro::FITS::CFITSIO::CheckStatus - automatically catch CFITSIO status errors
SYNOPSIS
use Astro::FITS::CFITSIO::CheckStatus;
# call Carp::croak upon error
tie my $status, 'Astro::FITS::CFITSIO::CheckStatus';
$fptr = Astro::FITS::CFITSIO::create_file( $file, $status );
# call user specified function upon error:
tie my $status, 'Astro::FITS::CFITSIO::CheckStatus', $mycroak;
$fptr = Astro::FITS::CFITSIO::create_file( $file, $status );
# call Log::Log4perl->logcroak;
$logger = Log::Log4perl::get_logger();
tie my $status, 'Astro::FITS::CFITSIO::CheckStatus', $logger;
$fptr = Astro::FITS::CFITSIO::create_file( $file, $status );DESCRIPTION
The CFITSIO library uses the concept of a status variable passed to each CFITSIO function call to return an error status. At present, the Astro::FITS::CFITSIO Perl interface mirrors the CFITSIO interfaces directly, and does not do anything special to handle error returns (e.g., by throwing an exception). It should be noted that CFITSIO routines will not perform their requested action if a non-zero status value is passed in, so as long as the same status variable is used throughout, CFITSIO routines won't do extra work after an error. However, this can lead to the situation where one does not know at which step the error occurred.
In order to immediately catch an error, the status error must be checked after each call to a CFITSIO routine. Littering one's code with status variable checks is ugly.
This module resolves the impasse by tieing the status variable to a class which will check the value every time it is set, and throw an exception (via Carp::croak) containing the CFITISO error message if the value is non-zero. The caller may provide an alternate means of throwing the exception, either by passing in a subroutine reference,
tie my $status, 'Astro::FITS::CFITSIO::CheckStatus',
sub { die "An awful thing happened: @_" };
$fptr = Astro::FITS::CFITSIO::create_file( $file, $status );or a reference to a Log::Log4perl::Logger object.
$logger = Log::Log4perl::get_logger();
tie my $status, 'Astro::FITS::CFITSIO::CheckStatus', $logger;
$fptr = Astro::FITS::CFITSIO::create_file( $file, $status );In the latter case, it will be equivalent to calling $logger->logcroak.
EXPORT
None by default.
AUTHOR
Diab Jerius, <djerius@cpan.org>
COPYRIGHT AND LICENSE
Copyright (C) 2004 by The Smithsonian Astrophysical Observatory.
This software is released under the GNU General Public License. You may find a copy at http://www.fsf.org/copyleft/gpl.html.