1 /* 2 Copyright (C) 2015-2021, Dirk Krause 3 SPDX-License-Identifier: BSD-3-Clause 4 */ 5 6 /* 7 WARNING: This file was generated by the dkct program (see 8 http://dktools.sourceforge.net/ for details). 9 Changes you make here will be lost if dkct is run again! 10 You should modify the original source and run dkct on it. 11 Original source: dk4opt.ctr 12 */ 13 14 #ifndef DK4OPT_H_INCLUDED 15 /** Avoid multiple inclusions. */ 16 #define DK4OPT_H_INCLUDED 1 17 18 19 /** @file 20 Process command line option in simple programs. 21 You can specify a set of allowed options including the option 22 arguments types. After processing command line arguments you 23 can simply check which options were used and obtain option 24 argument values. 25 */ 26 27 28 #ifndef DK4CONF_H_INCLUDED 29 #if DK4_BUILDING_DKTOOLS4 30 #include "dk4conf.h" 31 #else 32 #include <dktools-4/dk4conf.h> 33 #endif 34 #endif 35 36 #ifndef DK4TYPES_H_INCLUDED 37 #if DK4_BUILDING_DKTOOLS4 38 #include <libdk4base/dk4types.h> 39 #else 40 #include <dktools-4/dk4types.h> 41 #endif 42 #endif 43 44 #ifndef DK4ERROR_H_INCLUDED 45 #if DK4_BUILDING_DKTOOLS4 46 #include <libdk4base/dk4error.h> 47 #else 48 #include <dktools-4/dk4error.h> 49 #endif 50 #endif 51 52 /** Option specification for application module. 53 */ 54 typedef struct { 55 dkChar c; /**< Short option character. */ 56 const dkChar *longopt; /**< Long option string. */ 57 int argtype; /**< Argument type. */ 58 } dk4_option_specification_t; 59 60 /** Option values can be different types. 61 */ 62 typedef union { 63 dkChar *t; /**< String value. */ 64 double d; /**< Double value. */ 65 dk4_im_t i; /**< Integer value. */ 66 dk4_um_t u; /**< Unsigned integer value. */ 67 size_t s; /**< Size value. */ 68 int b; /**< Boolean value. */ 69 } dk4_option_value_t; 70 71 /** Option with value. 72 */ 73 typedef struct { 74 dk4_option_specification_t spec; /**< Option specification. */ 75 dk4_option_value_t val; /**< Option value. */ 76 int found; /**< Flag: Option found in cmd line. */ 77 } dk4_option_t; 78 79 80 /** Argument types. 81 */ 82 enum { 83 /** No argument expected. 84 */ 85 DK4_OPT_ARG_NONE = 1, 86 87 /** Boolean value expected. 88 */ 89 DK4_OPT_ARG_BOOL , 90 91 /** Size specification expected. 92 */ 93 DK4_OPT_ARG_SIZE , 94 95 /** Signed integer value expected. 96 */ 97 DK4_OPT_ARG_INT , 98 99 /** Unsigned integer value expected. 100 */ 101 DK4_OPT_ARG_UNSIGNED , 102 103 /** Double value expected. 104 */ 105 DK4_OPT_ARG_DOUBLE , 106 107 /** String value expected. 108 */ 109 DK4_OPT_ARG_STRING 110 }; 111 112 113 114 #ifdef __cplusplus 115 extern "C" { 116 #endif 117 118 /** Create option object. 119 CRT on Windows: Optional. 120 @param spec Specifications for the option. 121 @param erp Error report, may be NULL. 122 @return Pointer to new option object on success, NULL on error. 123 124 Error codes: 125 - DK4_E_INVALID_ARGUMENTS<br> 126 if spec is NULL, 127 - DK4_E_SYNTAX<br> 128 if neither short nor long option is defined in spec, 129 - DK4_E_MEMORY<br> 130 if the memory allocation failed. 131 */ 132 dk4_option_t * 133 dk4opt_open(const dk4_option_specification_t *spec, dk4_er_t *erp); 134 135 /** Retrieve boolean value (as int) from option. 136 CRT on Windows: Optional. 137 @param dptr Pointer to destination variable. 138 @param optptr Option to retrieve value from. 139 @param erp Error report, may be NULL. 140 @return 1 on success, 0 on error. 141 142 Error codes: 143 - DK4_E_INVALID_ARGUMENTS<br> 144 if dptr or optptr is NULL or optptr is configured for another data 145 type, 146 - DK4_E_NOT_FOUND<br> 147 if the option was not specified on the command line, 148 - DK4_E_SYNTAX<br> 149 if a string is stored not representing a boolean or the option was 150 configured with an incompatible type. 151 */ 152 int 153 dk4opt_get_bool(int *dptr, dk4_option_t const *optptr, dk4_er_t *erp); 154 155 /** Retrieve size_t value from option. 156 CRT on Windows: Optional. 157 @param dptr Pointer to destination variable. 158 @param optptr Option to retrieve value from. 159 @param erp Error report, may be NULL. 160 @return 1 on success, 0 on error. 161 162 Error codes: 163 - DK4_E_INVALID_ARGUMENTS<br> 164 if dptr or optptr is NULL or optptr is configured for another data 165 type, 166 - DK4_E_NOT_FOUND<br> 167 if the option was not specified on the command line, 168 - DK4_E_SYNTAX<br> 169 if the option was configured for an incompatible type or the option 170 argument string can not be converted to a size_t, 171 - DK4_E_MATH_OVERFLOW<br> 172 if the option was configured for another numeric type and conversion 173 results in an overflow. 174 */ 175 int 176 dk4opt_get_size(size_t *dptr, dk4_option_t const *optptr, dk4_er_t *erp); 177 178 /** Retrieve integer value (dk4_im_t) from option. 179 CRT on Windows: Optional. 180 @param dptr Pointer to destination variable. 181 @param optptr Option to retrieve value from. 182 @param erp Error report, may be NULL. 183 @return 1 on success, 0 on error. 184 185 Error codes: 186 - DK4_E_INVALID_ARGUMENTS<br> 187 if dptr or optptr is NULL or optptr is configured for another data 188 type, 189 - DK4_E_NOT_FOUND<br> 190 if the option was not specified on the command line, 191 - DK4_E_SYNTAX<br> 192 if the option was configured for an incompatible type or the option 193 argument string does not represent an integer number, 194 - DK4_E_MATH_OVERFLOW<br> 195 if the option was configured for another numeric type and conversion 196 results in an overflow. 197 */ 198 int 199 dk4opt_get_int(dk4_im_t *dptr, dk4_option_t const *optptr, dk4_er_t *erp); 200 201 /** Retrieve unsigned integer value (dk4_um_t) from option. 202 CRT on Windows: Optional. 203 @param dptr Pointer to destination variable. 204 @param optptr Option to retrieve value from. 205 @param erp Error report, may be NULL. 206 @return 1 on success, 0 on error. 207 208 Error codes: 209 - DK4_E_INVALID_ARGUMENTS<br> 210 if dptr or optptr is NULL or optptr is configured for another data 211 type, 212 - DK4_E_NOT_FOUND<br> 213 if the option was not specified on the command line, 214 - DK4_E_SYNTAX<br> 215 if the option was configured for an incompatible data type or the 216 option string does not represent an integer number, 217 - DK4_E_MATH_OVERFLOW<br> 218 if the option was configured for an incompatible numeric type and a 219 negative value is stored. 220 */ 221 int 222 dk4opt_get_unsigned(dk4_um_t *dptr, dk4_option_t const *optptr, dk4_er_t *erp); 223 224 /** Retrieve double value from option. 225 CRT on Windows: Optional. 226 @param dptr Pointer to destination variable. 227 @param optptr Option to retrieve value from. 228 @param erp Error report, may be NULL. 229 @return 1 on success, 0 on error. 230 231 Error codes: 232 - DK4_E_INVALID_ARGUMENTS<br> 233 if dptr or optptr is NULL or optptr is configured for another data 234 type, 235 - DK4_E_NOT_FOUND<br> 236 if the option was not specified on the command line, 237 - DK4_E_SYNTAX<br> 238 if the option was configured for an incompatible data type or the 239 string stored as option argument does not represent a double number. 240 */ 241 int 242 dk4opt_get_double(double *dptr, dk4_option_t const *optptr, dk4_er_t *erp); 243 244 /** Retrieve string value from option. 245 CRT on Windows: Optional, disabling CRT reduces functionality 246 as we can not convert double values to strings. 247 @param dptr Pointer to destination buffer. 248 @param szdptr Size of destination buffer (number of dkChar). 249 @param optptr Option to retrieve value from. 250 @param erp Error report, may be NULL. 251 @return 1 on success, 0 on error. 252 253 Error codes: 254 - DK4_E_INVALID_ARGUMENTS<br> 255 if dptr or optptr is NULL or optptr is configured for another data 256 type, 257 - DK4_E_NOT_FOUND<br> 258 if the option was not specified on the command line. 259 - DK4_E_SYNTAX<br> 260 if the option was configured for an incompatible data type, 261 - DK4_E_BUFFER_TOO_SMALL<br> 262 if the destination buffer is too small to hold a conversion result, 263 - DK4_E_NOT_SUPPORTED<br> 264 if the option was configured for the double data type and the use of 265 sprintf() was denied during setup. 266 */ 267 int 268 dk4opt_get_string( 269 dkChar *dptr, size_t szdptr, dk4_option_t const *optptr, dk4_er_t *erp 270 ); 271 272 /** Destroy option object, release memory. 273 CRT on Windows: Optional. 274 @param optptr Option object to destroy. 275 */ 276 void 277 dk4opt_close(dk4_option_t *optptr); 278 279 /** Compare option against other option or char or string. 280 CRT on Windows: Optional. 281 @param l Left pointer, always an option. 282 @param r Right pointer, type depends on cr. 283 @param cr Comparison criteria: 284 0=option/option by short character, 285 1=option/character, 286 2=option/option by long option text, 287 3=option/text. 288 @return Comparison result. 289 */ 290 int 291 dk4option_compare(const void *l, const void *r, int cr); 292 293 /** Process command line options provided to the main function. 294 @param optptr Options array. 295 @param szoptptr Number of elements in array. 296 @param argc Number of command line arguments. 297 @param argv Command line arguments array. 298 @param filenames Pointer array to store file names. 299 @param nfilenames Elements in array (in: size, out: used). 300 @param progname Flag: Argument 0 is program name. 301 @param logstderr Flag: Logging to stderr allowed. 302 @param erp Error report, may be NULL. 303 @return 1 on success, 0 on error. 304 */ 305 int 306 dk4opt_process_argv( 307 dk4_option_t *optptr, 308 size_t szoptptr, 309 int argc, 310 dkChar *argv[], 311 dkChar **filenames, 312 size_t *nfilenames, 313 int progname, 314 int logstderr, 315 dk4_er_t *erp 316 ); 317 318 #ifdef __cplusplus 319 } 320 #endif 321 322 323 #endif 324