[gnuastro-commits] master 928bf15: Arithmetic: New tofilefree operator and change in --dontdelete

[Mohammad Akhlaghi]

branch: master
commit 928bf15f62c4c1a521916b20945e02a7e8f6676d
Author: Mohammad Akhlaghi <address@hidden>
Commit: Mohammad Akhlaghi <address@hidden>

    Arithmetic: New tofilefree operator and change in --dontdelete
    
    Until now, as in all programs, when the `--dontdelete' option is called,
    Arithmetic would simply complain and abort if the file exists. But with
    this commit, only in Arithmetic, this option is interpretted as appending
    the output dataset to the existing file's extensions.
    
    Also, Arithmetic now has a new `tofilefree' operator that will free the
    popped operand from the stack (as opposed to `tofile' which will put it
    back ontop of the stack).
    
    These features were added following a discussion with Leindert Boogaard.
---
 NEWS                         | 11 ++++---
 bin/arithmetic/arithmetic.c  | 16 +++++++---
 bin/arithmetic/main.h        |  2 ++
 bin/arithmetic/ui.c          | 18 ++++++-----
 doc/announce-acknowledge.txt |  1 +
 doc/gnuastro.texi            | 73 +++++++++++++++++++++++++++++++-------------
 6 files changed, 84 insertions(+), 37 deletions(-)

diff --git a/NEWS b/NEWS
index 6bacbd9..b6c2caf 100644
--- a/NEWS
+++ b/NEWS
@@ -13,10 +13,10 @@ GNU Astronomy Utilities NEWS                          -*- 
outline -*-
      option's value).
 
   Arithmetic:
-   - The new `tofile-' operator will save the top operand into a file
-     without changing the state of the operand stack (popping the top
-     element). This can greatly help in debugging/understanding an
-     Arithmetic command, especially as it gets longer, or more complicated.
+   - The new `tofile-' and `tofilefree-' operators will save the top
+     operand into a file. They can be very handy in debugging/understanding
+     an Arithmetic command (especially as it gets complicated), or to
+     produce multiple files/extensions with a single call to Arithmetic.
    - Four new operators have beed added to allow coadding multiple datasets
      into one using sigma-clipping: `sigclip-number', `sigclip-mean',
      `sigclip-median', and `sigclip-std'. These are very useful when
@@ -71,6 +71,9 @@ GNU Astronomy Utilities NEWS                          -*- 
outline -*-
   Arithmetic:
    - `num' operator is renamed to `number'.
    - `numvalue' operator is renamed to `numbervalue'.
+   - `--dontdelete' will append the output to any existing file. Note that
+     this change is only in Arithmetic, other programs will still just
+     complain and abort.
 
   ConvertType:
    --forcemin & --forcemax: until now, `--flminbyte' and `--flmaxbyte' were
diff --git a/bin/arithmetic/arithmetic.c b/bin/arithmetic/arithmetic.c
index 986fda2..68e3912 100644
--- a/bin/arithmetic/arithmetic.c
+++ b/bin/arithmetic/arithmetic.c
@@ -846,11 +846,13 @@ arithmetic_collapse(struct arithmeticparams *p, char 
*token, int operator)
 
 
 void
-arithmetic_tofile(struct arithmeticparams *p, char *token)
+arithmetic_tofile(struct arithmeticparams *p, char *token, int freeflag)
 {
   /* Pop the top dataset. */
   gal_data_t *popped = operands_pop(p, token);
-  char *filename=&token[ OPERATOR_PREFIX_LENGTH_TOFILE ];
+  char *filename = &token[ freeflag
+                           ? OPERATOR_PREFIX_LENGTH_TOFILEFREE
+                           : OPERATOR_PREFIX_LENGTH_TOFILE     ];
 
   /* Save it to a file. */
   popped->wcs=p->refdata.wcs;
@@ -864,7 +866,10 @@ arithmetic_tofile(struct arithmeticparams *p, char *token)
 
   /* Reset the WCS to NULL and put it back on the stack. */
   popped->wcs=NULL;
-  operands_add(p, NULL, popped);
+  if(freeflag)
+    gal_data_free(popped);
+  else
+    operands_add(p, NULL, popped);
 }
 
 
@@ -922,7 +927,10 @@ reversepolish(struct arithmeticparams *p)
          specified operation on them. */
       if( !strncmp(OPERATOR_PREFIX_TOFILE, token->v,
                    OPERATOR_PREFIX_LENGTH_TOFILE) )
-        arithmetic_tofile(p, token->v);
+        arithmetic_tofile(p, token->v, 0);
+      else if( !strncmp(OPERATOR_PREFIX_TOFILEFREE, token->v,
+                   OPERATOR_PREFIX_LENGTH_TOFILE) )
+        arithmetic_tofile(p, token->v, 1);
       else if( !strncmp(token->v, OPERATOR_PREFIX_SET,
                         OPERATOR_PREFIX_LENGTH_SET) )
         operands_set_name(p, token->v);
diff --git a/bin/arithmetic/main.h b/bin/arithmetic/main.h
index d6f6661..92c9e9f 100644
--- a/bin/arithmetic/main.h
+++ b/bin/arithmetic/main.h
@@ -42,8 +42,10 @@ along with Gnuastro. If not, see 
<http://www.gnu.org/licenses/>.
 #define NEG_DASH_REPLACE 11 /* Vertical tab (ASCII=11) for negative dash */
 #define OPERATOR_PREFIX_SET               "set-"
 #define OPERATOR_PREFIX_TOFILE            "tofile-"
+#define OPERATOR_PREFIX_TOFILEFREE        "tofilefree-"
 #define OPERATOR_PREFIX_LENGTH_SET        strlen(OPERATOR_PREFIX_SET)
 #define OPERATOR_PREFIX_LENGTH_TOFILE     strlen(OPERATOR_PREFIX_TOFILE)
+#define OPERATOR_PREFIX_LENGTH_TOFILEFREE strlen(OPERATOR_PREFIX_TOFILEFREE)
 
 
 
diff --git a/bin/arithmetic/ui.c b/bin/arithmetic/ui.c
index c4baea8..f08d5c1 100644
--- a/bin/arithmetic/ui.c
+++ b/bin/arithmetic/ui.c
@@ -255,6 +255,7 @@ ui_check_options_and_arguments(struct arithmeticparams *p)
   int output_checked=0;
   gal_list_str_t *token, *hdu;
   size_t nummultiext=0, numhdus=0;
+  struct gal_options_common_params *cp=&p->cp;
 
   /* First, make sure that any tokens are actually given. */
   if(p->tokens==NULL)
@@ -271,6 +272,10 @@ ui_check_options_and_arguments(struct arithmeticparams *p)
      was done in `gal_options_read_config_set'. */
   gal_list_str_reverse(&p->tokens);
 
+  /* To allow adding extensions to existing files, let the `keep' flag be
+     the same as the `dontdelete'. */
+  cp->keep=cp->dontdelete;
+
   /* Set the output file name (if any is needed). Note that since the lists
      are already reversed, the first FITS file encountered, is the first
      FITS file given by the user. Also, note that these file name
@@ -285,7 +290,7 @@ ui_check_options_and_arguments(struct arithmeticparams *p)
 
         {
           /* This token is a file, count how many mult-extension files we
-             haev and use the first to set the output filename (if it has
+             have and use the first to set the output filename (if it has
              not been set). */
           if( gal_array_name_recognized(token->v) )
             {
@@ -299,12 +304,11 @@ ui_check_options_and_arguments(struct arithmeticparams *p)
               /* If the output filename isn't set yet, then set it. */
               if(output_checked==0)
                 {
-                  if(p->cp.output)
-                    gal_checkset_writable_remove(p->cp.output, 0,
-                                                 p->cp.dontdelete);
+                  if(cp->output)
+                    gal_checkset_writable_remove(cp->output, cp->keep,
+                                                 cp->dontdelete);
                   else
-                    p->cp.output=gal_checkset_automatic_output(&p->cp,
-                                                               token->v,
+                    p->cp.output=gal_checkset_automatic_output(cp, token->v,
                                                                "_arith.fits");
                   output_checked=1;
                 }
@@ -321,7 +325,7 @@ ui_check_options_and_arguments(struct arithmeticparams *p)
       else
         {
           filename=&token->v[ OPERATOR_PREFIX_LENGTH_TOFILE ];
-          gal_checkset_writable_remove(filename, 0, p->cp.dontdelete);
+          gal_checkset_writable_remove(filename, cp->keep, cp->dontdelete);
         }
     }
 
diff --git a/doc/announce-acknowledge.txt b/doc/announce-acknowledge.txt
index e5c7f79..8e5463a 100644
--- a/doc/announce-acknowledge.txt
+++ b/doc/announce-acknowledge.txt
@@ -1,5 +1,6 @@
 Alphabetically ordered list to acknowledge in the next release.
 
+Leindert Boogaard
 Raúl Infante Sainz
 David Valls-Gabaud
 Ignacio Trujillo
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index d056a75..202384e 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -12770,12 +12770,13 @@ $ astarithmetic image.fits set-i   i i 5 gt nan where
 
 @item tofile-AAA
 Write the top oprand on the operands stack into a file called @code{AAA}
-(can be any FITS file name) without changing the operands stack (no operand
-will be operand).
+(can be any FITS file name) without changing the operands stack. If you
+don't need the dataset any more and would like to free it, see the
address@hidden operator below.
 
-Any file that is given to this operator is deleted before Arithmetic
-actually starts working on the input datasets. The deletion can be
-deactivated with the @option{--dontdelete} option (as in all Gnuastro
+By default, any file that is given to this operator is deleted before
+Arithmetic actually starts working on the input datasets. The deletion can
+be deactivated with the @option{--dontdelete} option (as in all Gnuastro
 programs, see @ref{Input output options}). If the same FITS file is given
 to this operator multiple times, it will contain multiple extensions (in
 the same order that it was called.
@@ -12787,6 +12788,11 @@ a string of operators and operands given to 
Arithmetic: simply put
 @command{tofile-AAA} anywhere in the process to see what is happening
 behind the scenes without modifying the overall process.
 
address@hidden tofilefree-AAA
+Similar to the @code{tofile} operator, with the only difference that the
+dataset that is written to a file is popped from the operand stack and
+freed from memory (cannot be used any more).
+
 @end table
 
 @cartouche
@@ -12857,24 +12863,28 @@ $ astarithmetic img1.fits img2.fits img3.fits median  
              \
                 -h0 -h1 -h2 --out=median.fits
 @end example
 
-The output is last remaining operand on the stack, see @ref{Reverse polish
-notation}. When its a single number, it will be printed on the
-command-line. When the output is an array, it will be stored as a file. The
-name of the file can be specified with the @option{--output} option, but if
-its not given, Arithmetic will use ``automatic output'' on the name of the
-first FITS image encountered to generate an output file name, see
address@hidden output}.
-
-By default, the world coordinate system (WCS) information will be taken
-from the first input image (that contains a WCS) on the command-line. This
-can be modified with the @option{--wcsfile} option described below.
-
 Arithmetic's notation for giving operands to operators is fully described
-in @ref{Reverse polish notation}. To ignore certain pixels, set them as
-blank, see @ref{Blank pixels}, for example with the @command{where}
-operator (see @ref{Arithmetic operators}). See @ref{Common options} for a
-review of the options in all Gnuastro programs. Arithmetic just redefines
-the @option{--hdu} option as explained below.
+in @ref{Reverse polish notation}. The output dataset is last remaining
+operand on the stack. When the output dataset a single number, it will be
+printed on the command-line. When the output is an array, it will be stored
+as a file.
+
+The name of the final file can be specified with the @option{--output}
+option, but if its not given, Arithmetic will use ``automatic output'' on
+the name of the first FITS image encountered to generate an output file
+name, see @ref{Automatic output}. By default, if the output file aready
+exists, it will be deleted before Arithmetic starts operation. However,
+this can be disabled with the @option{--dontdelete} option (see below). At
+any point during Arithmetic's operation, you can also write the top operand
+on the stack to a file, using the @code{tofile} or @code{tofilefree}
+operators, see @ref{Arithmetic operators}.
+
+By default, the world coordinate system (WCS) information of the output
+dataset will be taken from the first input image (that contains a WCS) on
+the command-line. This can be modified with the @option{--wcsfile} and
address@hidden options described below. When the @option{--quiet} option
+isn't given, the name and extension of the dataset used for the output's
+WCS is printed on the commandline.
 
 Through operators like those starting with @code{collapse-}, the
 dimensionality of the inputs may not be the same as the outputs. By
@@ -12884,6 +12894,10 @@ binary) can be set with the @option{--tableformat} 
option, see @ref{Input
 output options}). You can disable this feature (write 1D arrays as FITS
 images/arrays) with the @option{--onedasimage} option.
 
+See @ref{Common options} for a review of the options in all Gnuastro
+programs. Arithmetic just redefines the @option{--hdu} and
address@hidden options as explained below.
+
 @table @option
 
 @item -h INT/STR
@@ -12949,6 +12963,21 @@ HDU/extension to read the WCS within the file given to
 When final dataset to write as output only has one dimension, write it as a
 FITS image/array. By default, if the output is 1D, it will be written as a
 table, see above.
+
address@hidden -D
address@hidden --dontdelete
+Don't delete the output file, or files given to the @code{tofile} or
address@hidden operators, if they already exist. Instead append the
+desired datasets to the extensions that already exist in the respective
+file. Note it doesn't matter if the final output file name is given with
+the the @option{--output} option, or determined automatically.
+
+Arithmetic treats this option differently from its default operation in
+other Gnuastro programs (see @ref{Input output options}). If the output
+file exists, when other Gnuastro programs are called with
address@hidden, they simply complain and abort. But when Arithmetic
+is called with @option{--dontdelete}, it will appended the dataset(s) to
+the existing extension(s) in the file.
 @end table
 
 Arithmetic accepts two kinds of input: images and numbers. Images are