libutil

optget: Add manpage

Diffstat

2 files changed, 57 insertions, 1 deletions

diff --git a/README.md b/README.md
index ed382de..827e073 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ OMKOV lib is a lightweight generic library to be included locally in projects.
 | ---------------- | --------------------------------------------------- |
 | error            | Error reporting functions                           |
 | mode             | Parse numeric or symbolic POSIX modes               |
-| optget           | Parse arguments                                     |
+| optget           | Parse command line options                          |
 
 ## Build Instructions
 
diff --git a/man/optget.3 b/man/optget.3
new file mode 100644
index 0000000..7de1590
--- /dev/null
+++ b/man/optget.3
@@ -0,0 +1,56 @@
+.TH OPTGET 3 2020-11-01 "OMKOV lib" "OMKOV lib 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
+All rights reserved.
+OMKOV Permissive Licence (https://www.omkov.net/OLPE)
+.fi