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 BABELTRACE_ARGPAR_H
   9 #define BABELTRACE_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_parse_next() to access the parsing
  22  *     results, 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 `struct argpar_item *`. Each
  83  * item is to be casted to the appropriate type
  84  * (`struct argpar_item_opt *` or `struct argpar_item_non_opt *`)
  85  * depending on its `type` member.
  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 /* Base item */
 148 struct argpar_item {
 149         enum argpar_item_type type;
 150 };
 151
 152 /* Option item */
 153 struct argpar_item_opt {
 154         struct argpar_item base;
 155
 156         /* Corresponding descriptor */
 157         const struct argpar_opt_descr *descr;
 158
 159         /* Argument, or `NULL` if none */
 160         const char *arg;
 161 };
 162
 163 /* Non-option item */
 164 struct argpar_item_non_opt {
 165         struct argpar_item base;
 166
 167         /*
 168          * Complete argument, pointing to one of the entries of the
 169          * original arguments (`argv`).
 170          */
 171         const char *arg;
 172
 173         /* Index of this argument amongst all original arguments (`argv`) */
 174         unsigned int orig_index;
 175
 176         /* Index of this argument amongst other non-option arguments */
 177         unsigned int non_opt_index;
 178 };
 179
 180 struct argpar_item_array {
 181         const struct argpar_item **items;
 182
 183         /* Number of used slots in `items` */
 184         unsigned int n_items;
 185
 186         /* Number of allocated slots in `items` */
 187         unsigned int n_alloc;
 188 };
 189
 190 /* What is returned by argpar_parse() */
 191 struct argpar_parse_ret {
 192         /*
 193          * Array of parsing items, or `NULL` on error.
 194          *
 195          * Do NOT destroy those items manually with
 196          * argpar_iter_destroy(): call argpar_parse_ret_fini() to
 197          * finalize the whole structure.
 198          */
 199         struct argpar_item_array *items;
 200
 201         /* Error string, or `NULL` if none */
 202         char *error;
 203
 204         /* Number of original arguments (`argv`) ingested */
 205         unsigned int ingested_orig_args;
 206 };
 207
 208 /*
 209  * Parses arguments in `argv` until the end is reached or an error is
 210  * encountered.
 211  *
 212  * On success, this function returns an array of items (field `items` of
 213  * `struct argpar_parse_ret`).
 214  *
 215  * In the returned structure, `ingested_orig_args` is the number of
 216  * ingested arguments within `argv` to produce the resulting array of
 217  * items.
 218  *
 219  * If `fail_on_unknown_opt` is true, then on success
 220  * `ingested_orig_args` is equal to `argc`. Otherwise,
 221  * `ingested_orig_args` contains the number of original arguments until
 222  * an unknown _option_ occurs. For example, with
 223  *
 224  *     --great --white contact nuance --shark nuclear
 225  *
 226  * if `--shark` is not described within `descrs` and
 227  * `fail_on_unknown_opt` is false, then `ingested_orig_args` is 4 (two
 228  * options, two non-options), whereas `argc` is 6.
 229  *
 230  * This makes it possible to know where a command name is, for example.
 231  * With those arguments:
 232  *
 233  *     --verbose --stuff=23 do-something --specific-opt -f -b
 234  *
 235  * and the descriptors for `--verbose` and `--stuff` only, the function
 236  * returns the `--verbose` and `--stuff` option items, the
 237  * `do-something` non-option item, and that three original arguments
 238  * were ingested. This means you can start the next argument parsing
 239  * stage, with option descriptors depending on the command name, at
 240  * `&argv[3]`.
 241  *
 242  * Note that `ingested_orig_args` is not always equal to the number of
 243  * returned items, as
 244  *
 245  *     --hello -fdw
 246  *
 247  * for example contains two ingested original arguments, but four
 248  * resulting items.
 249  *
 250  * On failure, the `items` member of the returned structure is `NULL`,
 251  * and the `error` string member contains details about the error.
 252  *
 253  * Finalize the returned structure with argpar_parse_ret_fini().
 254  */
 255 ARGPAR_HIDDEN
 256 struct argpar_parse_ret argpar_parse(unsigned int argc,
 257                 const char * const *argv,
 258                 const struct argpar_opt_descr *descrs,
 259                 bool fail_on_unknown_opt);
 260
 261 /*
 262  * Finalizes what argpar_parse() returns.
 263  *
 264  * You may call argpar_parse() multiple times with the same structure.
 265  */
 266 ARGPAR_HIDDEN
 267 void argpar_parse_ret_fini(struct argpar_parse_ret *ret);
 268
 269 /*
 270  * Creates an argument parsing iterator.
 271  *
 272  * This function initializes the returned structure, but doesn't
 273  * actually start parsing the arguments.
 274  *
 275  * `*argv` and `*descrs` must NOT change for the lifetime of the
 276  * returned iterator (until you call argpar_iter_destroy()).
 277  *
 278  * Call argpar_iter_parse_next() with the returned iterator to obtain
 279  * the next parsing result (item).
 280  */
 281 ARGPAR_HIDDEN
 282 struct argpar_iter *argpar_iter_create(unsigned int argc,
 283                 const char * const *argv,
 284                 const struct argpar_opt_descr *descrs);
 285
 286 /*
 287  * Destroys `iter`, as returned by argpar_iter_create().
 288  */
 289 ARGPAR_HIDDEN
 290 void argpar_iter_destroy(struct argpar_iter *iter);
 291
 292 /*
 293  * Return type of argpar_iter_parse_next().
 294  */
 295 enum argpar_iter_parse_next_status {
 296         ARGPAR_ITER_PARSE_NEXT_STATUS_OK,
 297         ARGPAR_ITER_PARSE_NEXT_STATUS_END,
 298         ARGPAR_ITER_PARSE_NEXT_STATUS_ERROR_UNKNOWN_OPT,
 299         ARGPAR_ITER_PARSE_NEXT_STATUS_ERROR,
 300 };
 301
 302 /*
 303  * Parses and returns the next item from `iter`.
 304  *
 305  * On success, this function sets `*item` to an item which describes the
 306  * next option or non-option argument and returns
 307  * `ARGPAR_ITER_PARSE_NEXT_STATUS_OK`. Destroy `*item` with
 308  * argpar_item_destroy().
 309  *
 310  * If there are no more items to return, this function returns
 311  * `ARGPAR_ITER_PARSE_NEXT_STATUS_END`.
 312  *
 313  * On failure (status codes
 314  * `ARGPAR_ITER_PARSE_NEXT_STATUS_ERROR_UNKNOWN_OPT` and
 315  * `ARGPAR_ITER_PARSE_NEXT_STATUS_ERROR`), this function sets `*error`
 316  * to a descriptive error string. Free `*error` with free().
 317  *
 318  * Create an argument parsing iterator with argpar_iter_create().
 319  */
 320 enum argpar_iter_parse_next_status argpar_iter_parse_next(
 321                 struct argpar_iter *iter, const struct argpar_item **item,
 322                 char **error);
 323
 324 /*
 325  * Returns the number of ingested elements from `argv`, as passed to
 326  * argpar_iter_create() to create `*iter`, that were required to produce
 327  * the previously returned items.
 328  */
 329 ARGPAR_HIDDEN
 330 unsigned int argpar_iter_get_ingested_orig_args(const struct argpar_iter *iter);
 331
 332 /*
 333  * Destroys `item`, as created by argpar_iter_parse_next().
 334  */
 335 ARGPAR_HIDDEN
 336 void argpar_item_destroy(const struct argpar_item *item);
 337
 338 /*
 339  * Destroys `_item` (`const struct argpar_item *`) and sets it to
 340  * `NULL`.
 341  */
 342 #define ARGPAR_ITEM_DESTROY_AND_RESET(_item)                            \
 343         {                                                               \
 344                 argpar_item_destroy(_item);                             \
 345                 _item = NULL;                                           \
 346         }
 347
 348 #endif /* BABELTRACE_ARGPAR_H */