argpar/argpar.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (c) 2019-2021 Philippe Proulx <pproulx@efficios.com>
   5  * Copyright (c) 2020-2021 Simon Marchi <simon.marchi@efficios.com>
   6  */
   7
   8 #ifndef ARGPAR_ARGPAR_H
   9 #define ARGPAR_ARGPAR_H
  10
  11 #include <stdbool.h>
  12
  13 /*
  14  * argpar is a library which provides facilities for command-line
  15  * argument parsing.
  16  *
  17  * Two APIs are available:
  18  *
  19  * Iterator API:
  20  *     Create a parsing iterator with argpar_iter_create(), then
  21  *     repeatedly call argpar_iter_next() to access the parsing results,
  22  *     until one of:
  23  *
  24  *     * There are no more arguments.
  25  *
  26  *     * The argument parser encounters an error (for example, an
  27  *       unknown option).
  28  *
  29  *     * You need to stop.
  30  *
  31  *     This API provides more parsing control than the next one.
  32  *
  33  * Single call API:
  34  *     Call argpar_parse(), which parses the arguments until one of:
  35  *
  36  *     * There are no more arguments.
  37  *
  38  *     * It encounters an argument parsing error.
  39  *
  40  *     argpar_parse() returns a single array of parsing results.
  41  *
  42  * Both methods parse the arguments `argv` of which the count is `argc`
  43  * using the sentinel-terminated (use `ARGPAR_OPT_DESCR_SENTINEL`)
  44  * option descriptor array `descrs`.
  45  *
  46  * argpar considers ALL the elements of `argv`, including the first one,
  47  * so that you would typically pass `argc - 1` and `&argv[1]` from what
  48  * main() receives.
  49  *
  50  * The argpar parsers support:
  51  *
  52  * * Short options without an argument, possibly tied together:
  53  *
  54  *       -f -auf -n
  55  *
  56  * * Short options with argument:
  57  *
  58  *       -b 45 -f/mein/file -xyzhello
  59  *
  60  * * Long options without an argument:
  61  *
  62  *       --five-guys --burger-king --pizza-hut --subway
  63  *
  64  * * Long options with arguments:
  65  *
  66  *       --security enable --time=18.56
  67  *
  68  * * Non-option arguments (anything else).
  69  *
  70  * The argpar parsers parse `-` and `--` as non-option arguments. A
  71  * non-option argument cannot have the form of an option, for example if
  72  * you need to pass the exact relative path `--component`. In that case,
  73  * you would need to pass `./--component`. There's no generic way to
  74  * escape `-` as of this version.
  75  *
  76  * Both argpar_iter_create() and argpar_parse() accept duplicate options
  77  * (they produce one item for each instance).
  78  *
  79  * A returned parsing item has the type `const struct argpar_item *`.
  80  * Get the type (option or non-option) of an item with
  81  * argpar_item_type(). Each item type has its set of dedicated methods
  82  * (`argpar_item_opt_` and `argpar_item_non_opt_` prefixes).
  83  *
  84  * Both argpar_iter_create() and argpar_parse() produce the items in
  85  * the same order that the arguments were parsed, including non-option
  86  * arguments. This means, for example, that for:
  87  *
  88  *     --hello --count=23 /path/to/file -ab --type file magie
  89  *
  90  * The produced items are, in this order:
  91  *
  92  * 1. Option item (`--hello`).
  93  * 2. Option item (`--count` with argument `23`).
  94  * 3. Non-option item (`/path/to/file`).
  95  * 4. Option item (`-a`).
  96  * 5. Option item (`-b`).
  97  * 6. Option item (`--type` with argument `file`).
  98  * 7. Non-option item (`magie`).
  99  */
 100
 101 /* Sentinel for an option descriptor array */
 102 #define ARGPAR_OPT_DESCR_SENTINEL       { -1, '\0', NULL, false }
 103
 104 /*
 105  * If argpar is used in some shared library, we don't want said library
 106  * to export its symbols, so mark them as "hidden".
 107  *
 108  * On Windows, symbols are local unless explicitly exported; see
 109  * <https://gcc.gnu.org/wiki/Visibility>.
 110  */
 111 #if defined(_WIN32) || defined(__CYGWIN__)
 112 # define ARGPAR_HIDDEN
 113 #else
 114 # define ARGPAR_HIDDEN __attribute__((visibility("hidden")))
 115 #endif
 116
 117 /* Forward-declaration for the opaque type */
 118 struct argpar_iter;
 119
 120 /* Option descriptor */
 121 struct argpar_opt_descr {
 122         /* Numeric ID for this option */
 123         const int id;
 124
 125         /* Short option character, or `\0` */
 126         const char short_name;
 127
 128         /* Long option name (without the `--` prefix), or `NULL` */
 129         const char * const long_name;
 130
 131         /* True if this option has an argument */
 132         const bool with_arg;
 133 };
 134
 135 /* Item type */
 136 enum argpar_item_type {
 137         /* Option */
 138         ARGPAR_ITEM_TYPE_OPT,
 139
 140         /* Non-option */
 141         ARGPAR_ITEM_TYPE_NON_OPT,
 142 };
 143
 144 /* Parsing item, as created by argpar_parse() and argpar_iter_next() */
 145 struct argpar_item;
 146
 147 /*
 148  * Returns the type of the parsing item `item`.
 149  */
 150 ARGPAR_HIDDEN
 151 enum argpar_item_type argpar_item_type(const struct argpar_item *item);
 152
 153 /*
 154  * Returns the option descriptor of the option parsing item `item`.
 155  */
 156 ARGPAR_HIDDEN
 157 const struct argpar_opt_descr *argpar_item_opt_descr(
 158                 const struct argpar_item *item);
 159
 160 /*
 161  * Returns the argument of the option parsing item `item`, or `NULL` if
 162  * none.
 163  */
 164 ARGPAR_HIDDEN
 165 const char *argpar_item_opt_arg(const struct argpar_item *item);
 166
 167 /*
 168  * Returns the complete argument, pointing to one of the entries of the
 169  * original arguments (`argv`), of the non-option parsing item `item`.
 170  */
 171 ARGPAR_HIDDEN
 172 const char *argpar_item_non_opt_arg(const struct argpar_item *item);
 173
 174 /*
 175  * Returns the original index, within ALL the original arguments
 176  * (`argv`), of the non-option parsing item `item`.
 177  */
 178 ARGPAR_HIDDEN
 179 unsigned int argpar_item_non_opt_orig_index(const struct argpar_item *item);
 180
 181 /*
 182  * Returns the index, within the non-option arguments, of the non-option
 183  * parsing item `item`.
 184  */
 185 ARGPAR_HIDDEN
 186 unsigned int argpar_item_non_opt_non_opt_index(const struct argpar_item *item);
 187
 188 /*
 189  * Destroys `item`, as created by argpar_iter_next().
 190  */
 191 ARGPAR_HIDDEN
 192 void argpar_item_destroy(const struct argpar_item *item);
 193
 194 struct argpar_item_array {
 195         const struct argpar_item **items;
 196
 197         /* Number of used slots in `items` */
 198         unsigned int n_items;
 199
 200         /* Number of allocated slots in `items` */
 201         unsigned int n_alloc;
 202 };
 203
 204 /* What is returned by argpar_parse() */
 205 struct argpar_parse_ret {
 206         /*
 207          * Array of parsing items, or `NULL` on error.
 208          *
 209          * Do NOT destroy those items manually with
 210          * argpar_iter_destroy(): call argpar_parse_ret_fini() to
 211          * finalize the whole structure.
 212          */
 213         struct argpar_item_array *items;
 214
 215         /* Error string, or `NULL` if none */
 216         char *error;
 217
 218         /* Number of original arguments (`argv`) ingested */
 219         unsigned int ingested_orig_args;
 220 };
 221
 222 /*
 223  * Parses arguments in `argv` until the end is reached or an error is
 224  * encountered.
 225  *
 226  * On success, this function returns an array of items (field `items` of
 227  * `struct argpar_parse_ret`).
 228  *
 229  * In the returned structure, `ingested_orig_args` is the number of
 230  * ingested arguments within `argv` to produce the resulting array of
 231  * items.
 232  *
 233  * If `fail_on_unknown_opt` is true, then on success
 234  * `ingested_orig_args` is equal to `argc`. Otherwise,
 235  * `ingested_orig_args` contains the number of original arguments until
 236  * an unknown _option_ occurs. For example, with
 237  *
 238  *     --great --white contact nuance --shark nuclear
 239  *
 240  * if `--shark` is not described within `descrs` and
 241  * `fail_on_unknown_opt` is false, then `ingested_orig_args` is 4 (two
 242  * options, two non-options), whereas `argc` is 6.
 243  *
 244  * This makes it possible to know where a command name is, for example.
 245  * With those arguments:
 246  *
 247  *     --verbose --stuff=23 do-something --specific-opt -f -b
 248  *
 249  * and the descriptors for `--verbose` and `--stuff` only, the function
 250  * returns the `--verbose` and `--stuff` option items, the
 251  * `do-something` non-option item, and that three original arguments
 252  * were ingested. This means you can start the next argument parsing
 253  * stage, with option descriptors depending on the command name, at
 254  * `&argv[3]`.
 255  *
 256  * Note that `ingested_orig_args` is not always equal to the number of
 257  * returned items, as
 258  *
 259  *     --hello -fdw
 260  *
 261  * for example contains two ingested original arguments, but four
 262  * resulting items.
 263  *
 264  * On failure, the `items` member of the returned structure is `NULL`,
 265  * and the `error` string member contains details about the error.
 266  *
 267  * Finalize the returned structure with argpar_parse_ret_fini().
 268  */
 269 ARGPAR_HIDDEN
 270 struct argpar_parse_ret argpar_parse(unsigned int argc,
 271                 const char * const *argv,
 272                 const struct argpar_opt_descr *descrs,
 273                 bool fail_on_unknown_opt);
 274
 275 /*
 276  * Finalizes what argpar_parse() returns.
 277  *
 278  * You may call argpar_parse() multiple times with the same structure.
 279  */
 280 ARGPAR_HIDDEN
 281 void argpar_parse_ret_fini(struct argpar_parse_ret *ret);
 282
 283 /*
 284  * Creates an argument parsing iterator.
 285  *
 286  * This function initializes the returned structure, but doesn't
 287  * actually start parsing the arguments.
 288  *
 289  * `*argv` and `*descrs` must NOT change for the lifetime of the
 290  * returned iterator (until you call argpar_iter_destroy()) and for the
 291  * lifetime of any parsing item (until you call argpar_item_destroy())
 292  * argpar_iter_next() creates for the returned iterator.
 293  *
 294  * Call argpar_iter_next() with the returned iterator to obtain the next
 295  * parsing result (item).
 296  */
 297 ARGPAR_HIDDEN
 298 struct argpar_iter *argpar_iter_create(unsigned int argc,
 299                 const char * const *argv,
 300                 const struct argpar_opt_descr *descrs);
 301
 302 /*
 303  * Destroys `iter`, as returned by argpar_iter_create().
 304  */
 305 ARGPAR_HIDDEN
 306 void argpar_iter_destroy(struct argpar_iter *iter);
 307
 308 /*
 309  * Return type of argpar_iter_next().
 310  */
 311 enum argpar_iter_next_status {
 312         ARGPAR_ITER_NEXT_STATUS_OK,
 313         ARGPAR_ITER_NEXT_STATUS_END,
 314         ARGPAR_ITER_NEXT_STATUS_ERROR_UNKNOWN_OPT,
 315         ARGPAR_ITER_NEXT_STATUS_ERROR_MISSING_OPT_ARG,
 316         ARGPAR_ITER_NEXT_STATUS_ERROR_UNEXPECTED_OPT_ARG,
 317         ARGPAR_ITER_NEXT_STATUS_ERROR_MEMORY,
 318 };
 319
 320 /*
 321  * Parses and returns the next item from `iter`.
 322  *
 323  * On success, this function:
 324  *
 325  * * Sets `*item` to a parsing item which describes the next option
 326  *   or non-option argument.
 327  *
 328  *   Destroy `*item` with argpar_item_destroy().
 329  *
 330  * * Returns `ARGPAR_ITER_NEXT_STATUS_OK`.
 331  *
 332  * If there are no more items to return, this function returns
 333  * `ARGPAR_ITER_NEXT_STATUS_END`.
 334  *
 335  * On failure, this function:
 336  *
 337  * * Returns one of:
 338  *
 339  *   `ARGPAR_ITER_NEXT_STATUS_ERROR_UNKNOWN_OPT`:
 340  *       Unknown option (not found in `descrs` as passed to
 341  *       argpar_iter_create() to create `iter`).
 342  *
 343  *   `ARGPAR_ITER_NEXT_STATUS_ERROR_MISSING_OPT_ARG`:
 344  *       Missing option argument.
 345  *
 346  *   `ARGPAR_ITER_NEXT_STATUS_ERROR_UNEXPECTED_OPT_ARG`:
 347  *       Unexpected option argument.
 348  *
 349  *   `ARGPAR_ITER_NEXT_STATUS_ERROR_MEMORY`:
 350  *       Memory error.
 351  *
 352  * * Except for the `ARGPAR_ITER_NEXT_STATUS_ERROR_MEMORY` status,
 353  *   sets `*error`, if not `NULL`, to a descriptive error string.
 354  *   Free `*error` with free().
 355  */
 356 enum argpar_iter_next_status argpar_iter_next(
 357                 struct argpar_iter *iter, const struct argpar_item **item,
 358                 char **error);
 359
 360 /*
 361  * Returns the number of ingested elements from `argv`, as passed to
 362  * argpar_iter_create() to create `*iter`, that were required to produce
 363  * the previously returned items.
 364  */
 365 ARGPAR_HIDDEN
 366 unsigned int argpar_iter_ingested_orig_args(const struct argpar_iter *iter);
 367
 368 /*
 369  * Destroys `_item` (`const struct argpar_item *`) and sets it to
 370  * `NULL`.
 371  */
 372 #define ARGPAR_ITEM_DESTROY_AND_RESET(_item)                            \
 373         {                                                               \
 374                 argpar_item_destroy(_item);                             \
 375                 _item = NULL;                                           \
 376         }
 377
 378 #endif /* ARGPAR_ARGPAR_H */