Debian Codegraph @

md2html/cmdline.h

raw
1 /*
2 * C Reusables
3 * <http://github.com/mity/c-reusables>
4 *
5 * Copyright (c) 2017 Martin Mitáš
6 *
7 * Permission is hereby granted, free of charge, to any person obtaining a
8 * copy of this software and associated documentation files (the "Software"),
9 * to deal in the Software without restriction, including without limitation
10 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
11 * and/or sell copies of the Software, and to permit persons to whom the
12 * Software is furnished to do so, subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
18 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
22 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
23 * IN THE SOFTWARE.
24 */
25
26 #ifndef CRE_CMDLINE_H
27 #define CRE_CMDLINE_H
28
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32
33
34 /* The option may have an argument. (Affects only long option.) */
35 #define CMDLINE_OPTFLAG_OPTIONALARG 0x0001
36
37 /* The option must have an argument.
38 * Such short option cannot be grouped within single '-abc'. */
39 #define CMDLINE_OPTFLAG_REQUIREDARG 0x0002
40
41 /* Enable special compiler-like mode for the long option.
42 *
43 * Note ::shortname is not supported with this flag. CMDLINE_OPTION::shortname
44 * is silently ignored if the flag is used.
45 *
46 * With this flag, CMDLINE_OPTION::longname is treated differently as follows:
47 *
48 * 1. The option matches if the CMDLINE_OPTION::longname is the exact prefix
49 * of the argv[i] from commandline.
50 *
51 * 2. Double dash ("--") is not automatically prepended to
52 * CMDLINE_OPTION::longname. (If you desire any leading dash, include it
53 * explicitly in CMDLINE_OPTION initialization.)
54 *
55 * 3. An argument is required (the flag CMDLINE_OPTFLAG_COMPILERLIKE implicitly
56 * implies also the flag CMDLINE_OPTFLAG_REQUIREDARG).
57 *
58 * But there is no "=" delimiter expected between the option and argument,
59 * however there is an optional whitespace allowed.
60 *
61 * This offers similar semantics to common compiler options. For example:
62 * -DDEBUG=0 (If -D is the option, DEBUG=0 is the argument)
63 * -Isrc/include (If -I is the option, src/include is the argument)
64 * -I src/include (Equivalent to the above)
65 * -isystem /usr/include (If -isystem is the option, /usr/include is the argument)
66 * -lmath (If -l is the option, math is the argument)
67 */
68 #define CMDLINE_OPTFLAG_COMPILERLIKE 0x0004
69
70
71 /* Special (reserved) option IDs. Do not use these for any CMDLINE_OPTION::id.
72 * See documentation of cmdline_read() to get info about their meaning.
73 */
74 #define CMDLINE_OPTID_NONE 0
75 #define CMDLINE_OPTID_UNKNOWN (-0x7fffffff + 0)
76 #define CMDLINE_OPTID_MISSINGARG (-0x7fffffff + 1)
77 #define CMDLINE_OPTID_BOGUSARG (-0x7fffffff + 2)
78
79
80 typedef struct CMDLINE_OPTION {
81 char shortname; /* Short (single char) option or 0. */
82 const char* longname; /* Long name (after "--") or NULL. */
83 int id; /* Non-zero ID to identify the option in the callback; or zero to denote end of options list. */
84 unsigned flags; /* Bitmask of CMDLINE_OPTFLAG_xxxx flags. */
85 } CMDLINE_OPTION;
86
87
88 /* Parses all options and their arguments as specified by argc, argv accordingly
89 * with the given options (except argv[0] which is ignored).
90 *
91 * The caller must specify the list of supported options in the 1st parameter
92 * of the function. The array must end with a record whose CMDLINE_OPTION::id
93 * is set to zero.
94 *
95 * The provided callback function is called for each option on the command
96 * line so that:
97 *
98 * -- the "id" refers to the id of the option as specified in options[].
99 *
100 * -- the "arg" specifies an argument of the option or NULL if none is
101 * provided.
102 *
103 * -- the "userdata" just allows to pass in some caller's context into
104 * the callback.
105 *
106 * Special cases (recognized via special "id" value) are reported to the
107 * callback as follows:
108 *
109 * -- If id is CMDLINE_OPTID_NONE, the callback informs about a non-option,
110 * also known as a positional argument.
111 *
112 * All argv[] tokens which are not interpreted as an options or an argument
113 * of any option fall into this category.
114 *
115 * Usually, programs interpret these as file paths to process.
116 *
117 * -- If id is CMDLINE_OPTID_UNKNOWN, the corresponding argv[] looks like an
118 * option but it is not found in the options[] passed to cmdline_read().
119 *
120 * The callback's parameter arg specifies the guilty command line token.
121 * Usually, program writes down an error message and exits.
122 *
123 * -- If id is CMDLINE_OPTID_MISSINGARG, the given option is valid but its
124 * flag in options[] requires an argument; yet there is none on the
125 * command line.
126 *
127 * The callback's parameter arg specifies the guilty option name.
128 * Usually, program writes down an error message and exits.
129 *
130 * -- If id is CMDLINE_OPTID_BOGUSARG, the given option is valid but its
131 * flag in options[] does not expect an argument; yet the command line
132 * does provide one.
133 *
134 * The callback's parameter arg specifies the guilty option name.
135 * Usually, program writes down an error message and exits.
136 *
137 * On success, zero is returned.
138 *
139 * If the callback returns a non-zero, cmdline_read() aborts immediately and
140 * cmdline_read() propagates the same return value to the caller.
141 */
142
143 int cmdline_read(const CMDLINE_OPTION* options, int argc, char** argv,
144 int (*callback)(int /*id*/, const char* /*arg*/, void* /*userdata*/),
145 void* userdata);
146
147
148 #ifdef __cplusplus
149 } /* extern "C" { */
150 #endif
151
152 #endif /* CRE_CMDLINE_H */