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