[gnuastro-commits] master e4c110d 082/125: ConvertType also prints to stdout

[Mohammad Akhlaghi]

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

    ConvertType also prints to stdout
    
    ConvertType was slightly modified so when the output filename is `stdout',
    it will print to the standard output. Also, the book was updated to fully
    describe the updated status including the format of plain text outputs.
---
 bin/convertt/convertt.c | 29 ++++++++-------
 bin/convertt/ui.c       | 50 +++++++++++++++----------
 doc/gnuastro.texi       | 97 +++++++++++++++++++++++++++++--------------------
 lib/checkset.c          |  5 +++
 4 files changed, 109 insertions(+), 72 deletions(-)

diff --git a/bin/convertt/convertt.c b/bin/convertt/convertt.c
index 007e7c0..cfacc79 100644
--- a/bin/convertt/convertt.c
+++ b/bin/convertt/convertt.c
@@ -173,24 +173,27 @@ save_with_gnuastro_lib(struct converttparams *p)
 {
   gal_data_t *channel;
 
-  for(channel=p->chll; channel!=NULL; channel=channel->next)
-    switch(p->outformat)
-      {
+  /* Determine the type. */
+  switch(p->outformat)
+    {
 
-      case OUT_FORMAT_FITS:
+    /* FITS: a FITS file can have many extensions (channels). */
+    case OUT_FORMAT_FITS:
+      for(channel=p->chll; channel!=NULL; channel=channel->next)
         gal_fits_img_write(channel, p->cp.output, NULL, PROGRAM_STRING);
-        break;
-
+      break;
 
-      case OUT_FORMAT_TXT:
-        gal_txt_write(p->chll, NULL, p->cp.output, p->cp.dontdelete);
-        break;
+    /* Plain text: only one channel is acceptable. */
+    case OUT_FORMAT_TXT:
+      gal_txt_write(p->chll, NULL, p->cp.output, p->cp.dontdelete);
+      break;
 
 
-      default:
-        error(EXIT_FAILURE, 0, "a bug! output format code `%d' not "
-              "recognized in `save_with_gnuastro_lib'", p->outformat);
-      }
+    /* Not recognized. */
+    default:
+      error(EXIT_FAILURE, 0, "a bug! output format code `%d' not "
+            "recognized in `save_with_gnuastro_lib'", p->outformat);
+    }
 }
 
 
diff --git a/bin/convertt/ui.c b/bin/convertt/ui.c
index 249b202..c22613d 100644
--- a/bin/convertt/ui.c
+++ b/bin/convertt/ui.c
@@ -708,25 +708,36 @@ ui_set_output(struct converttparams *p)
     {
       p->outformat=OUT_FORMAT_TXT;
 
-      /* Plain text files don't have any unique set of suffixes. So, here,
-         we will just adopt two of the most common ones: `txt' or `dat'. If
-         the output is just one of these two suffixes, then we will use
-         automatic output to generate the full name, otherwise, we'll just
-         take the user's given value as the filename. */
-      if( !strcmp(cp->output, "txt") || !strcmp(cp->output, ".txt")
-          || !strcmp(cp->output, "dat") || !strcmp(cp->output, ".dat") )
-        ui_add_dot_use_automatic_output(p);
-
-      /* If output type is not an image, there should only be one color
-         channel: */
-      if(p->numch>1)
-        error(EXIT_FAILURE, 0, "text output (`--output=%s`) can only be "
-              "completed with one input color channel. You have given "
-              "%zu. Note that some formats (for example JPEG) can have "
-              "more than one color channel in each file. You can first "
-              "convert the file to FITS, then convert the desired "
-              "channel to text by specifying the HDU",
-              cp->output, p->numch);
+      /* If the given value is `stdout', then set p->cp.output to NULL, so
+         the result will be printed to the standard output. */
+      if( !strcmp(p->cp.output, "stdout") )
+        {
+          free(p->cp.output);
+          p->cp.output=NULL;
+        }
+      else
+        {
+          /* Plain text files don't have any unique set of suffixes. So,
+             here, we will just adopt two of the most common ones: `txt' or
+             `dat'. If the output is just one of these two suffixes, then
+             we will use automatic output to generate the full name,
+             otherwise, we'll just take the user's given value as the
+             filename. */
+          if( !strcmp(cp->output, "txt") || !strcmp(cp->output, ".txt")
+              || !strcmp(cp->output, "dat") || !strcmp(cp->output, ".dat") )
+            ui_add_dot_use_automatic_output(p);
+
+          /* If output type is not an image, there should only be one color
+             channel: */
+          if(p->numch>1)
+            error(EXIT_FAILURE, 0, "text output (`--output=%s`) can only be "
+                  "completed with one input color channel. You have given "
+                  "%zu. Note that some formats (for example JPEG) can have "
+                  "more than one color channel in each file. You can first "
+                  "convert the file to FITS, then convert the desired "
+                  "channel to text by specifying the HDU",
+                  cp->output, p->numch);
+        }
     }
 
   /* Check if the output already exists. */
