README.md
1# Optparse
2
3Optparse is a public domain, portable, reentrant, embeddable,
4getopt-like option parser. It's a single header file and can be
5trivially dropped into any project. It supports POSIX getopt option
6strings, GNU-style long options, argument permutation, and subcommand
7processing.
8
9To get the implementation, define `OPTPARSE_IMPLEMENTATION` before
10including `optparse.h`.
11
12~~~c
13#define OPTPARSE_IMPLEMENTATION
14#include "optparse.h"
15~~~
16
17Optionally define `OPTPARSE_API` to control the API's visibility
18and/or linkage (`static`, `__attribute__`, `__declspec`).
19
20~~~c
21#define OPTPARSE_API static
22#include "optparse.h"
23~~~
24
25## Why not getopt()?
26
27The POSIX getopt option parser has three fatal flaws. These flaws are
28solved by Optparse.
29
301. The getopt parser state is stored entirely in global variables,
31some of which are static and inaccessible. This means only one thread
32can use getopt. It also means it's not possible to recursively parse
33nested sub-arguments while in the middle of argument parsing. Optparse
34fixes this by storing all state on a local struct.
35
362. The POSIX standard provides no way to properly reset the parser.
37For portable code this means getopt is only good for one run, over one
38argv with one option string. It also means subcommand options cannot
39be reliably processed with getopt. Most implementations provide an
40implementation-specific method to reset the parser, but this is not
41portable. Optparse provides an `optparse_arg()` function for stepping
42through non-option arguments, and parsing of options can continue
43again at any time with a different option string. The Optparse struct
44itself could be passed around to subcommand handlers for additional
45subcommand option parsing. If a full parser reset is needed,
46`optparse_init()` can be called again.
47
483. In getopt, error messages are printed to stderr. This can be
49disabled with opterr, but the messages themselves are still
50inaccessible. Optparse solves this by writing the error message to its
51errmsg field, which can be printed to anywhere. The downside to
52Optparse is that this error message will always be in English rather
53than the current locale.
54
55## Permutation
56
57By default, argv is permuted as it is parsed, moving non-option
58arguments to the end of the array. This can be disabled by setting the
59`permute` field to 0 after initialization.
60
61~~~c
62struct optparse options;
63optparse_init(&options, argv);
64options.permute = 0;
65~~~
66
67## Drop-in Replacement
68
69Optparse's interface should be familiar with anyone accustomed to
70getopt. It's nearly a drop-in replacement. The option string has the
71same format and the parser struct fields have the same names as the
72getopt global variables (optarg, optind, optopt).
73
74The long option parser `optparse_long()` API is very similar to GNU's
75`getopt_long()` and can serve as a portable, embedded replacement.
76
77Optparse does not allocate memory. Furthermore, Optparse has no
78dependencies, including libc itself, so it can be used in situations
79where the standard C library cannot.
80
81See `optparse.h` for full API documentation.
82
83## Example Usage
84
85Here's a traditional getopt setup.
86
87~~~c
88#include <stdio.h>
89#include <stdlib.h>
90#include <stdbool.h>
91#include <getopt.h>
92
93int main(int argc, char **argv)
94{
95 bool amend = false;
96 bool brief = false;
97 const char *color = "white";
98 int delay = 0;
99
100 int option;
101 while ((option = getopt(argc, argv, "abc:d::")) != -1) {
102 switch (option) {
103 case 'a':
104 amend = true;
105 break;
106 case 'b':
107 brief = true;
108 break;
109 case 'c':
110 color = optarg;
111 break;
112 case 'd':
113 delay = optarg ? atoi(optarg) : 1;
114 break;
115 case '?':
116 exit(EXIT_FAILURE);
117 }
118 }
119
120 /* Print remaining arguments. */
121 for (; optind < argc; optind++)
122 printf("%s\n", argv[optind]);
123 return 0;
124}
125~~~
126
127Here's the same thing translated to Optparse.
128
129~~~c
130#include <stdio.h>
131#include <stdlib.h>
132#include <stdbool.h>
133#define OPTPARSE_IMPLEMENTATION
134#define OPTPARSE_API static
135#include "optparse.h"
136
137int main(int argc, char **argv)
138{
139 bool amend = false;
140 bool brief = false;
141 const char *color = "white";
142 int delay = 0;
143
144 char *arg;
145 int option;
146 struct optparse options;
147
148 optparse_init(&options, argv);
149 while ((option = optparse(&options, "abc:d::")) != -1) {
150 switch (option) {
151 case 'a':
152 amend = true;
153 break;
154 case 'b':
155 brief = true;
156 break;
157 case 'c':
158 color = options.optarg;
159 break;
160 case 'd':
161 delay = options.optarg ? atoi(options.optarg) : 1;
162 break;
163 case '?':
164 fprintf(stderr, "%s: %s\n", argv[0], options.errmsg);
165 exit(EXIT_FAILURE);
166 }
167 }
168
169 /* Print remaining arguments. */
170 while ((arg = optparse_arg(&options)))
171 printf("%s\n", arg);
172 return 0;
173}
174~~~
175
176And here's a conversion to long options.
177
178~~~c
179#include <stdio.h>
180#include <stdlib.h>
181#include <stdbool.h>
182#define OPTPARSE_IMPLEMENTATION
183#define OPTPARSE_API static
184#include "optparse.h"
185
186int main(int argc, char **argv)
187{
188 struct optparse_long longopts[] = {
189 {"amend", 'a', OPTPARSE_NONE},
190 {"brief", 'b', OPTPARSE_NONE},
191 {"color", 'c', OPTPARSE_REQUIRED},
192 {"delay", 'd', OPTPARSE_OPTIONAL},
193 {0}
194 };
195
196 bool amend = false;
197 bool brief = false;
198 const char *color = "white";
199 int delay = 0;
200
201 char *arg;
202 int option;
203 struct optparse options;
204
205 optparse_init(&options, argv);
206 while ((option = optparse_long(&options, longopts, NULL)) != -1) {
207 switch (option) {
208 case 'a':
209 amend = true;
210 break;
211 case 'b':
212 brief = true;
213 break;
214 case 'c':
215 color = options.optarg;
216 break;
217 case 'd':
218 delay = options.optarg ? atoi(options.optarg) : 1;
219 break;
220 case '?':
221 fprintf(stderr, "%s: %s\n", argv[0], options.errmsg);
222 exit(EXIT_FAILURE);
223 }
224 }
225
226 /* Print remaining arguments. */
227 while ((arg = optparse_arg(&options)))
228 printf("%s\n", arg);
229
230 return 0;
231}
232~~~
233