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