@@ -853,6 +864,7 @@ ui_free_report(struct converttparams *p)
   /* Free the allocated spaces */
   gal_data_free(p->fluxlow);
   gal_data_free(p->fluxhigh);
+  if(p->cp.output) free(p->cp.output);
   gal_linkedlist_free_stll(p->hdus, 1);
   gal_linkedlist_free_stll(p->inputnames, 0);
 }
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index dc91c36..73e9568 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -342,7 +342,7 @@ Header
 
 ConvertType
 
-* Recognized file types::       Recognized file types
+* Recognized file formats::     Recognized file formats
 * Color::                       Some explanations on color.
 * Invoking astconvertt::        Options and arguments to ConvertType.
 
@@ -367,8 +367,8 @@ ImageCrop
 
 Invoking ImageCrop
 
-* ImageCrop options::          A list of all the options with explanation.
-* ImageCrop output::           The outputs of ImageCrop.
+* ImageCrop options::           A list of all the options with explanation.
+* ImageCrop output::            The outputs of ImageCrop.
 
 Arithmetic
 
@@ -6251,13 +6251,13 @@ files types will be given followed a short introduction 
to digital
 color.
 
 @menu
-* Recognized file types::       Recognized file types
+* Recognized file formats::     Recognized file formats
 * Color::                       Some explanations on color.
 * Invoking astconvertt::        Options and arguments to ConvertType.
 @end menu
 
address@hidden Recognized file types, Color, ConvertType, ConvertType
address@hidden Recognized file types
address@hidden Recognized file formats, Color, ConvertType, ConvertType
address@hidden Recognized file formats
 
 The various standards and the file name extensions recognized by
 ConvertType are listed below.
@@ -6378,28 +6378,49 @@ channel, that channel will not be used in the output.
 @item Plain text
 @cindex Plain text
 @cindex Suffixes, plain text
-Plain text files have the advantage that they can be viewed with any
-text editor or on the command-line. Most programs also support input
-as plain text files. In ConvertType, if the input arguments do not
-have any of the extensions listed above for other formats, the input
-is assumed to be a text file. Each plain text file is considered to
-contain one color channel. There is no standard output for plain text
-files.
-
address@hidden Mis-spelling file suffix
address@hidden File suffix mis-spelling
-If any of the extension above is mis-spelled, this will result in the
-output becoming a plain text file with that (short) name. If this
-happens, ConvertType will warn you and write the output as a plain
-text file. If you don't want that warning, set your plain text output
-file names longer than 5 characters. When converting an image to plain
-text, consider the fact that if the image is large the number of
-columns in each line will become very large, possibly making it very
-hard to open in some text editors.
+Plain text files have the advantage that they can be viewed with any text
+editor or on the command-line. Most programs also support input as plain
+text files. As input, each plain text file is considered to contain one
+color channel.
+
+In ConvertType, the recognized extensions for plain text files are
address@hidden and @file{.dat}. As described in @ref{Invoking astconvertt}, if
+you just give these extensions, (and not a full filename) as output, then
+automatic output will be preformed to determine the final output name (see
address@hidden output}). Besides these, when the format of a file cannot be
+recognized from its name, ConvertType will fall back to plain text mode. So
+you can use any name (even without an extension) for a plain text input or
+output. Just note that when the suffix is not recognized, automatic output
+will not be preformed.
+
+The basic input/output on plain text images is very similar to how tables
+are read/written as discribed in @ref{Gnuastro text table format}. Simply
+put, the restrictions are very loose, and there is a convention to define a
+name, units, data type (see @ref{Data types}), and comments for the data in
+a commented line. The only difference is that as a table, a text file can
+contain many datasets (columns), but as a 2D image, it can only contain one
+dataset. As a result, only one information comment line is necessary for a
+2D image, and instead of the starting address@hidden Column N}' (@code{N} is 
the
+column number), the information line for a 2D image must start with
address@hidden Image 1}'. When ConvertType is asked to output to plain text 
file,
+this information comment line is written before the image pixel values.
+
+When converting an image to plain text, consider the fact that if the image
+is large, the number of columns in each line will become very large,
+possibly making it very hard to open in some text editors.
+
address@hidden Standard output (command-line)
+This is very similar to the plain text output, but instead of creating a
+file to keep the printed values, they are printed on the command line. This
+can be very useful when you want to redirect the results directly to
+another program in one command with no intermediate file. The only
+difference is that only the pixel values are printed (with no information
+comment line). To print to the standard output, set the output name to
address@hidden'.
 
 @end table
 
