1 // SPDX-FileCopyrightText: 2023 Philippe Proulx <eeppeliteloop@gmail.com>
2 // SPDX-License-Identifier: CC-BY-SA-4.0
4 // Render with Asciidoctor
8 :bt2: Babeltrace{nbsp}2
18 **argpar**, an https://efficios.com/[EfficiOS] project, is yet another
19 open-source command-line argument parser for C/{cpp} programs.
27 The most important features of argpar are:
29 * A single MIT-licensed, independent C99 source file and its header that
30 you can copy as is into your own project.
32 * Declarative description of expected options:
42 static const struct argpar_opt_descr descrs[] = {
43 { MY_OPT_ID_DATA, 'd', NULL, false },
44 { MY_OPT_ID_SQUEEZE, '\0', "squeeze", true },
45 { MY_OPT_ID_MEOW, 'm', "meow", true },
46 ARGPAR_OPT_DESCR_SENTINEL,
50 * Supports short (`-k`) and long (`--kernel`) options.
52 Multiple short options may be concatenated, and the argument of the
53 last one may be "`attached`" (`-xvfmyfile`).
55 The argument of a long option may follow a space (`--meow{nbsp}mix`) or
56 an `=` sign (`--meow=mix`).
58 * Supports repeated options:
61 --meow=mix salut -f4 /path/to/file --meow blend -cqc
64 * Fully documented, `const`-correct C99 API based on an argument
67 The `argpar_iter_next()` function produces items in the same order that
68 it parses original arguments, including non-option items. This means,
69 for example, that for:
72 --hello --count=23 /path/to/file -ab --type file -- magie
75 `argpar_iter_next()` produces the following items, in this order:
77 ** Option item: `--hello`.
78 ** Option item: `--count` with argument `23`.
79 ** Non-option item: `/path/to/file`.
82 ** Option item: `--type` with argument `file`.
83 ** Non-option item: `--`.
84 ** Non-option item: `magie`.
86 * On parsing error, provides a detailed error object including the index
87 of the argument (in `argv`) that caused the error as well as the name,
88 if available, of the unknown option.
92 Compared to other similar open-source command-line argument parsers,
93 argpar has the following known limitations:
95 * Doesn't support abbreviated long options.
97 For example, if your option descriptor describes `--fraction`, then
98 `argpar_iter_next()` won't parse `--frac=23`: it will return an unknown
101 * Doesn't explicitly support "`end of option`" (`--`).
106 --hello=world --meow -- mix --hut=23
109 `argpar_iter_next()` provides the `--` argument as a non-option item.
111 * Doesn't support a non-option argument having the form of an option,
112 for example if you need to pass the exact relative path `--calorie`.
114 In that case, you would need to pass `./--calorie`. There's no generic
115 way to escape `-` as of this version. This is in part because argpar
116 doesn't support "`end of option`" (`--`).
118 As a workaround, because argpar offers an iterator API, you may:
120 . Stop using `argpar_iter_next()` from the first `--` non-option item
122 . Use `argpar_item_non_opt_orig_index()` with __**ITEM**__ to get the
123 original index __**I**__ of the first `--` within `argv` (as passed
124 to `argpar_iter_create()`).
125 . Read the remaining non-option arguments from `argv`, starting at
126 __**I**__{nbsp}+{nbsp}1.
128 * Doesn't handle the `-h`/`--help` option in a special way (doesn't show
129 some automatic usage message).
131 * Doesn't provide direct access to the value of an option.
133 This is because argpar offers an iterator API to support positional and
138 To use argpar in your own project, simply copy the `argpar/argpar.c` and
139 `argpar/argpar.h` files and you're ready to go.
141 To build this project, make sure you have
142 https://docs.gtk.org/glib/[GLib]{nbsp}2 (required by the tests), and
145 . **If you build from a Git clone**, run:
152 This generates the `configure` script and other important files.
154 . Configure the project:
161 See `./configure --help` for more options.
170 == Build the API documentation
172 To build the API documentation, make sure you have
173 https://www.doxygen.nl/[Doxygen], and then:
175 * From the root of the project, run:
181 Open `api-doc/html/index.html` with Netscape Navigator.
185 To run the argpar tests:
187 . <<build-argpar,Build the project>>.
198 argpar uses https://review.lttng.org/admin/repos/argpar,general[Gerrit]
201 To report a bug, https://github.com/efficios/argpar/issues/new[create a