src/common/argpar/argpar.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright 2019 Philippe Proulx <pproulx@efficios.com>
   5  */
   6
   7 #ifndef BABELTRACE_ARGPAR_H
   8 #define BABELTRACE_ARGPAR_H
   9
  10 #include <stdbool.h>
  11
  12 /*
  13  * argpar is a library that provides facilities for argument parsing.
  14  *
  15  * Two APIs are available:
  16  *
  17  *   - The iterator-style API, where you initialize a state object with
  18  *     `argpar_state_create`, then repeatedly call `argpar_state_parse_next` to
  19  *     get the arguments, until (1) there are no more arguments, (2) the parser
  20  *     encounters an error (e.g. unknown option) or (3) you get bored.  This
  21  *     API gives you more control on when to stop parsing the arguments.
  22  *
  23  *   - The parse-everything-in-one-shot-API, where you call `argpar_parse`,
  24  *     which parses the arguments until (1) there are not more arguments or
  25  *     (2) it encounters a parser error.  It returns you a list of all the
  26  *     arguments it was able to parse, which you can consult at your leisure.
  27  *
  28  * The following describes how arguments are parsed, and applies to both APIs.
  29  *
  30  * argpar parses the arguments `argv` of which the count is `argc` using the
  31  * sentinel-terminated (use `ARGPAR_OPT_DESCR_SENTINEL`) option
  32  * descriptor array `descrs`.
  33  *
  34  * argpar considers ALL the elements of `argv`, including the* first one, so
  35  * that you would typically pass `argc - 1` and `&argv[1]` from what main()
  36  * receives.
  37  *
  38  * This argument parser supports:
  39  *
  40  * * Short options without an argument, possibly tied together:
  41  *
  42  *       -f -auf -n
  43  *
  44  * * Short options with argument:
  45  *
  46  *       -b 45 -f/mein/file -xyzhello
  47  *
  48  * * Long options without an argument:
  49  *
  50  *       --five-guys --burger-king --pizza-hut --subway
  51  *
  52  * * Long options with arguments:
  53  *
  54  *       --security enable --time=18.56
  55  *
  56  * * Non-option arguments (anything else).
  57  *
  58  * This parser does not accept `-` or `--` as arguments. The latter
  59  * means "end of options" for many command-line tools, but this function
  60  * is all about keeping the order of the arguments, so it does not mean
  61  * much to put them at the end. This has the side effect that a
  62  * non-option argument cannot have the form of an option, for example if
  63  * you need to pass the exact relative path `--component`. In that case,
  64  * you would need to pass `./--component`. There's no generic way to
  65  * escape `-` for the moment.
  66  *
  67  * This parser accepts duplicate options (it will output one item for each
  68  * instance).
  69  *
  70  * The returned items are of the type `struct argpar_item *`.  Each item
  71  * is to be casted to the appropriate type (`struct argpar_item_opt *` or
  72  * `struct argpar_item_non_opt *`) depending on its type.
  73  *
  74  * The items are returned in the same order that the arguments were parsed,
  75  * including non-option arguments. This means, for example, that for
  76  *
  77  *     --hello --meow=23 /path/to/file -b
  78  *
  79  * found items are returned in this order: option item (--hello), option item
  80  * (--meow=23), non-option item (/path/to/file) and option item (-b).
  81  */
  82
  83 /* Sentinel for an option descriptor array */
  84 #define ARGPAR_OPT_DESCR_SENTINEL       { -1, '\0', NULL, false }
  85
  86 /*
  87  * ARGPAR_HIDDEN: if argpar is used in some shared library, we don't want them
  88  * to be exported by that library, so mark them as "hidden".
  89  *
  90  * On Windows, symbols are local unless explicitly exported,
  91  * see https://gcc.gnu.org/wiki/Visibility
  92  */
  93 #if defined(_WIN32) || defined(__CYGWIN__)
  94 #define ARGPAR_HIDDEN
  95 #else
  96 #define ARGPAR_HIDDEN __attribute__((visibility("hidden")))
  97 #endif
  98
  99 /* Forward-declaration for the opaque type. */
 100 struct argpar_state;
 101
 102 /* Option descriptor */
 103 struct argpar_opt_descr {
 104         /* Numeric ID for this option */
 105         const int id;
 106
 107         /* Short option character, or `\0` */
 108         const char short_name;
 109
 110         /* Long option name (without `--`), or `NULL` */
 111         const char * const long_name;
 112
 113         /* True if this option has an argument */
 114         const bool with_arg;
 115 };
 116
 117 /* Item type */
 118 enum argpar_item_type {
 119         /* Option */
 120         ARGPAR_ITEM_TYPE_OPT,
 121
 122         /* Non-option */
 123         ARGPAR_ITEM_TYPE_NON_OPT,
 124 };
 125
 126 /* Base item */
 127 struct argpar_item {
 128         enum argpar_item_type type;
 129 };
 130
 131 /* Option item */
 132 struct argpar_item_opt {
 133         struct argpar_item base;
 134
 135         /* Corresponding descriptor */
 136         const struct argpar_opt_descr *descr;
 137
 138         /* Argument, or `NULL` if none */
 139         const char *arg;
 140 };
 141
 142 /* Non-option item */
 143 struct argpar_item_non_opt {
 144         struct argpar_item base;
 145
 146         /*
 147          * Complete argument, pointing to one of the entries of the
 148          * original arguments (`argv`).
 149          */
 150         const char *arg;
 151
 152         /* Index of this argument amongst all original arguments (`argv`) */
 153         unsigned int orig_index;
 154
 155         /* Index of this argument amongst other non-option arguments */
 156         unsigned int non_opt_index;
 157 };
 158
 159 struct argpar_item_array {
 160         /* Array of `struct argpar_item *`, or `NULL` on error */
 161         struct argpar_item **items;
 162
 163         /* Number of used slots in `items`. */
 164         unsigned int n_items;
 165
 166         /* Number of allocated slots in `items`. */
 167         unsigned int n_alloc;
 168 };
 169
 170 /* What is returned by argpar_parse() */
 171 struct argpar_parse_ret {
 172         /* Array of `struct argpar_item *`, or `NULL` on error */
 173         struct argpar_item_array *items;
 174
 175         /* Error string, or `NULL` if none */
 176         char *error;
 177
 178         /* Number of original arguments (`argv`) ingested */
 179         unsigned int ingested_orig_args;
 180 };
 181
 182 /*
 183  * Parses arguments in `argv` until the end is reached or an error is
 184  * encountered.
 185  *
 186  * On success, this function returns an array of items
 187  * (field `items` of `struct argpar_parse_ret`) corresponding to each parsed
 188  * argument.
 189  *
 190  * In the returned structure, `ingested_orig_args` is the number of
 191  * ingested arguments within `argv` to produce the resulting array of
 192  * items.
 193  *
 194  * If `fail_on_unknown_opt` is true, then on success `ingested_orig_args` is
 195  * equal to `argc`. Otherwise, `ingested_orig_args` contains the number of
 196  * original arguments until an unknown _option_ occurs. For example, with
 197  *
 198  *     --great --white contact nuance --shark nuclear
 199  *
 200  * if `--shark` is not described within `descrs` and
 201  * `fail_on_unknown_opt` is false, then `ingested_orig_args` is 4 (two
 202  * options, two non-options), whereas `argc` is 6.
 203  *
 204  * This makes it possible to know where a command name is, for example.
 205  * With those arguments:
 206  *
 207  *     --verbose --stuff=23 do-something --specific-opt -f -b
 208  *
 209  * and the descriptors for `--verbose` and `--stuff` only, the function
 210  * returns the `--verbose` and `--stuff` option items, the
 211  * `do-something` non-option item, and that three original arguments
 212  * were ingested. This means you can start the next argument parsing
 213  * stage, with option descriptors depending on the command name, at
 214  * `&argv[3]`.
 215  *
 216  * Note that `ingested_orig_args` is not always equal to the number of
 217  * returned items, as
 218  *
 219  *     --hello -fdw
 220  *
 221  * for example contains two ingested original arguments, but four
 222  * resulting items.
 223  *
 224  * On failure, the returned structure's `items` member is `NULL`, and
 225  * the `error` string member contains details about the error.
 226  *
 227  * You can finalize the returned structure with
 228  * argpar_parse_ret_fini().
 229  */
 230 ARGPAR_HIDDEN
 231 struct argpar_parse_ret argpar_parse(unsigned int argc,
 232                 const char * const *argv,
 233                 const struct argpar_opt_descr *descrs,
 234                 bool fail_on_unknown_opt);
 235
 236 /*
 237  * Finalizes what is returned by argpar_parse().
 238  *
 239  * It is safe to call argpar_parse() multiple times with the same
 240  * structure.
 241  */
 242 ARGPAR_HIDDEN
 243 void argpar_parse_ret_fini(struct argpar_parse_ret *ret);
 244
 245 /*
 246  * Creates an instance of `struct argpar_state`.
 247  *
 248  * This sets up the argpar_state structure, but does not actually
 249  * start parsing the arguments.
 250  *
 251  * When you are done with it, the state must be freed with
 252  * `argpar_state_destroy`.
 253  */
 254 ARGPAR_HIDDEN
 255 struct argpar_state *argpar_state_create(
 256                 unsigned int argc,
 257                 const char * const *argv,
 258                 const struct argpar_opt_descr * const descrs);
 259
 260 /*
 261  * Destroys an instance of `struct argpar_state`.
 262  */
 263 ARGPAR_HIDDEN
 264 void argpar_state_destroy(struct argpar_state *state);
 265
 266
 267 enum argpar_state_parse_next_status {
 268         ARGPAR_STATE_PARSE_NEXT_STATUS_OK,
 269         ARGPAR_STATE_PARSE_NEXT_STATUS_END,
 270         ARGPAR_STATE_PARSE_NEXT_STATUS_ERROR_UNKNOWN_OPT,
 271         ARGPAR_STATE_PARSE_NEXT_STATUS_ERROR,
 272 };
 273
 274 /*
 275  * Parses and returns the next argument from `state`.
 276  *
 277  * On success, an item describing the argument is returned in `*item` and
 278  * ARGPAR_STATE_PARSE_NEXT_STATUS_OK is returned.  The item must be freed with
 279  * `argpar_item_destroy`.
 280  *
 281  * If there are no more arguments to parse, ARGPAR_STATE_PARSE_NEXT_STATUS_END
 282  * is returned.
 283  *
 284  * On failure (status codes ARGPAR_STATE_PARSE_NEXT_STATUS_ERROR_UNKNOWN_OPT and
 285  * ARGPAR_STATE_PARSE_NEXT_STATUS_ERROR), an error string is returned in `*error`.
 286  * This string must be freed with `free`.
 287  */
 288 enum argpar_state_parse_next_status argpar_state_parse_next(
 289                 struct argpar_state *state,
 290                 struct argpar_item **item,
 291                 char **error);
 292
 293 /*
 294  * Return the number of ingested elements from argv that were required to
 295  * produce the previously returned items.
 296  */
 297 ARGPAR_HIDDEN
 298 int argpar_state_get_ingested_orig_args(struct argpar_state *state);
 299
 300 /*
 301  * Destroy an instance of `struct argpar_item`, as returned by
 302  * argpar_state_parse_next.
 303  */
 304 ARGPAR_HIDDEN
 305 void argpar_item_destroy(struct argpar_item *item);
 306
 307 #define ARGPAR_ITEM_DESTROY_AND_RESET(_item)    \
 308         {                                       \
 309                 argpar_item_destroy(_item);     \
 310                 _item = NULL;                   \
 311         }
 312
 313
 314 #endif /* BABELTRACE_ARGPAR_H */