address@hidden Color, Invoking astconvertt, Recognized file types, ConvertType
address@hidden Color, Invoking astconvertt, Recognized file formats, ConvertType
 @subsection Color
 
 @cindex RGB
@@ -6499,7 +6520,7 @@ complete) file name given to the @option{--output} 
option, which can
 either be given on the command-line or in any of the configuration
 files (see @ref{Configuration files}). Note that if the output suffix
 is not recognized, it will default to plain text format, see
address@hidden file types}.
address@hidden file formats}.
 
 The order of multiple input files is important. After reading the
 input file(s) the number of color channels in all the inputs will be
@@ -6512,17 +6533,13 @@ green and blue color channels and if there are four 
color channels
 they are respectively considered to be cyan, magenta, yellow and
 black.
 
-The value to @option{--output} (or @option{-o}) can be either a full
-file name or just the suffix of the desired output format. In the
-former case, that same name will be used for the output. In the latter
-case, the name of the output file will be set based on the automatic
-output guidelines, see @ref{Automatic output}. Note that the suffix
-name can optionally start a @file{.} (dot), so for example
address@hidden and @option{--output=jpg} are equivalent. Be
-careful that if you want your output in plain text, you have to give
-the full file name. So if @option{-otxt} or @option{--output=.txt} are
-given, the output file will be named @file{txt} or @file{.txt} (the
-latter will be a hidden file!).
+The value to @option{--output} (or @option{-o}) can be either a full file
+name or just the suffix of the desired output format. In the former case,
+that same name will be used for the output. In the latter case, the name of
+the output file will be set based on the automatic output guidelines, see
address@hidden output}. Note that the suffix name can optionally start a
address@hidden (dot), so for example @option{--output=.jpg} and
address@hidden are equivalent. See @ref{Recognized file formats}
 
 Besides the common set of options explained in @ref{Common options},
 the options to ConvertType can be classified into input, output and
@@ -7222,8 +7239,8 @@ and classifies his catalog} for a tutorial on effectively 
using this
 feature.
 
 @menu
-* ImageCrop options::          A list of all the options with explanation.
-* ImageCrop output::           The outputs of ImageCrop.
+* ImageCrop options::           A list of all the options with explanation.
+* ImageCrop output::            The outputs of ImageCrop.
 @end menu
 
 @node ImageCrop options, ImageCrop output, Invoking astimgcrop, Invoking 
astimgcrop
@@ -7654,7 +7671,7 @@ you can see, very complicated procedures can be created 
without the need
 for parenthesis or worrying about precedence. Even functions which take an
 arbitrary number of arguments can be defined in this notation. This is a
 very powerfull notation and is used in languages like Postscript
address@hidden the EPS and PDF part of @ref{Recognized file types} for a
address@hidden the EPS and PDF part of @ref{Recognized file formats} for a
 little more on the Postscript language.}  (the programming language in
 Postscript and compiled into PDF files) uses this notation.
 
diff --git a/lib/checkset.c b/lib/checkset.c
index 78333ac..75367ae 100644
--- a/lib/checkset.c
+++ b/lib/checkset.c
@@ -249,6 +249,11 @@ gal_checkset_check_remove_file(char *filename, int 
dontdelete)
 {
   FILE *tmpfile;
 
+  /* If the filename is `NULL' everything is ok (it doesn't exist)! In some
+     cases, a NULL filename is interpretted to mean standard output. */
+  if(filename==NULL)
+    return;
+
   /* We want to make sure that we can open and write to this file. But
      the user might have asked to not delete the file, so the
      contents should not be changed. Therefore we have to open it with