.TH OPTGET 3 2022-03-06 "libutil" "libutil Programmer's Manual"
.SH NAME
optget \(em parse command line options
.SH SYNOPSYS
#include "optget.h"
.PP
extern const struct opt \fIOPTGET_INIT\fR;
.PP
int \fBoptget\fR(struct opt *\fIopt\fB, char *\fIav\fB[], int \fIflags\fB);
.SH DESCRIPTION
The \fBoptget\fR() function parses command line options. The parameter \fIopt\fR
is a pointer to an opt struct which contains variables related to a parse run.
The parameter \fIav\fR is the argument vertex as passed to \fImain\fR(). The
paramter \fIflags\fR is a set of binary flags that may customise the parse
execution.
.PP
If the first character of \fIopt.str\fR is not a colon character ':', then an
error message will be printed to standard error in the event of an error.
.PP
The \fBoptget\fR() function will return the value of the next option, if one is
found that is either in \fIopt.str\fR or \fIopt.lops\fR for short and long
options respectively. Once all options have been parsed, \fBoptget\fR() will
return -1. If an invalid option is parsed, \fBoptget\fR() will return a question
mark character '?', and if an option is parsed that requires an argument but one
hasnt been specified then \fBoptget\fR() will return a colon character ':'.
.PP
If an option is parsed, \fIopt.ind\fR will contain the option index,
\fIopt.opt\fR will contain the option character if the option is short, or 0
otherwise, \fIopt.lop\fR will contain the option string if the option is long,
or NULL otherwise, \fIopt.arg\fR will contain the option argument if one is
present, or NULL otherwise.
.SH EXAMPLE
.nf
static struct lop lops[] = {
	{ "help",    ARG_NUL, 256 },
	{ "version", ARG_NUL, 257 },
	{ NULL, 0, 0 }
};

int main(int ac, char *av[]) { A0 = av[0];
	struct opt opt = OPTGET_INIT; opt.str = "ab"; opt.lops = lops;
	for (int o; (o = optget(&opt, av, 1)) != -1;) switch (o) {
	case 'a': { printf("'-a' parsed\\n"); break; }
	case 'b': { printf("'-b' parsed\\n"); break; }
	case 256: { hlp(); return 0; }
	case 257: { ver(); return 0; }
	default: { return 1; }
	} return 0;
}
.fi
.SH COPYRIGHT
.nf
Copyright (C) 2020, Jakob Wakeling
MIT Licence (https://opensource.org/licenses/MIT)
.fi