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  * Create a parsing iterator with argpar_iter_create(), then
  18  * repeatedly call argpar_iter_next() to access the parsing results,
  19  * until one of:
  20  *
  21  * * There are no more arguments.
  22  *
  23  * * The argument parser encounters an error (for example, an unknown
  24  *   option).
  25  *
  26  * * You need to stop.
  27  *
  28  * The argpar parser parses the original arguments `argv` of which the
  29  * count is `argc` using the sentinel-terminated (use
  30  * `ARGPAR_OPT_DESCR_SENTINEL`) option descriptor array `descrs`.
  31  *
  32  * argpar considers ALL the elements of `argv`, including the first one,
  33  * so that you would typically pass `argc - 1` and `&argv[1]` from what
  34  * main() receives.
  35  *
  36  * The argpar parser supports:
  37  *
  38  * * Short options without an argument, possibly tied together:
  39  *
  40  *       -f -auf -n
  41  *
  42  * * Short options with argument:
  43  *
  44  *       -b 45 -f/mein/file -xyzhello
  45  *
  46  * * Long options without an argument:
  47  *
  48  *       --five-guys --burger-king --pizza-hut --subway
  49  *
  50  * * Long options with arguments:
  51  *
  52  *       --security enable --time=18.56
  53  *
  54  * * Non-option arguments (anything else).
  55  *
  56  * The argpar parser parses `-` and `--` as non-option arguments. A
  57  * non-option argument cannot have the form of an option, for example if
  58  * you need to pass the exact relative path `--component`. In that case,
  59  * you would need to pass `./--component`. There's no generic way to
  60  * escape `-` as of this version.
  61  *
  62  * argpar_iter_create() accepts duplicate options in `descrs` (it
  63  * produces one item for each instance).
  64  *
  65  * A returned parsing item has the type `const struct argpar_item *`.
  66  * Get the type (option or non-option) of an item with
  67  * argpar_item_type(). Each item type has its set of dedicated methods
  68  * (`argpar_item_opt_` and `argpar_item_non_opt_` prefixes).
  69  *
  70  * argpar_iter_next() produces the items in the same order that the
  71  * original arguments were parsed, including non-option arguments. This
  72  * means, for example, that for:
  73  *
  74  *     --hello --count=23 /path/to/file -ab --type file magie
  75  *
  76  * argpar_iter_next() produces the following items, in this order:
  77  *
  78  * 1. Option item (`--hello`).
  79  * 2. Option item (`--count` with argument `23`).
  80  * 3. Non-option item (`/path/to/file`).
  81  * 4. Option item (`-a`).
  82  * 5. Option item (`-b`).
  83  * 6. Option item (`--type` with argument `file`).
  84  * 7. Non-option item (`magie`).
  85  */
  86
  87 /* Sentinel for an option descriptor array */
  88 #define ARGPAR_OPT_DESCR_SENTINEL       { -1, '\0', NULL, false }
  89
  90 /*
  91  * If argpar is used in some shared library, we don't want said library
  92  * to export its symbols, so mark them as "hidden".
  93  *
  94  * On Windows, symbols are local unless explicitly exported; see
  95  * <https://gcc.gnu.org/wiki/Visibility>.
  96  */
  97 #if defined(_WIN32) || defined(__CYGWIN__)
  98 # define ARGPAR_HIDDEN
  99 #else
 100 # define ARGPAR_HIDDEN __attribute__((visibility("hidden")))
 101 #endif
 102
 103 /* Forward-declaration for the opaque argpar iterator type */
 104 struct argpar_iter;
 105
 106 /* Option descriptor */
 107 struct argpar_opt_descr {
 108         /* Numeric ID for this option */
 109         const int id;
 110
 111         /* Short option character, or `\0` */
 112         const char short_name;
 113
 114         /* Long option name (without the `--` prefix), or `NULL` */
 115         const char * const long_name;
 116
 117         /* True if this option has an argument */
 118         const bool with_arg;
 119 };
 120
 121 /* Item type */
 122 enum argpar_item_type {
 123         /* Option */
 124         ARGPAR_ITEM_TYPE_OPT,
 125
 126         /* Non-option */
 127         ARGPAR_ITEM_TYPE_NON_OPT,
 128 };
 129
 130 /* Forward-declaration for the opaque argpar parsing item type */
 131 struct argpar_item;
 132
 133 /*
 134  * Returns the type of the parsing item `item`.
 135  */
 136 ARGPAR_HIDDEN
 137 enum argpar_item_type argpar_item_type(const struct argpar_item *item);
 138
 139 /*
 140  * Returns the option descriptor of the option parsing item `item`.
 141  */
 142 ARGPAR_HIDDEN
 143 const struct argpar_opt_descr *argpar_item_opt_descr(
 144                 const struct argpar_item *item);
 145
 146 /*
 147  * Returns the argument of the option parsing item `item`, or `NULL` if
 148  * none.
 149  */
 150 ARGPAR_HIDDEN
 151 const char *argpar_item_opt_arg(const struct argpar_item *item);
 152
 153 /*
 154  * Returns the complete argument, pointing to one of the entries of the
 155  * original arguments (`argv`), of the non-option parsing item `item`.
 156  */
 157 ARGPAR_HIDDEN
 158 const char *argpar_item_non_opt_arg(const struct argpar_item *item);
 159
 160 /*
 161  * Returns the original index, within ALL the original arguments
 162  * (`argv`), of the non-option parsing item `item`.
 163  */
 164 ARGPAR_HIDDEN
 165 unsigned int argpar_item_non_opt_orig_index(const struct argpar_item *item);
 166
 167 /*
 168  * Returns the index, within the non-option arguments, of the non-option
 169  * parsing item `item`.
 170  */
 171 ARGPAR_HIDDEN
 172 unsigned int argpar_item_non_opt_non_opt_index(const struct argpar_item *item);
 173
 174 /*
 175  * Destroys `item`, as created by argpar_iter_next().
 176  */
 177 ARGPAR_HIDDEN
 178 void argpar_item_destroy(const struct argpar_item *item);
 179
 180 /*
 181  * Creates an argument parsing iterator.
 182  *
 183  * This function initializes the returned structure, but doesn't
 184  * actually start parsing the arguments.
 185  *
 186  * `*argv` and `*descrs` must NOT change for the lifetime of the
 187  * returned iterator (until you call argpar_iter_destroy()) and for the
 188  * lifetime of any parsing item (until you call argpar_item_destroy())
 189  * argpar_iter_next() creates for the returned iterator.
 190  *
 191  * Call argpar_iter_next() with the returned iterator to obtain the next
 192  * parsing result (item).
 193  */
 194 ARGPAR_HIDDEN
 195 struct argpar_iter *argpar_iter_create(unsigned int argc,
 196                 const char * const *argv,
 197                 const struct argpar_opt_descr *descrs);
 198
 199 /*
 200  * Destroys `iter`, as returned by argpar_iter_create().
 201  */
 202 ARGPAR_HIDDEN
 203 void argpar_iter_destroy(struct argpar_iter *iter);
 204
 205 /*
 206  * Return type of argpar_iter_next().
 207  */
 208 enum argpar_iter_next_status {
 209         ARGPAR_ITER_NEXT_STATUS_OK,
 210         ARGPAR_ITER_NEXT_STATUS_END,
 211         ARGPAR_ITER_NEXT_STATUS_ERROR_UNKNOWN_OPT,
 212         ARGPAR_ITER_NEXT_STATUS_ERROR_MISSING_OPT_ARG,
 213         ARGPAR_ITER_NEXT_STATUS_ERROR_UNEXPECTED_OPT_ARG,
 214         ARGPAR_ITER_NEXT_STATUS_ERROR_MEMORY,
 215 };
 216
 217 /*
 218  * Parses and returns the next item from `iter`.
 219  *
 220  * On success, this function:
 221  *
 222  * * Sets `*item` to a parsing item which describes the next option
 223  *   or non-option argument.
 224  *
 225  *   Destroy `*item` with argpar_item_destroy().
 226  *
 227  * * Returns `ARGPAR_ITER_NEXT_STATUS_OK`.
 228  *
 229  * If there are no more items to return, this function returns
 230  * `ARGPAR_ITER_NEXT_STATUS_END`.
 231  *
 232  * On failure, this function:
 233  *
 234  * * Returns one of:
 235  *
 236  *   `ARGPAR_ITER_NEXT_STATUS_ERROR_UNKNOWN_OPT`:
 237  *       Unknown option (not found in `descrs` as passed to
 238  *       argpar_iter_create() to create `iter`).
 239  *
 240  *   `ARGPAR_ITER_NEXT_STATUS_ERROR_MISSING_OPT_ARG`:
 241  *       Missing option argument.
 242  *
 243  *   `ARGPAR_ITER_NEXT_STATUS_ERROR_UNEXPECTED_OPT_ARG`:
 244  *       Unexpected option argument.
 245  *
 246  *   `ARGPAR_ITER_NEXT_STATUS_ERROR_MEMORY`:
 247  *       Memory error.
 248  *
 249  * * Except for the `ARGPAR_ITER_NEXT_STATUS_ERROR_MEMORY` status,
 250  *   sets `*error`, if not `NULL`, to a descriptive error string.
 251  *   Free `*error` with free().
 252  */
 253 enum argpar_iter_next_status argpar_iter_next(
 254                 struct argpar_iter *iter, const struct argpar_item **item,
 255                 char **error);
 256
 257 /*
 258  * Returns the number of ingested elements from `argv`, as passed to
 259  * argpar_iter_create() to create `*iter`, that were required to produce
 260  * the previously returned items.
 261  */
 262 ARGPAR_HIDDEN
 263 unsigned int argpar_iter_ingested_orig_args(const struct argpar_iter *iter);
 264
 265 /*
 266  * Destroys `_item` (`const struct argpar_item *`) and sets it to
 267  * `NULL`.
 268  */
 269 #define ARGPAR_ITEM_DESTROY_AND_RESET(_item)                            \
 270         {                                                               \
 271                 argpar_item_destroy(_item);                             \
 272                 _item = NULL;                                           \
 273         }
 274
 275 #endif /* ARGPAR_ARGPAR_H */