1 /*********************************************************************
2 Function to parse options and configuration file values.
3 
4 Original author:
5      Mohammad Akhlaghi <mohammad@akhlaghi.org>
6 Contributing author(s):
7 Copyright (C) 2017-2021, Free Software Foundation, Inc.
8 
9 Gnuastro is free software: you can redistribute it and/or modify it
10 under the terms of the GNU General Public License as published by the
11 Free Software Foundation, either version 3 of the License, or (at your
12 option) any later version.
13 
14 Gnuastro is distributed in the hope that it will be useful, but
15 WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17 General Public License for more details.
18 
19 You should have received a copy of the GNU General Public License
20 along with Gnuastro. If not, see <http://www.gnu.org/licenses/>.
21 **********************************************************************/
22 #ifndef __GAL_OPTIONS_H__
23 #define __GAL_OPTIONS_H__
24 
25 #include <argp.h>
26 
27 #include <gnuastro/tile.h>
28 #include <gnuastro/list.h>
29 #include <gnuastro/fits.h>
30 
31 
32 
33 
34 /**********************************************************************/
35 /************                Common options             ***************/
36 /**********************************************************************/
37 
38 /* Type for options that don't accept an argument/value. This macro is
39    defined to help make the definition and processing of these options
40    easier and less buggy. Please use this macro for such options. */
41 #define GAL_OPTIONS_NO_ARG_TYPE   GAL_TYPE_UINT8
42 
43 /* When printing the option names, values and comments, we want things to
44    be clean and readable (all the comments starting on one line for most,
45    ideally all, lines). But in some cases, option values can become too
46    long (for example the '--polygon' option in Crop, which takes many
47    coordinates). So simply using the maximum option length is going to make
48    the whole thing unreadable and we need to have a maximum so this rule
49    only applies to them. */
50 #define GAL_OPTIONS_MAX_VALUE_LEN 10
51 
52 /* Statically allocated space for printing option values. */
53 #define GAL_OPTIONS_STATIC_MEM_FOR_VALUES 2000
54 
55 
56 
57 
58 
59 /* Standard groups of options. From the Argp manual (in GNU C Library): "In
60    a long help message, options are sorted alphabetically within each
61    group, and the groups presented in the order 0, 1, 2, ..., N, -M, ...,
62    -2, -1."
63 
64    We want the Operating mode group of options to be the last and the input
65    and output groups to the be the first. So first we set the operating
66    mdoe group code to '-1', and benefit from the definition of the
67    Enumerator type in C, so each field afterwards will be one integer
68    larger than the previous. The largest common option group is then used
69    to build the codes of program-specific option groups. */
70 enum options_standard_groups
71 {
72   GAL_OPTIONS_GROUP_OPERATING_MODE = -1,
73   GAL_OPTIONS_GROUP_INPUT=1,
74   GAL_OPTIONS_GROUP_TESSELLATION,
75   GAL_OPTIONS_GROUP_OUTPUT,
76 
77   GAL_OPTIONS_GROUP_AFTER_COMMON,
78 };
79 
80 
81 
82 
83 
84 /* Key values for the common options, the free alphabetical keys are listed
85    below. You can use any of the free letters for an option in a
86    program. Note that '-V', which is used by GNU and implemented by Argp,
87    is also removed from this list.
88 
89    a b c d e f g i j k l m n p r s t u v w x y z
90    A B C E G H J L O Q R W X Y
91 */
92 enum options_common_keys
93 {
94   /* With short-option version */
95   GAL_OPTIONS_KEY_HDU           = 'h',
96   GAL_OPTIONS_KEY_OUTPUT        = 'o',
97   GAL_OPTIONS_KEY_TYPE          = 'T',
98   GAL_OPTIONS_KEY_DONTDELETE    = 'D',
99   GAL_OPTIONS_KEY_KEEPINPUTDIR  = 'K',
100   GAL_OPTIONS_KEY_QUIET         = 'q',
101   GAL_OPTIONS_KEY_NUMTHREADS    = 'N',
102   GAL_OPTIONS_KEY_PRINTPARAMS   = 'P',
103   GAL_OPTIONS_KEY_SETDIRCONF    = 'S',
104   GAL_OPTIONS_KEY_SETUSRCONF    = 'U',
105   GAL_OPTIONS_KEY_IGNORECASE    = 'I',
106   GAL_OPTIONS_KEY_TILESIZE      = 'Z',
107   GAL_OPTIONS_KEY_NUMCHANNELS   = 'M',
108   GAL_OPTIONS_KEY_REMAINDERFRAC = 'F',
109 
110   /* Only long option (integers for keywords). */
111   GAL_OPTIONS_KEY_STDINTIMEOUT = 500,
112   GAL_OPTIONS_KEY_MINMAPSIZE,
113   GAL_OPTIONS_KEY_QUIETMMAP,
114   GAL_OPTIONS_KEY_LOG,
115   GAL_OPTIONS_KEY_CITE,
116   GAL_OPTIONS_KEY_CONFIG,
117   GAL_OPTIONS_KEY_SEARCHIN,
118   GAL_OPTIONS_KEY_LASTCONFIG,
119   GAL_OPTIONS_KEY_CHECKCONFIG,
120   GAL_OPTIONS_KEY_TABLEFORMAT,
121   GAL_OPTIONS_KEY_ONLYVERSION,
122   GAL_OPTIONS_KEY_WORKOVERCH,
123   GAL_OPTIONS_KEY_CHECKTILES,
124   GAL_OPTIONS_KEY_ONEELEMPERTILE,
125   GAL_OPTIONS_KEY_INTERPONLYBLANK,
126   GAL_OPTIONS_KEY_INTERPMETRIC,
127   GAL_OPTIONS_KEY_INTERPNUMNGB,
128   GAL_OPTIONS_KEY_WCSLINEARMATRIX,
129 };
130 
131 
132 
133 
134 
135 /* Conditions to check */
136 enum gal_options_range_values
137 {
138   GAL_OPTIONS_RANGE_ANY,
139 
140   GAL_OPTIONS_RANGE_GT_0,
141   GAL_OPTIONS_RANGE_GE_0,
142   GAL_OPTIONS_RANGE_0_OR_1,
143   GAL_OPTIONS_RANGE_GE_0_LE_1,
144   GAL_OPTIONS_RANGE_GE_0_LT_1,
145   GAL_OPTIONS_RANGE_GT_0_LT_1,
146 
147   GAL_OPTIONS_RANGE_GT_0_ODD,
148   GAL_OPTIONS_RANGE_0_OR_ODD,
149 };
150 
151 
152 
153 
154 
155 /* What to do if option isn't given. Note that in each program's 'main.c'
156    the main program structure is initialized to zero (or NULL for
157    pointers). */
158 enum gal_options_mandatory_values
159 {
160   GAL_OPTIONS_NOT_MANDATORY,     /* =0 in C standard. */
161   GAL_OPTIONS_MANDATORY,
162 };
163 
164 
165 
166 
167 
168 /* If the option has already been given a value or not. */
169 enum gal_options_set_values
170 {
171   GAL_OPTIONS_NOT_SET,           /* =0 in C standard. */
172   GAL_OPTIONS_SET,
173 };
174 
175 
176 
177 
178 
179 /* The structure keeping all the values of the common options in Gnuastro's
180    programs. */
181 struct gal_options_common_params
182 {
183   /* Tessellation. */
184   struct gal_tile_two_layer_params tl; /* Two layer tessellation params.  */
185   uint8_t      interponlyblank; /* Only interpolate over blank values.    */
186   uint8_t         interpmetric; /* Metric to use for nearest-ngb interp.  */
187   size_t          interpnumngb; /* Number of neighbors for interpolation. */
188 
189   /* Input. */
190   char                    *hdu; /* Image extension.                       */
191   uint8_t             searchin; /* Column meta-data to match/search.      */
192   uint8_t           ignorecase; /* Ignore case when matching col info.    */
193   long            stdintimeout; /* Timeout (micro-seconds) for stdin.     */
194 
195   /* Output. */
196   char                 *output; /* Directory containg output.             */
197   uint8_t                 type; /* Data type of output.                   */
198   uint8_t          tableformat; /* Internal code for output table format. */
199   uint8_t      wcslinearmatrix; /* WCS matrix to use (PC or CD).          */
200   uint8_t           dontdelete; /* ==1: Don't delete existing file.       */
201   uint8_t         keepinputdir; /* Keep input directory for auto output.  */
202 
203   /* Operating modes. */
204   uint8_t                quiet; /* Only print errors.                     */
205   size_t            numthreads; /* Number of threads to use.              */
206   size_t            minmapsize; /* Minimum bytes necessary to use mmap.   */
207   uint8_t            quietmmap; /* ==0: print mmap'd file name and size.  */
208   uint8_t                  log; /* Make a log file.                       */
209   char            *onlyversion; /* Redundant, kept/set for generality.    */
210 
211   /* Configuration files. */
212   uint8_t          printparams; /* To print the full list of parameters.  */
213   uint8_t           setdirconf; /* To write the directory config file.    */
214   uint8_t           setusrconf; /* To write teh user config config file.  */
215   uint8_t           lastconfig; /* This is the last configuration file.   */
216   uint8_t          checkconfig; /* Check config files and values.         */
217 
218   /* Output files. */
219   gal_fits_list_key_t  *okeys;  /* Configuration as FITS keys in output.  */
220 
221   /* For internal (to option processing) purposes. */
222   uint8_t                 keep; /* Output file can exist.                 */
223   void         *program_struct; /* Host program's main variable struct.   */
224   char           *program_name; /* Official name to be used in text.      */
225   char           *program_exec; /* Program's executable name.             */
226   char         *program_bibtex; /* BibTeX record for this program.        */
227   char        *program_authors; /* List of the program authors.           */
228   struct argp_option *coptions; /* Common options to all programs.        */
229   struct argp_option *poptions; /* Program specific options.              */
230   gal_list_i32_t  *mand_common; /* Common mandatory options.  */
231   gal_list_str_t  *novalue_doc; /* Mandatory opts, no value   */
232   gal_list_str_t *novalue_name; /* Mandatory opts, no value   */
233 };
234 
235 
236 
237 
238 
239 /**********************************************************************/
240 /************              Option utilities             ***************/
241 /**********************************************************************/
242 int
243 gal_options_is_last(struct argp_option *option);
244 
245 int
246 gal_options_is_category_title(struct argp_option *option);
247 
248 void
249 gal_options_add_to_not_given(struct gal_options_common_params *cp,
250                              struct argp_option *option);
251 
252 void
253 gal_options_abort_if_mandatory_missing(struct gal_options_common_params *cp);
254 
255 
256 
257 /**********************************************************************/
258 /************     Parser functions for common options   ***************/
259 /**********************************************************************/
260 void *
261 gal_options_check_version(struct argp_option *option, char *arg,
262                           char *filename, size_t lineno, void *junk);
263 
264 void *
265 gal_options_print_citation(struct argp_option *option, char *arg,
266                            char *filename, size_t lineno, void *pa);
267 
268 void *
269 gal_options_check_config(struct argp_option *option, char *arg,
270                          char *filename, size_t lineno, void *junk);
271 
272 void *
273 gal_options_read_type(struct argp_option *option, char *arg,
274                       char *filename, size_t lineno, void *junk);
275 
276 void *
277 gal_options_read_searchin(struct argp_option *option, char *arg,
278                           char *filename, size_t lineno, void *junk);
279 
280 void *
281 gal_options_read_wcslinearmatrix(struct argp_option *option, char *arg,
282                                  char *filename, size_t lineno, void *junk);
283 
284 void *
285 gal_options_read_tableformat(struct argp_option *option, char *arg,
286                              char *filename, size_t lineno, void *junk);
287 
288 void *
289 gal_options_read_interpmetric(struct argp_option *option, char *arg,
290                               char *filename, size_t lineno, void *junk);
291 
292 gal_data_t *
293 gal_options_parse_list_of_numbers(char *string, char *filename,
294                                   size_t lineno);
295 
296 gal_data_t *
297 gal_options_parse_csv_strings_raw(char *string, char *filename,
298                                   size_t lineno);
299 
300 void *
301 gal_options_parse_csv_strings(struct argp_option *option, char *arg,
302                               char *filename, size_t lineno, void *junk);
303 
304 void
305 gal_options_merge_list_of_csv(gal_list_str_t **list);
306 
307 void *
308 gal_options_parse_sizes_reverse(struct argp_option *option, char *arg,
309                                 char *filename, size_t lineno, void *params);
310 
311 void *
312 gal_options_parse_csv_float64(struct argp_option *option, char *arg,
313                               char *filename, size_t lineno, void *junk);
314 
315 void *
316 gal_options_read_sigma_clip(struct argp_option *option, char *arg,
317                             char *filename, size_t lineno, void *junk);
318 
319 void *
320 gal_options_parse_name_and_strings(struct argp_option *option, char *arg,
321                                    char *filename, size_t lineno, void *junk);
322 
323 void *
324 gal_options_parse_name_and_float64s(struct argp_option *option, char *arg,
325                                     char *filename, size_t lineno, void *junk);
326 
327 gal_data_t *
328 gal_options_parse_colon_sep_csv_raw(char *instring, char *filename,
329                                     size_t lineno);
330 
331 void *
332 gal_options_parse_colon_sep_csv(struct argp_option *option, char *arg,
333                                 char *filename, size_t lineno, void *junk);
334 
335 
336 /**********************************************************************/
337 /************            Command-line options           ***************/
338 /**********************************************************************/
339 error_t
340 gal_options_set_from_key(int key, char *arg, struct argp_option *options,
341                          struct gal_options_common_params *cp);
342 
343 error_t
344 gal_options_common_argp_parse(int key, char *arg, struct argp_state *state);
345 
346 char *
347 gal_options_stdin_error(long stdintimeout, int precedence, char *name);
348 
349 gal_list_str_t *
350 gal_options_check_stdin(char *inputname, long stdintimeout, char *name);
351 
352 
353 
354 
355 /**********************************************************************/
356 /************            Configuration files            ***************/
357 /**********************************************************************/
358 void *
359 gal_options_call_parse_config_file(struct argp_option *option, char *arg,
360                                    char *filename, size_t lineno, void *cp);
361 
362 void
363 gal_options_read_config_set(struct gal_options_common_params *cp);
364 
365 
366 
367 
368 /**********************************************************************/
369 /************              Printing/Writing             ***************/
370 /**********************************************************************/
371 void
372 gal_options_print_state(struct gal_options_common_params *cp);
373 
374 void
375 gal_options_as_fits_keywords(struct gal_options_common_params *cp);
376 
377 #endif
378