[gnuastro-commits] master d7e893ae: Table: new options of --info-num-cols and --info-num-rows

[Mohammad Akhlaghi]

branch: master
commit d7e893aead47d7910966f8c502901fe6a8fb8270
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Table: new options of --info-num-cols and --info-num-rows
    
    Until now, there was no easy way for the user to easily print the number of
    rows or columns in a table. They would either have to read the FITS
    keywords (which would only work on FITS tables) or try parsing the output
    of '--information' (which would be buggy and non-trivial).
    
    With this commit, the two new options above have been added to Table to
    simplify extracting these two numbers (that are often necessary in
    scripts).
---
 NEWS              |  2 ++
 bin/table/args.h  | 28 +++++++++++++++++++++-
 bin/table/main.h  |  4 +++-
 bin/table/ui.c    | 71 ++++++++++++++++++++++++++++++++++++++++++-------------
 bin/table/ui.h    |  2 ++
 doc/gnuastro.texi | 53 +++++++++++++++++++++++++++++++----------
 6 files changed, 129 insertions(+), 31 deletions(-)

diff --git a/NEWS b/NEWS
index b4b2698b..dfff97c6 100644
--- a/NEWS
+++ b/NEWS
@@ -57,6 +57,8 @@ See the end of the file for license conditions.
     Mehnoor.
 
   Table:
+  --info-num-cols: print the number of the input table's columns and abort.
+  --info-num-rows: print the number of the input table's rows and abort.
   - '$_all' in column arithmetic: when an arithmetic expression contains
     this string, it will be repeated independently for all the columns of
     the input table.
diff --git a/bin/table/args.h b/bin/table/args.h
index 03150a60..1c8310f7 100644
--- a/bin/table/args.h
+++ b/bin/table/args.h
@@ -147,7 +147,7 @@ struct argp_option program_options[] =
       UI_KEY_INFORMATION,
       0,
       0,
-      "Only print table and column information.",
+      "Only print input table's information.",
       GAL_OPTIONS_GROUP_OUTPUT,
       &p->information,
       GAL_OPTIONS_NO_ARG_TYPE,
@@ -155,6 +155,32 @@ struct argp_option program_options[] =
       GAL_OPTIONS_NOT_MANDATORY,
       GAL_OPTIONS_NOT_SET
     },
