[gnuastro-commits] master 503ed91: Elaborated error messages for incorrect HDU

[Mohammad Akhlaghi]

branch: master
commit 503ed91b5b01671e7111f222dea8a7bd89d4be8f
Author: Mohammad Akhlaghi <address@hidden>
Commit: Mohammad Akhlaghi <address@hidden>

    Elaborated error messages for incorrect HDU
    
    When the input FITS file only has one extension (and the default value to
    `--hdu' is 1 to read the second extension) Gnuastro aborts with a
    program. But the default CFITSIO error can confuse the (especially early)
    users and isn't clear enough. So a much more elaborate error message is now
    printed in such cases. It explains the problem thoroughly (in a footnote)
    and also suggests the fix to the problem (when the input HDU was 1).
    
    Also, a more clear error message was prepared when the given HDU generally
    doesn't exist in the input FITS file. It now suggests using Gnuastro's Fits
    program to get a list of the HDUs.
    
    This issue was raised by Fernando Buitrago.
---
 THANKS                       |  1 +
 doc/announce-acknowledge.txt |  1 +
 doc/gnuastro.texi            | 16 +++++++--------
 lib/fits.c                   | 48 +++++++++++++++++++++++++++++++++++++++++++-
 4 files changed, 57 insertions(+), 9 deletions(-)

diff --git a/THANKS b/THANKS
index 4018892..0b5e215 100644
--- a/THANKS
+++ b/THANKS
@@ -19,6 +19,7 @@ support in Gnuastro. The list is ordered alphabetically (by 
family name).
     Karl Berry                           address@hidden
     Roland Bacon                         address@hidden
     Nicolas Bouché                       address@hidden
+    Fernando Buitrago                    address@hidden
     Adrian Bunk                          address@hidden
     Rosa Calvi                           address@hidden
     Antonio Diaz Diaz                    address@hidden
diff --git a/doc/announce-acknowledge.txt b/doc/announce-acknowledge.txt
index e6de1fa..20169f3 100644
--- a/doc/announce-acknowledge.txt
+++ b/doc/announce-acknowledge.txt
@@ -2,6 +2,7 @@ This file is meant to keep the names of the people who's help 
must be
 acknowledged in the next release.
 
 Marjan Akbari
+Fernando Buitrago
 Adrian Bunk
 Antonio Diaz Diaz
 Mosè Giordano
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 9819a15..ed164e7 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -1544,14 +1544,14 @@ management of its version controlled source server 
there.
 @c To the developers: please keep this in the same order as the THANKS file
 @c (alphabetical, except for the names in the paragraph above).
 We would also like to gratefully thank (in alphabetical order by family
-name) Marjan Akbari, Roland Bacon, Nicolas Bouch@'e, Adrian Bunk, Rosa
-Calvi, Antonio Diaz Diaz, Stephen Hamer, Raúl Infante Sainz, Lee Kelvin,
-Mohammad-Reza Khellat, Alan Lefor, Guillaume Mahler, Francesco Montanari,
-William Pence, Yahya Sefidbakht, Ole Streicher, Ignacio Trujillo, David
-Valls-Gabaud and Christopher Willmer for their useful and constructive
-comments and suggestions. Finally we should thank all the (sometimes
-anonymous) people in various online forums which patiently answered all our
-small (but important) technical questions.
+name) Marjan Akbari, Roland Bacon, Nicolas Bouch@'e, Fernando Buitrago,
+Adrian Bunk, Rosa Calvi, Antonio Diaz Diaz, Stephen Hamer, Raúl Infante
+Sainz, Lee Kelvin, Mohammad-Reza Khellat, Alan Lefor, Guillaume Mahler,
+Francesco Montanari, William Pence, Yahya Sefidbakht, Ole Streicher,
+Ignacio Trujillo, David Valls-Gabaud and Christopher Willmer for their
+useful and constructive comments and suggestions. Finally we should thank
+all the (sometimes anonymous) people in various online forums which
+patiently answered all our small (but important) technical questions.
 
 All work on Gnuastro has been voluntary, but the authors are most grateful
 to the following institutions (in chronological order) for hosting us in
diff --git a/lib/fits.c b/lib/fits.c
index 9350c2f..691fadb 100644
--- a/lib/fits.c
+++ b/lib/fits.c
@@ -675,7 +675,53 @@ gal_fits_hdu_open(char *filename, char *hdu, int iomode)
 
   /* Open the FITS file: */
   if( fits_open_file(&fptr, ffname, iomode, &status) )
-    gal_fits_io_error(status, "reading this FITS file");
+    {
+      switch(status)
+        {
+        /* Since the default HDU is `1', when the file only has one
+           extension, this error is common, so we will put a special
+           notice. */
+        case END_OF_FILE:
+          if( hdu[0]=='1' && hdu[1]=='\0' )
+            error(EXIT_FAILURE, 0, "%s has only one extension/HDU but you "
+                  "have asked for the second HDU (hdu number 1 in CFITSIO)."
+                  "\n\n"
+                  "To fix the problem please add `--hdu=0' (or `-h0') to "
+                  "your command when calling Gnuastro's programs. For "
+                  "library users, please give a value of \"0\" to the HDU "
+                  "argument.\n\n"
+                  "FOOTNOTE -- When writing a new FITS file, Gnuastro leaves "
+                  "the first HDU blank (with no data) and writes the "
+                  "outputs in the second HDU. In this way the keywords of "
+                  "the the first HDU can be used as meta data of the whole "
+                  "file (which may contain many extensions). This is the "
+                  "recommended way in the FITS standard. As a result, "
+                  "Gnuastro's default HDU to read an extension in a FITS "
+                  "file is the second. This error is commonly caused when "
+                  "the FITS file wasn't created according to this "
+                  "convention.", filename);
+          break;
+
+        /* Generic error below is fine for this case */
+        case BAD_HDU_NUM:
+          break;
+
+        /* In case an un-expected error occurs, use the general CFITSIO
+           reporting that we have already prepared. */
+        default:
+          gal_fits_io_error(status, "opening the given extension/HDU in "
+                            "the given file");
+        }
+
+      error(EXIT_FAILURE, 0, "%s: extension/HDU `%s' doesn't exist. Please "
+            "run the following command to see the extensions/HDUs in "
+            "`%s':\n\n"
+            "    $ astfits %s\n\n"
+            "The respective HDU number (or name, when present) may be used "
+            "with the `--hdu' option in Gnuastro's programs (or the `hdu' "
+            "argument in Gnuastro's libraries) to open the respective HDU.",
+            filename, hdu, filename, filename);
+    }
 
   /* Clean up and the pointer. */
   free(ffname);