1= nng_opts_parse(3supp)
2//
3// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
4// Copyright 2018 Capitar IT Group BV <info@capitar.com>
5//
6// This document is supplied under the terms of the MIT License, a
7// copy of which should be located in the distribution where this
8// file was obtained (LICENSE.txt).  A copy of the license may also be
9// found online at https://opensource.org/licenses/MIT.
10//
11
12== NAME
13
14nng_opts_parse - parse command line options
15
16== SYNOPSIS
17
18[source, c]
19----
20#include <nng/nng.h>
21#include <nng/supplemental/util/options.h>
22
23typedef struct nng_optspec {
24    const char *o_name;  // Long style name (may be NULL for short only)
25    int         o_short; // Short option (no clustering!)
26    int         o_val;   // Value stored on a good parse (>0)
27    bool        o_arg;   // Option takes an argument if true
28} nng_optspec;
29
30int nng_opts_parse(int argc, char *const *argv, const nng_optspec *spec, int *val, char **arg, int *idx);
31----
32
33== DESCRIPTION
34
35The `nng_opts_parse()` is function is a supplemental function intended to
36facilitate parsing command line arguments.
37This function exists largely to stand in for `getopt()` from POSIX
38systems, but it is available everywhere that _NNG_ is, and it includes
39some capabilities missing from `getopt()`.
40
41The function parses arguments from `main()` (using _argc_ and _argv_),
42starting at the index referenced by _idx_.
43(New invocations typically set the value pointed to by _idx_ to 1.)
44
45Options are parsed as specified by _spec_ (see <<Option Specification>>.)
46The value of the parsed option will be stored at the address indicated by
47_val_, and the value of _idx_ will be incremented to reflect the next
48option to parse.
49
50TIP: For using this to parse command-line like strings that do not include
51the command name itself, set the value referenced by _idx_ to zero
52instead of one.
53
54If the option had an argument, a pointer to that is returned at the address
55referenced by _arg_.
56
57This function should be called repeatedly, until it returns either -1
58(indicating the end of options is reached) or a non-zero error code is
59returned.
60
61=== Option Specification
62
63The calling program must first create an array of `nng_optspec` structures
64describing the options to be supported.
65This structure has the following members:
66
67`o_name`::
68
69  The long style name for the option, such as "verbose".
70  This will be parsed on the command line when it is prefixed with two dashes.
71  It may be `NULL` if only a short option is to be supported.
72
73`o_short`::
74
75  This is a single letter (at present only ASCII letters are supported).
76  These options appear as just a single letter, and are prefixed with a single dash on the command line.
77  The use of a slash in lieu of the dash is _not_ supported, in order to avoid confusion with path name arguments.
78  This value may be set to 0 if no short option is needed.
79
80`o_val`::
81
82  This is a numeric value that is unique to this option.
83  This value is assigned by the application program, and must be non-zero
84  for a valid option.
85  If this is zero, then it indicates the end of the specifications, and the
86  rest of this structure is ignored.
87  The value will be returned to the caller in _val_ by `nng_opts_parse()` when
88  this option is parsed from the command line.
89
90`o_arg`::
91
92  This value should be set to `true` if the option should take an argument.
93
94=== Long Options
95
96Long options are parsed from the _argv_ array, and are indicated when
97the element being scanned starts with two dashes.
98For example, the "verbose" option would be specified as `--verbose` on
99the command line.
100If a long option takes an argument, it can either immediately follow
101the option as the next element in _argv_, or it can be appended to
102the option, separated from the option by an equals sign (`=`) or a
103colon (`:`).
104
105=== Short Options
106
107Short options appear by themselves in an _argv_ element, prefixed by a
108dash (`-`).
109If the short option takes an argument, it can either be appended in the
110same element of _argv_, or may appear in the next _argv_ element.
111
112NOTE: Option clustering, where multiple options can be crammed together in
113a single _argv_ element, is not supported by this function (yet).
114
115=== Prefix Matching
116
117When using long options, the parser will match if it is equal to a prefix
118of the `o_name` member of a option specification, provided that it do so
119unambiguously (meaning it must not match any other option specification.)
120
121== EXAMPLE
122
123The following program fragment demonstrates this function.
124
125[source, c]
126----
127    enum { OPT_LOGFILE, OPT_VERBOSE };
128    char *logfile; // options to be set
129    bool verbose;
130
131    static nng_optspec specs[] = {
132        {
133            .o_name = "logfile",
134            .o_short = 'D',
135            .o_val = OPT_LOGFILE,
136            .o_arg = true,
137        }, {
138            .o_name = "verbose",
139            .o_short = 'V',
140            .o_val = OPT_VERBOSE,
141            .o_arg = false,
142        }, {
143            .o_val = 0; // Terminate array
144        }
145    };
146
147    for (int idx = 1;;) {
148        int rv, opt;
149        char *arg;
150        rv = nng_opts_parse(argc, argv, specs, &opt, &arg, &idx);
151        if (rv != 0) {
152            break;
153        }
154        switch (opt) {
155        case OPT_LOGFILE:
156            logfile = arg;
157            break;
158        case OPT_VERBOSE:
159            verbose = true;
160            break;
161        }
162    }
163    if (rv != -1) {
164        printf("Options error: %s\n", nng_strerror(rv));
165        exit(1);
166    }
167----
168
169== RETURN VALUES
170
171This function returns 0 if an option parsed correctly, -1 if
172no more options are available to be parsed, or an error number otherwise.
173
174== ERRORS
175
176[horizontal]
177`NNG_EAMBIGUOUS`:: Parsed option matches more than one specification.
178`NNG_ENOARG`:: Option requires an argument, but one is not present.
179`NNG_EINVAL`:: An invalid (unknown) argument is present.
180
181== SEE ALSO
182
183[.text-left]
184xref:nng_strerror.3.adoc[nng_strerror(3)],
185xref:nng.7.adoc[nng(7)]
186