+    {
+      "info-num-rows",
+      UI_KEY_INFONUMROWS,
+      0,
+      0,
+      "Only print input table's number of rows.",
+      GAL_OPTIONS_GROUP_OUTPUT,
+      &p->infonumrows,
+      GAL_OPTIONS_NO_ARG_TYPE,
+      GAL_OPTIONS_RANGE_0_OR_1,
+      GAL_OPTIONS_NOT_MANDATORY,
+      GAL_OPTIONS_NOT_SET
+    },
+    {
+      "info-num-cols",
+      UI_KEY_INFONUMCOLS,
+      0,
+      0,
+      "Only print input table's number of columns.",
+      GAL_OPTIONS_GROUP_OUTPUT,
+      &p->infonumcols,
+      GAL_OPTIONS_NO_ARG_TYPE,
+      GAL_OPTIONS_RANGE_0_OR_1,
+      GAL_OPTIONS_NOT_MANDATORY,
+      GAL_OPTIONS_NOT_SET
+    },
     {
       "colinfoinstdout",
       UI_KEY_COLINFOINSTDOUT,
diff --git a/bin/table/main.h b/bin/table/main.h
index 8567de01..6714c76d 100644
--- a/bin/table/main.h
+++ b/bin/table/main.h
@@ -98,7 +98,9 @@ struct tableparams
   char               *wcsfile;  /* File with WCS.                       */
   char                *wcshdu;  /* HDU in file with WCS.                */
   gal_list_str_t     *columns;  /* List of given columns.               */
-  uint8_t         information;  /* ==1: only print FITS information.    */
+  uint8_t         information;  /* ==1: only print input information.   */
+  uint8_t         infonumrows;  /* ==1: only print input's num rows.    */
+  uint8_t         infonumcols;  /* ==1: only print input's num columns. */
   uint8_t     colinfoinstdout;  /* ==1: print column metadata in CL.    */
   uint8_t            rowfirst;  /* Do row-based operations first.       */
   gal_data_t           *range;  /* Range to limit output.               */
diff --git a/bin/table/ui.c b/bin/table/ui.c
index 0dd58062..e6522d43 100644
--- a/bin/table/ui.c
+++ b/bin/table/ui.c
@@ -607,46 +607,85 @@ ui_colpack_free(struct column_pack *list)
 /**************************************************************/
 /***************       Preparations         *******************/
 /**************************************************************/
+  /* Read the table metadata to print information. */
+static gal_data_t *
+ui_info_read(struct tableparams *p, size_t *numcols, size_t *numrows,
+             int *tableformat)
+{
+  gal_data_t *allcols;
+  gal_list_str_t *lines;
+  lines=gal_options_check_stdin(p->filename, p->cp.stdintimeout, "input");
+  allcols=gal_table_info(p->filename, p->cp.hdu, lines, numcols,
+                         numrows, tableformat, "--hdu");
+  if(p->filename==NULL) p->filename="Standard-input";
+  gal_list_str_free(lines, 1);
+  return allcols;
+}
+
+
+
+
+
+/* Print full column and row information. */
 static void
 ui_print_info_exit(struct tableparams *p)
 {
   char *tmp;
   int tableformat;
   gal_data_t *allcols;
-  gal_list_str_t *lines;
   size_t numcols, numrows;
 
-  /* Read the table information for the number of columns and rows. */
-  lines=gal_options_check_stdin(p->filename, p->cp.stdintimeout, "input");
-  allcols=gal_table_info(p->filename, p->cp.hdu, lines, &numcols,
-                         &numrows, &tableformat, "--hdu");
-  if(p->filename==NULL) p->filename="Standard-input";
-  gal_list_str_free(lines, 1);
-
+  /* Read the input. */
+  allcols=ui_info_read(p, &numcols, &numrows, &tableformat);
 
   /* If there was no actual data in the file, then inform the user */
   if(allcols==NULL)
     error(EXIT_FAILURE, 0, "%s: no usable data rows", p->filename);
 
-
   /* Print the file information. */
   printf("--------\n");
   tmp=gal_fits_name_save_as_string(p->filename, p->cp.hdu);
   printf("%s\n", tmp);
   free(tmp);
 
-
   /* Print each column's information. */
   gal_table_print_info(allcols, numcols, numrows);
 
-
   /* Free the information from all the columns. */
   gal_data_array_free(allcols, numcols, 0);
 
+  /* Free the allocated spaces and exit. */
+  ui_free_report(p);
+  exit(EXIT_SUCCESS);
+}
+
+
+
+
+
+/* Print number of rows or columns */
+static void
+ui_print_info_nums_exit(struct tableparams *p)
+{
+  int tableformat;
+  gal_data_t *allcols;
+  size_t numcols, numrows;
+
+  /* Read the input metadata and free the column information (which is not
+     needed here: we just want the numbers). */
+  allcols=ui_info_read(p, &numcols, &numrows, &tableformat);
+  gal_data_array_free(allcols, numcols, 0);
+
+  /* Print the respective information. */
+  if(p->infonumcols) printf("%zu\n", numcols);
+  else if(p->infonumrows) printf("%zu\n", numrows);
+  else
+    error(EXIT_FAILURE, 0, "%s: a bug! Please contact us at '%s' to fix "
+          "the problem. This function should only be activated when "
+          "'--info-num-cols' or '--info-num-rows' are called", __func__,
+          PACKAGE_BUGREPORT);
 
-  /* Free the allocated spaces and exit. Otherwise, add the number of
-     columns to the list if the user wanted to print the columns
-     (didn't just want their information. */
+  /* Free the allocated spaces and exit. */
   ui_free_report(p);
   exit(EXIT_SUCCESS);
 }
@@ -1291,8 +1330,8 @@ ui_preparations(struct tableparams *p)
 
   /* If there were no columns specified or the user has asked for
      information on the columns, we want the full set of columns. */
-  if(p->information)
-    ui_print_info_exit(p);
+  if(p->information)                   ui_print_info_exit(p);
+  if(p->infonumcols || p->infonumrows) ui_print_info_nums_exit(p);
 
 
   /* If the input is from stdin, save it as 'lines'. */
diff --git a/bin/table/ui.h b/bin/table/ui.h
index 445b1a07..f9ce944b 100644
--- a/bin/table/ui.h
+++ b/bin/table/ui.h
@@ -88,6 +88,8 @@ enum option_keys_enum
   UI_KEY_TRANSPOSE,
   UI_KEY_OUTPOLYGON,
   UI_KEY_FROMVECTOR,
+  UI_KEY_INFONUMROWS,
+  UI_KEY_INFONUMCOLS,
   UI_KEY_CATCOLUMNRAWNAME,
 };
 
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index a60a98ff..1b842311 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -16108,11 +16108,32 @@ At the end of this section, there is an example of 
doing this.
 @end cartouche
 
 @table @asis
-@item Column information (@option{--information} or @option{-i})
-When given this option, the column data are not read at all.
-Table simply reads the column metadata (name, units, numeric data type and 
comments), and the number of rows and prints them.
+@item Input table information
+The first set of operations that will be preformed (if requested) are the 
printing of the input table information.
+Therefore, when the following options are called, the column data are not read 
at all.
+Table simply reads the main input's column metadata (name, units, numeric data 
type and comments), and the number of rows and prints them.
 Table then terminates and no other operation is done.
-This can therefore be called at the end of an arbitrarily long Table command 
only to remember the column metadata, then deleted to continue writing the 
command (using the shell's history to retrieve the previous command with an 
up-arrow key).
+These can therefore be called at the end of an arbitrarily long Table command.
+When you have forgot some information about the input table.
+You can then delete these options and continue writing the command (using the 
shell's history to retrieve the previous command with an up-arrow key).
+
+At any time only a single one of the options in this category may be called.
+The order of checking for these options is therefore important: in the same 
order that they are described below:
+
+@table @asis
+@item Column and row information (@option{--information} or @option{-i})
+Print the list of input columns and the metadata of each column in a single 
row.
+This includes the column name, numeric data type, units and comments of each 
column within a separate row of the output.
+Finally, print the number of rows.
+
+@item Number of columns (@option{--info-num-cols})
+Print the number of columns in the input table.
+Only a single integer (number of columns) is printed before Table terminates.
+
+@item Number of rows (@option{--info-num-rows})
+Print the number of rows in the input table.
+Only a single integer (number of rows) is printed before Table terminates.
+@end table
 
 @item Column selection (@option{--column})
 When this option is given, only the columns given to this option (from the 
main input) will be used for all future steps.
@@ -16298,34 +16319,34 @@ One line examples:
 
 @example
 ## Get the table column information (name, data type, or units):
-$ asttable bintab.fits --information
+$ asttable table.fits --information
 
 ## Print columns named RA and DEC, followed by all the columns where
 ## the name starts with "MAG_":
-$ asttable bintab.fits --column=RA --column=DEC --column=/^MAG_/
+$ asttable table.fits --column=RA --column=DEC --column=/^MAG_/
 
 ## Similar to the above, but with one call to `--column' (or `-c'),
 ## also sort the rows by the input's photometric redshift (`Z_PHOT')
 ## column. To confirm the sort, you can add `Z_PHOT' to the columns
 ## to print.
-$ asttable bintab.fits -cRA,DEC,/^MAG_/ --sort=Z_PHOT
+$ asttable table.fits -cRA,DEC,/^MAG_/ --sort=Z_PHOT
 
 ## Similar to the above, but only print rows that have a photometric
 ## redshift between 2 and 3.
-$ asttable bintab.fits -cRA,DEC,/^MAG_/ --range=Z_PHOT,2:3
+$ asttable table.fits -cRA,DEC,/^MAG_/ --range=Z_PHOT,2:3
 
 ## Only print rows with a value in the 10th column above 100000:
-$ asttable bintab.fits --range=10,10e5,inf
+$ asttable table.txt --range=10,10e5,inf
 
 ## Only print the 2nd column, and the third column multiplied by 5,
 ## Save the resulting two columns in `table.txt'
-$ asttable bintab.fits -c2,'arith $2 5 x' -otable.fits
+$ asttable table.fits -c2,'arith $2 5 x' -otable.fits
 
 ## Sort the output columns by the third column, save output:
-$ asttable bintab.fits --sort=3 -ooutput.txt
+$ asttable table.fits --sort=3 -ooutput.txt
 
-## Subtract the first column from the second in `cat.fits' (can also
-## be a text table) and keep the third and fourth columns.
+## Subtract the first column from the second in `cat.txt' (can also
+## be a FITS table) and keep the third and fourth columns.
 $ asttable cat.txt -c'arith $2 $1 -',3,4 -ocat.fits
 
 ## Convert sexagesimal coordinates to degrees (same can be done in a
@@ -16392,6 +16413,12 @@ This can be useful if you forget the identifier of a 
column after you have alrea
 You can simply add a @option{-i} to your already-written command (without 
changing anything) and run Table, to see the whole list of column names and 
information.
 Then you can use the shell history (with the up arrow key on the keyboard), 
and retrieve the last command with all the previously typed columns present, 
delete @option{-i} and add the identifier you had forgot.
 
+@item --info-num-cols
+Similar to @option{--information}, but only the number of the input table's 
columns will be printed as a single integer (useful in scripts for example).
+
+@item --info-num-rows
+Similar to @option{--information}, but only the number of the input table's 
rows will be printed as a single integer (useful in scripts for example).
+
 @cindex AWK
 @cindex GNU AWK
 @item -c STR/INT