From 9d3fd447f36e1a144a40037d559a92562d120703 Mon Sep 17 00:00:00 2001
From: Andre Noll <maan@tuebingen.mpg.de>
Date: Sat, 22 Oct 2016 15:47:12 +0200
Subject: [PATCH] The long option parser for subcommands (lopsub).

This library was under development for over a year and is now ready
for prime time. The code is believed to be mature and no bugs are
known at this time. The API is fully documented and stable, and no
new features are planned. Future fixes and enhancements will take
backwards compatibility into account.

The code used to be part of the paraslash package, but has been
moved to its own repository. All prior commits have been discarded,
so this repository contains only the final result as a single commit.

The input files for the lopsubgen utility and the config file parser
are based on flex. The API documentation is created with gendoc.m4,
a simple m4 file which is part of this repository.

Documentation includes the three man pages lopsub.7, lopsubgen.1 and
lopsub.suite.5 which describe different aspects of the library. There
is also an example application called lopsubex which illustrates
various features of the library.
---
 .gitignore        |   12 +
 Makefile          |  113 ++++
 README            |   12 +
 config_file.l     |  270 ++++++++
 gendoc/gendoc.m4  |  265 ++++++++
 lopsub-internal.h |  219 ++++++
 lopsub-suite.5.m4 |  446 +++++++++++++
 lopsub.7.m4       |  183 ++++++
 lopsub.c          | 1610 +++++++++++++++++++++++++++++++++++++++++++++
 lopsub.h.m4       |  806 +++++++++++++++++++++++
 lopsubex.c        |  332 ++++++++++
 lopsubex.suite    |  392 +++++++++++
 lopsubgen.l       |  481 ++++++++++++++
 lopsubgen.suite   |  118 ++++
 lsg.c             |  812 +++++++++++++++++++++++
 lsg.h             |   70 ++
 version-gen.sh    |   25 +
 web/footer.html   |    2 +
 web/header.html   |   46 ++
 web/lopsub.png    |  Bin 0 -> 11493 bytes
 20 files changed, 6214 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 Makefile
 create mode 100644 README
 create mode 100644 config_file.l
 create mode 100644 gendoc/gendoc.m4
 create mode 100644 lopsub-internal.h
 create mode 100644 lopsub-suite.5.m4
 create mode 100644 lopsub.7.m4
 create mode 100644 lopsub.c
 create mode 100644 lopsub.h.m4
 create mode 100644 lopsubex.c
 create mode 100644 lopsubex.suite
 create mode 100644 lopsubgen.l
 create mode 100644 lopsubgen.suite
 create mode 100644 lsg.c
 create mode 100644 lsg.h
 create mode 100755 version-gen.sh
 create mode 100644 web/footer.html
 create mode 100644 web/header.html
 create mode 100644 web/lopsub.png

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..be0f3e3
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,12 @@
+**/*.o
+*.lsg.*
+*.[1-9]
+config_file.c
+lopsubgen.c
+version.c
+lopsub.h
+liblopsub.a
+lopsubex
+lopsubgen
+lopsubgen-stage1
+web/*.html
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..4278505
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,113 @@
+# Implicit rules are implemented in make as suffix rules. The following rule
+# empties the suffix list to disable the predefined implicit rules. This
+# increases performance and avoids hard-to-debug behaviour.
+.SUFFIXES:
+MAKEFLAGS += -Rr
+ifeq ("$(origin CC)", "default")
+        CC := cc
+endif
+
+PREFIX ?= /usr/local
+M4 := m4
+LN := ln -f
+LEX := lex
+RM := rm -f
+AR := ar
+GROFF := groff
+CP := cp
+INSTALL := install
+
+DATE := $(shell date '+%B %Y')
+GIT_VERSION := $(shell ./version-gen.sh)
+
+m4_man_pages := lopsub-suite.5 lopsub.7
+all := $(m4_man_pages) liblopsub.a lopsubgen lopsubgen.1 \
+	lopsubex lopsubex.1
+all: $(all)
+
+# deps
+lopsubgen.o: lsg.h
+lopsub.o lsg.o: lopsub.h lopsub-internal.h
+lsg.o: lopsubgen.lsg.h lopsub-internal.h
+lopsubex.o: lopsubex.lsg.h lopsub.h
+config_file.c: lopsub-internal.h lopsub.h
+version.o: version.c
+
+# m4 stuff
+gendoc := gendoc/gendoc.m4
+%.h: %.h.m4 $(gendoc)
+	$(M4) -DOUTPUT_MODE=C $(gendoc) $< > $@
+$(m4_man_pages): %: %.m4 version.c
+	$(M4) -DGIT_VERSION=$(GIT_VERSION) -DDATE="$(DATE)" $< > $@
+
+# flex
+%.c: %.l
+	$(LEX) -o $@ $<
+
+# lopsubgen
+lopsubgen.lsg.c lopsubgen.lsg.h: lopsubgen.suite lopsubgen-stage1 \
+		lopsub-internal.h
+	./lopsubgen-stage1 < $<
+%.lsg.c: %.suite lopsubgen
+	./lopsubgen --gen-c < $<
+%.lsg.h: %.suite lopsubgen
+	./lopsubgen --gen-header < $<
+%.1: %.suite lopsubgen
+	./lopsubgen --gen-man=$@ --version-string $(GIT_VERSION) < $<
+
+# compiling
+lsg1_objs := lopsubgen.o lsg1.o version.o
+lsg_objs := lopsubgen.o lsg.o lopsubgen.lsg.o lopsub.o version.o
+liblopsub_objs := config_file.o lopsub.o version.o
+lopsubex_objs := lopsubex.o lopsubex.lsg.o version.o
+
+$(lsg_objs) $(liblopsub_objs) $(lopsubex_objs): %.o: %.c
+lopsubgen.o config_file.o:
+	$(CC) -g -c -o $@ ${@:.o=.c}
+lsg1.o: lsg.c lsg.h
+	$(CC) -g -DSTAGE1 -Wall -g -c $< -o $@
+%.o: %.c
+	$(CC) -Wall -I. -g -c -o $@ $<
+
+# linking
+lopsubgen-stage1: $(lsg1_objs)
+	$(CC) -Wall -g $(lsg1_objs) -o $@
+lopsubgen: $(lsg_objs)
+	$(CC) -Wall -g -o $@ $(lsg_objs)
+liblopsub.a: $(liblopsub_objs)
+	$(AR) -rcs $@ $^
+lopsubex: $(lopsubex_objs) liblopsub.a
+	$(CC) -Wall -g -o $@ $^
+
+# web
+html := $(addprefix web/, $(addsuffix .html, \
+	index lopsub-api lopsubgen.1 lopsubex.1 $(m4_man_pages)))
+$(html): $(addprefix web/, $(addsuffix .html, header footer))
+
+www: $(html)
+
+web/lopsub-api.html: lopsub.h.m4
+	$(M4) -DOUTPUT_MODE=HTML web/header.html $(gendoc) \
+		$< web/footer.html > $@
+web/index.html: web/lopsub.7.html
+	$(LN) -s $(notdir $<) $@
+web/%.html: %
+	$(CP) web/header.html $@
+	$(GROFF) -m man -Thtml $< | sed -e '1,/^<body>/d' >> $@
+
+install: liblopsub.a lopsub.7
+	$(INSTALL) -d $(PREFIX)/lib $(PREFIX)/include $(PREFIX)/man/man1 \
+		 $(PREFIX)/man/man5 $(PREFIX)/man/man7 $(PREFIX)/bin
+	$(INSTALL) -m 755 liblopsub.a $(PREFIX)/lib
+	$(INSTALL) -m 755 lopsubgen $(PREFIX)/bin
+	$(INSTALL) -m 644 lopsub.h $(PREFIX)/include
+	$(INSTALL) -m 644 lopsub-internal.h $(PREFIX)/include
+	$(INSTALL) -m 644 lopsubgen.1 $(PREFIX)/man/man1
+	$(INSTALL) -m 644 lopsub-suite.5 $(PREFIX)/man/man5
+	$(INSTALL) -m 644 lopsub.7 $(PREFIX)/man/man7
+
+clean:
+	$(RM) $(all) $(html) *.o *.man *.lsg.c *.lsg.h \
+		lopsubgen.c config_file.c lopsubgen-stage1 \
+		lopsub.h lopsub.7 lopsub-suite.5 version.c
+
diff --git a/README b/README
new file mode 100644
index 0000000..a6ffa0b
--- /dev/null
+++ b/README
@@ -0,0 +1,12 @@
+Lopsub, the long option parser for subcommands
+----------------------------------------------
+
+Documentation is available at
+
+	http://people.tuebingen.mpg.de/maan/lopsub
+
+Alternatively, run
+
+	man -l ./lopsub.7.m4
+
+to show build and installation instructions.
diff --git a/config_file.l b/config_file.l
new file mode 100644
index 0000000..38691b7
--- /dev/null
+++ b/config_file.l
@@ -0,0 +1,270 @@
+/*
+ * Copyright (C) 2016 Andre Noll <maan@tuebingen.mpg.de>
+ *
+ * Licensed under the LGPL v3, see http://www.gnu.org/licenses/lgpl-3.0.html
+ */
+
+%option noyywrap
+%option stack
+%option never-interactive
+%option yylineno
+
+%x SC_ARG
+%s SC_SCANNING
+
+IDENTIFIER [a-zA-Z]+[a-zA-Z0-9_-]*
+EQUALS [[:space:]]*=[[:space:]]*
+OPTION [a-zA-Z]+[a-zA-Z0-9_-]*
+
+%{
+	#include <stdlib.h>
+	#include <ctype.h>
+	#include <assert.h>
+	#include <stdbool.h>
+	#include <inttypes.h>
+	#include "lopsub-internal.h"
+	#include "lopsub.h"
+
+	static int rargc;
+	static char **rargv;
+	static const char *subcommand;
+
+	static int expand_result(void)
+	{
+		int nargc = rargc + 1;
+		char **nrargv = realloc(rargv, (nargc + 1) * sizeof(char *));
+
+		if (!nrargv)
+			return -E_LLS_NOMEM;
+		rargc = nargc;
+		rargv = nrargv;
+		rargv[rargc] = NULL;
+		return 1;
+	}
+
+	static int add_option(void)
+	{
+		int ret;
+		unsigned n;
+
+		for (n = 0; n < yyleng; n++)
+			if (!isalnum(yytext[n]) && !(yytext[n] == '-'))
+				break;
+		assert(n > 0);
+		ret = expand_result();
+		if (ret < 0)
+			return ret;
+		rargv[rargc - 1] = malloc(n + 2 + 1);
+		if (!rargv[rargc - 1])
+			return -E_LLS_NOMEM;
+		rargv[rargc - 1][0] = rargv[rargc - 1][1] = '-';
+		memcpy(rargv[rargc - 1] + 2, yytext, n);
+		rargv[rargc - 1][n + 2] = '\0';
+		return 1;
+	}
+
+	static int parse_arg(char **result)
+	{
+		bool backslash = false, quote = false;
+		const char *in;
+		char *out;
+		int ret;
+
+		*result = malloc(yyleng + 1);
+		if (!*result)
+			return -E_LLS_NOMEM;
+		for (in = yytext, out = *result; *in; in++) {
+			if (*in == '\\') {
+				if (!backslash) {
+					backslash = true;
+					continue;
+				}
+			} else if (*in == 'n' || *in == 't') {
+				if (backslash) { /* \n or \t */
+					*out++ = (*in == 'n')? '\n' : '\t';
+					backslash = false;
+					continue;
+				}
+			} else if (*in == '"') {
+				if (!backslash) {
+					quote = !quote;
+					continue;
+				}
+			} else if (isspace(*in)) {
+				if (!backslash && !quote)
+					break;
+			}
+			/* copy the character */
+			*out++ = *in;
+			backslash = false;
+		}
+		ret = -E_LLS_TRAILING_BACKSLASH;
+		if (backslash)
+			goto fail;
+		ret = -E_LLS_UNMATCHED_QUOTE;
+		if (quote)
+			goto fail;
+		/* look at first non-space character */
+		for (; *in; in++) {
+			if (isspace(*in))
+				continue;
+			if (*in == '#')
+				break;
+			ret = -E_LLS_TRAILING_GARBAGE;
+			goto fail;
+		}
+		/* success */
+		*out = '\0';
+		return out - *result;
+	fail:
+		assert(ret < 0);
+		free(*result);
+		*result = NULL;
+		return ret;
+	}
+%}
+
+%%
+
+ /* skip comments and whitespace */
+^[[:space:]]*#.*\n ;
+[[:space:]]|\n+ ;
+
+<INITIAL,SC_SCANNING>\[[[:space:]]*{IDENTIFIER}[[:space:]]*\][[:space:]]*\n {
+	int i, j;
+
+	assert(yytext[0] == '[');
+	if (!subcommand)
+		return 0;
+	for (i = 1; i < yyleng; i++)
+		if (!isspace(yytext[i]))
+			break;
+	for (j = i; j < yyleng; j++)
+		if (yytext[j] == ']' || isspace(yytext[j]))
+			break;
+	assert(j < yyleng);
+	yytext[j] = '\0';
+	if (strcmp(yytext + i, subcommand))
+		BEGIN(INITIAL);
+	else
+		BEGIN(SC_SCANNING);
+}
+
+<SC_SCANNING>{OPTION}[[:space:]]*\n add_option();
+
+<SC_SCANNING>{OPTION}({EQUALS}|[[:space:]]+) {
+	int ret = add_option();
+
+	if (ret < 0)
+		return ret;
+	BEGIN(SC_ARG);
+}
+
+<SC_ARG>.*\n {
+	const char *opt = rargv[rargc - 1];
+	char *arg, *result;
+	size_t opt_len = strlen(opt), arg_len;
+	int ret = parse_arg(&arg);
+
+	if (ret < 0)
+		return ret;
+	arg_len = ret;
+	result = malloc(opt_len + arg_len + 2);
+	if (!result)
+		return -E_LLS_NOMEM;
+	strcpy(result, opt);
+	result[opt_len] = '=';
+	strcpy(result + opt_len + 1, arg);
+	free(arg);
+	result[opt_len + arg_len + 1] = '\0';
+	free(rargv[rargc - 1]);
+	rargv[rargc - 1] = result;
+	BEGIN(SC_SCANNING);
+}
+
+<INITIAL>.*\n {}
+
+ /* This rule runs iff none of the above patterns matched */
+. {return -1;}
+%%
+
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <fcntl.h>
+#include <stdio.h>
+
+int lls_convert_config(const char *buf, size_t nbytes, const char *subcmd,
+		 char ***result, char **errctx)
+{
+	int ret;
+	YY_BUFFER_STATE yybs;
+
+	*result = NULL;
+	if (errctx)
+		*errctx = NULL;
+	subcommand = subcmd;
+	if (!subcmd)
+		BEGIN(SC_SCANNING);
+	else
+		BEGIN(INITIAL);
+	yybs = yy_scan_bytes(buf, nbytes);
+	if (!yybs)
+		return -E_LLS_YY_SCAN;
+	rargc = 1;
+	rargv = malloc((rargc + 1) * sizeof(char *));
+	if (!rargv)
+		return -E_LLS_NOMEM;
+	rargv[0] = strdup(__FUNCTION__);
+	if (!rargv[0]) {
+		free(rargv);
+		return -E_LLS_NOMEM;
+	}
+	rargv[1] = NULL;
+	ret = yylex();
+	yy_delete_buffer(yybs);
+	if (ret >= 0) {
+		*result = rargv;
+		return rargc;
+	}
+	if (errctx) {
+		*errctx = malloc(100);
+		if (*errctx)
+			sprintf(*errctx, "error at line %d", yyget_lineno());
+	}
+	for (; rargc >= 0; rargc--)
+		free(rargv[rargc]);
+	free(rargv);
+	*result = NULL;
+	return -E_LLS_YY_LEX;
+}
+
+void lls_free_argv(char **argv)
+{
+	int i;
+
+	if (!argv)
+		return;
+	for (i = 0; argv[i]; i++)
+		free(argv[i]);
+	free(argv);
+}
+#if 0
+int main(void)
+{
+	char buf[100 * 1024];
+	int ret, len, i, argc;
+	char **argv;
+
+	ret = read(STDIN_FILENO, buf, sizeof(buf));
+	if (ret <= 0)
+		exit(EXIT_FAILURE);
+	len = ret;
+	ret = lls_convert_config(buf, len, NULL, &argv, NULL);
+	if (ret < 0)
+		exit(EXIT_FAILURE);
+	argc = ret;
+	for (i = 0; i < argc; i++)
+		printf("argv[%d]: %s\n", i, rargv[i]);
+	return EXIT_SUCCESS;
+}
+#endif
diff --git a/gendoc/gendoc.m4 b/gendoc/gendoc.m4
new file mode 100644
index 0000000..6c3099c
--- /dev/null
+++ b/gendoc/gendoc.m4
@@ -0,0 +1,265 @@
+changequote(`«', `»')dnl
+define(«IFNBLANK», «ifelse(translit(««$1»», «
+	 »), «», «», «$2»)»)dnl
+define(«DECL_ARGLIST», «ifelse(«$#», «2», «$1»,
+	«$1, DECL_ARGLIST(shift(shift($@)))»)»)dnl
+define(«LINK_COUNT», 0)
+define(«STRIP_LEFT», «patsubst(«$1», «^\s+», «»)»)dnl
+define(«STRIP_RIGHT», «patsubst(«$1», «\s+$», «»)»)dnl
+define(«STRIP», «STRIP_LEFT(«STRIP_RIGHT(«$1»)»)»)dnl
+ifelse(OUTPUT_MODE, «C», «dnl --------- C output
+define(«COMPOUND_MEMBERS», «ifelse(«$#», «1», «»,
+	«	$1; /* STRIP_RIGHT(«$2») */
+COMPOUND_MEMBERS(shift(shift($@)))»)»)dnl
+define(«DECL_ARG_TEXT», «ifelse(«$#», «1», «», «IFNBLANK(«$2», «
+		$1: $2«»DECL_ARG_TEXT(shift(shift($@)))»)»)»)dnl
+define(«DECLARE_FUNCTION», «/* $2 */
+$6 $1(DECL_ARGLIST($4));
+/*dnl
+$3«»dnl
+DECL_ARG_TEXT($4)dnl
+IFNBLANK(«$5», «$5»)dnl
+IFNBLANK(«$7», «
+		Return ($6): STRIP_RIGHT(«$7»)»
+)dnl
+IFNBLANK(«$8», «$8»)dnl
+*/»)dnl
+define(«STATEMENT», «/* $2 */
+$1;
+IFNBLANK(«$3», «/*STRIP_RIGHT(«$3»)
+*/dnl
+»)dnl
+»)dnl
+define(«DECLARE_COMPOUND», «/* $2 */
+$1 {
+IFNBLANK(«$3», «/*STRIP_RIGHT(«$3»)
+*/
+»)dnl
+COMPOUND_MEMBERS($4)dnl
+};
+IFNBLANK(«$5», «/*STRIP_RIGHT(«$5»)
+*/
+»)dnl
+»)dnl
+define(«VERBATIM_C», «$1»)dnl
+», OUTPUT_MODE, «HTML», «dnl --------- HTML output
+	define(«FIXUP_LT», «patsubst(«$1», «<», «&lt;»)»)
+	define(«FIXUP_GT», «patsubst(«$1», «>», «&gt;»)»)
+	define(«FIXUP_AMPERSAND», «patsubst(«$1», «&», «&amp;»)»)
+	define(«HANDLE_EMPTY_LINES», «patsubst(«$1», «^\s*$», «</p><p>»)»)
+	define(«FIXUP_HTML», «<p> FIXUP_AMPERSAND(«FIXUP_LT(«FIXUP_GT(
+		«HANDLE_EMPTY_LINES(«$1»)»)»)») </p>»)
+	define(«FORMAT_LIST_HTML», «ifelse(«$#», «1», «», «
+		IFNBLANK(«$2», «<li> <tt>$1</tt>: $2 </li>
+		FORMAT_LIST_HTML(shift(shift($@)))»)»
+	)»)
+	define(«ANCHOR», «
+		<a name = "link_«»LINK_COUNT" </a>
+	»)
+	define(«HREF», «
+		define(«LINK_COUNT», incr(LINK_COUNT))
+		<a href = "«#»link_«»LINK_COUNT"> $1 </a>
+	»)
+	define(«DECLARE_FUNCTION», «
+		divert
+		<tr> <td> <tt> HREF(«$1») </tt> </td> <td> $2 </td> </tr>
+		divert(«1»)
+		ANCHOR
+		<h1> <tt> $6 $1(DECL_ARGLIST($4)) </tt> </h1>
+		<strong> FIXUP_HTML(«$2») </strong>
+		FIXUP_HTML(«$3»)
+		<ul> FORMAT_LIST_HTML($4) </ul>
+		FIXUP_HTML(«$5»)
+		IFNBLANK(«$7», «Return (<tt>$6</tt>):
+			<ul><li> FIXUP_HTML(«$7») </lu></ul>»)
+		FIXUP_HTML(«$8»)
+		<hr>
+	»)
+	define(«STATEMENT», «
+		divert
+		<tr> <td> <tt> HREF(«$1») </tt> </td> <td> $2 </td>
+		divert(«1»)
+		ANCHOR
+		<h1> <tt> $1 </tt> </h1>
+		<strong> FIXUP_HTML(«$2») </strong>
+		<p> FIXUP_HTML(«$3») </p>
+		<hr>
+	»)
+	define(«DECLARE_COMPOUND», «
+		divert
+		<tr> <td> <tt> HREF(«$1») </tt> </td> <td> $2 </td>
+		divert(«1»)
+		ANCHOR
+		<h1> <tt> $1 </tt> </h1>
+		<strong> FIXUP_HTML(«$2») </strong>
+		FIXUP_HTML(«$3»)
+		Members:
+		<ul> FORMAT_LIST_HTML($4) </ul>
+		FIXUP_HTML(«$5»)
+		<hr>
+	»)
+	define(«VERBATIM_C»)
+	divert(«1») </table> <hr> divert
+	<center> <h1> API Reference </h1> </center>
+	<table>
+», OUTPUT_MODE, «ROFF»,«dnl ---------- ROFF output
+.TH
+.SH SYNOPSIS
+define(«VERBATIM_C»)
+define(«FORMAT_LIST_ROFF», «ifelse(«$#», «1», «», «
+IFNBLANK(«$2», «
+.B "STRIP(«$1»)"
+\- STRIP(«$2»)
+.br dnl
+FORMAT_LIST_ROFF(shift(shift($@)))»dnl
+»))»)
+define(«STATEMENT», «dnl
+divert
+.B "$1"
+\- «$2»
+.br dnl
+divert(«1»)
+.SS "«$1»"
+STRIP_LEFT(«$2»)
+STRIP_LEFT(«$3»)dnl
+»)
+define(«DECLARE_FUNCTION», «
+divert
+.BR "«$1»" ()
+\- «$2»
+.br dnl
+divert(«1»)
+.SS "STRIP_RIGHT(«$6») $1(DECL_ARGLIST($4))"
+STRIP(«$2»)
+STRIP(«$3»)
+.IP
+FORMAT_LIST_ROFF($4)
+.P
+STRIP(«$5»)dnl
+IFNBLANK(«$7», «
+.IP
+Return
+.RB ( "$6" ):
+STRIP(«$7»)»
+.P
+)
+STRIP_LEFT(«$8»)
+.P
+»)
+divert(«1»)
+.P
+.SH DESCRIPTION
+divert
+»)dnl
+ifdef(«EXAMPLES», «
+dnl
+dnl
+dnl	Args
+dnl	~~~~
+dnl	(1) name, (2) one-line summary, (3) prolog, (4) args,
+dnl	(5) arg doc, (6) return type, (7) one-line return text, (8) epilog
+DECLARE_FUNCTION(
+	«main»,
+	«The function that is executed on startup.»,
+«
+	1. This function must not be static, it's always linked in.
+
+	Each executable needs to define exactly one main function.
+», «
+	«int argc»,	«usual argument count»,
+	«char **argv»,	«usual argument vector»
+», «
+	2. The arg list may optionally contain an env pointer. In any case
+	argc > 0 and argc < INT_MAX.
+»,
+	«int», «EXIT_SUCCESS or EXIT_FAILURE»,
+«
+	3. On most systems EXIT_FAILURE is 1 and EXIT_SUCCESS is 0.
+»)
+
+DECLARE_FUNCTION(
+	«sync»,
+	«Commit buffer cache to disk.»,
+«
+	Causes all buffered modifications to file metadata and data
+	to be written to the underlying filesystems.
+», «
+	«void»,
+», «
+»,
+	«void»,
+)
+
+DECLARE_FUNCTION(
+	«getchar»,
+	«Input of characters and strings.»,
+«
+	Reads the next character from stdin.
+», «
+	«void»,
+», «
+»,
+	«int», «the character read»,
+«
+	On success the return value is an unsigned char cast to
+	an int. On end of file or error, EOF is returned.
+»
+)
+
+DECLARE_FUNCTION(
+	«free»,
+	«Free dynamic memory.»,
+«
+	The memory space must have been returned by a previous call to
+	malloc(), calloc(), or realloc().
+», «
+	«void *ptr»,	«free the memory space pointed to by ptr»
+», «
+	If ptr is NULL, no operation is performed.
+»,
+	«void»,
+)
+
+dnl	Args
+dnl	~~~~
+dnl	(1) name, (2) one-line summary, (3) prolog, (4) member list, (5) epilog
+DECLARE_COMPOUND(
+	«struct complex»,
+	«Describes a complex number»,
+«
+», «
+	«float re», «real part»,
+	«float im», «imaginary part»,
+»
+)
+DECLARE_COMPOUND(
+	«struct iovec»,
+	«According to POSIX, the <sys/uio.h> header shall define the iovec structure.»,
+«
+	This structure is employed for the readv() and writev() system calls.
+
+	For example, the readv() system call reads into buffers which is
+	described by an array of iovec structures.
+», «
+	«void *iov_base»,	«start address»,
+	«size_t iov_len»,	«number of bytes to transfer»
+», «
+	Buffers are processed in array order.
+»
+)
+dnl	Args
+dnl	~~~~
+dnl	(1) name, (2) one-line summary, (3) description
+STATEMENT(
+	«struct foo_handle»,
+	«Opaque structure that describes one connection to the foo subsystem»,
+«
+	The compiler considers this structure an incomplete type.
+
+	Applications can still declare pointer variables or arrays of pointers
+	to this structure, and compare pointers for equality. However, they
+	will not be able to de-reference a pointer, and can only change the
+	pointer's content by calling some procedure of the library.
+»
+)
+»)
diff --git a/lopsub-internal.h b/lopsub-internal.h
new file mode 100644
index 0000000..99366d3
--- /dev/null
+++ b/lopsub-internal.h
@@ -0,0 +1,219 @@
+/*
+ * Copyright (C) 2016 Andre Noll <maan@tuebingen.mpg.de>
+ *
+ * Licensed under the LGPL v3, see http://www.gnu.org/licenses/lgpl-3.0.html
+ */
+
+#include <inttypes.h>
+
+#define LLS_ABI_VERSION 1
+
+/*
+ * Concat "lls_abi_version" and the ABI version number to produce the name of a
+ * variable. To concat the *expansion* of the macro arguments, we have to use
+ * two levels of macros since otherwise the arguments are not macro-expanded
+ * first.
+ */
+#define LLS_CONCAT_EXPAND(_prefix, _suffix) LLS_CONCAT(_prefix, _suffix)
+#define LLS_CONCAT(_prefix, _suffix) _prefix ## _suffix
+#define LLS_ABI_VERSION_VAR LLS_CONCAT_EXPAND(lls_abi_version, LLS_ABI_VERSION)
+
+/*
+ * Declare the variable. It is defined in lopsub.c, which is part of the
+ * library. The single mission of this variable is to cause an error at link
+ * time on ABI version mismatches. The actual value of the variable is
+ * irrelevant. When the lopsubgen utility translates a suite into a .c file,
+ * the generated C code references this variable, using the *lopsubgen* ABI
+ * version for the reference. Therefore, if the lopsubgen ABI version differs
+ * from the ABI version of the library, the symbol can not be resolved,
+ * resulting in a link error.
+ */
+extern const unsigned LLS_ABI_VERSION_VAR;
+
+/*
+ * Options may have an optional or mandatory argument.
+ *
+ * The lobsubgen command initializes the ->arg_info field of each lls_option
+ * structure from the corresponding line of the .suite file.
+ *
+ * See also: ->arg_info of struct lls_option.
+ */
+enum lls_arg_info {
+	LLS_NO_ARGUMENT, /* Option does not take an argument. */
+	LLS_REQUIRED_ARGUMENT, /* An argument must be given. */
+	LLS_OPTIONAL_ARGUMENT, /* Option takes an optional argument. */
+};
+
+/*
+ * In addition to the argument type, there is a set of flags associated with
+ * each option. All but the LLS_IGNORED flag correspond directly to the
+ * possible values of the flag directive in the suite file.
+ */
+enum lls_option_flag {
+	/* Store each given argument (rather than only the last). */
+	LLS_MULTIPLE = 1,
+	/* It's an error if the option is not given. */
+	LLS_REQUIRED = 2,
+	/* Whether a default value was specified in the suite file. */
+	LLS_HAS_DEFAULT = 4,
+	/* For help text not related to any particular option. */
+	LLS_IGNORED = 8,
+};
+
+/*
+ * Ignored if arg_info is LLS_NO_ARGUMENT. A value of zero means no argument.
+ * We don't need an identifier like LLS_NONE though, because we can test the
+ * arg_info field to tell whether an argument can be supplied.
+ *
+ * See also: union lls_val.
+ */
+enum lls_arg_type {
+	/* Option takes a string argument. */
+	LLS_STRING = 1,
+	/* Signed 32 bit integer. */
+	LLS_INT32,
+	/* Unsigned 32 bit integer. */
+	LLS_UINT32,
+	/* Signed 64 bit integer. */
+	LLS_INT64,
+	/* Unsigned 64 bit integer. */
+	LLS_UINT64,
+};
+
+/*
+ * Stores the argument to an option.
+ *
+ * The default value of an option, the set of possible values for an option and
+ * the actually given value are all stored in an instance of this union.
+ *
+ * To determine the relevant alternative of the union, both the ->arg_type and
+ * the ->values field of the corresponding struct lls_option are
+ * important. For the values array itself, ->arg_type always determines the
+ * alternative of each element in the array. For other objects the following
+ * rule applies. If ->values is not given, ->arg_type determines the
+ * alternative for both ->default_val and lls_opt_result->value. On the other
+ * hand, if ->values is given, the ->uint32_val alternative is the index into
+ * the ->values array that indicates which of the possible values is the
+ * default value (for ->default_val) or was given in the arguments to
+ * lls_parse() (lls_opt_result).
+ */
+union lls_val {
+	char *string_val; /* LLS_STRING */
+	int32_t int32_val; /* LLS_INT32 */
+	uint32_t uint32_val; /* LLS_UINT32 */
+	int64_t int64_val; /* LLS_INT64 */
+	uint64_t uint64_val; /* LLS_UINT64 */
+};
+
+/*
+ * Describes one option of one command of a suite.
+ *
+ * For each option of every command in the .suite file, lopsubgen
+ * generates one structure of this type.
+ */
+struct lls_option {
+	/* The long name (short-only options are not supported). */
+	const char * const name;
+	/* Optional one-character variant. */
+	const char short_opt;
+	/* Mandatory one-line summary. */
+	const char * const summary;
+	/* Whether the option takes an argument, and if it is mandatory. */
+	const enum lls_arg_info arg_info;
+	/* Which alternative of the lls_val union is chosen. */
+	const enum lls_arg_type arg_type;
+	/* Description of the type of values (used for help output). */
+	const char * const typestr;
+	/* See enum lls_option_flag. */
+	const unsigned flags;
+	/* If not given, integer values default to 0, strings to NULL. */
+	const union lls_val default_val;
+	/* Optional multi-line help text. */
+	const char * const help;
+	/* If this is not NULL, only the given values are allowed. */
+	const union lls_val * const values;
+};
+
+/* Describes a command of a suite. */
+struct lls_command {
+	/* Only identifiers are allowed as command names. */
+	const char * const name;
+	/* One line of text, shown in all variants of help text. */
+	const char * const purpose;
+	/* Multi line text in long help and man page. */
+	const char * const description;
+	/* How non-option arguments should be called in the synopsis. */
+	const char * const non_opts_name;
+	/* Optional, will be computed if not given. */
+	const char * const synopsis;
+	/* Array of options for this command. */
+	const struct lls_option * const options;
+	/* Closing remarks after the option list in long help and man page. */
+	const char * const closing;
+	/* Initialized to com_NAME_user_data with NAME being the command name. */
+	const void * const user_data;
+	/* Contains the array size of ->options. */
+	const int num_options;
+};
+
+struct lls_suite {
+	const char * const name;
+	const char * const caption;
+	const struct lls_command * const commands;
+	const int num_subcommands;
+};
+
+struct lls_opt_result {
+	unsigned given;
+	/* for multiple options, one value for each time the option was given */
+	union lls_val *value;
+};
+
+struct lls_parse_result {
+	char **inputs; /* non-options, non-args */
+	unsigned num_inputs;
+	struct lls_opt_result *opt_result; /* one per option */
+};
+
+/*
+ * Most library functions return a negative error code on failure. The
+ * LLS_ERRORS macro expands to a list of all possible errors, optionally
+ * including the text of each error code. The LLS_ERROR macro (without the
+ * trailing S) controls how each error is expanded.
+ */
+#define LLS_ERRORS \
+	LLS_ERROR(SUCCESS, "success") \
+	LLS_ERROR(NOMEM, "allocation failure") \
+	LLS_ERROR(BAD_OPTION, "option not recognized") \
+	LLS_ERROR(AMBIG_OPTION, "option is ambiguous") \
+	LLS_ERROR(OPT_MANDATORY, "mandatory option not given") \
+	LLS_ERROR(ARG_GIVEN, "argument given to non-arg option") \
+	LLS_ERROR(NO_ARG_GIVEN, "argument required but not given") \
+	LLS_ERROR(TRAILING_BACKSLASH, "unexpected trailing backslash") \
+	LLS_ERROR(UNMATCHED_QUOTE, "unmatched quote character") \
+	LLS_ERROR(TRAILING_GARBAGE, "garbage at end of line or argument") \
+	LLS_ERROR(YY_SCAN, "error setting up lex input buffer") \
+	LLS_ERROR(YY_LEX, "yylex() failed") \
+	LLS_ERROR(BAD_SUBCMD, "invalid subcommand") \
+	LLS_ERROR(AMBIG_SUBCMD, "ambiguous subcommand") \
+	LLS_ERROR(BAD_ARG_COUNT, "invalid number of arguments") \
+	LLS_ERROR(OVERFLOW, "value too large") \
+	LLS_ERROR(NO_DIGITS, "no digits found in string") \
+	LLS_ERROR(ENUM, "invalid value for enum option") \
+
+/*
+ * Given an identifier and a string literal, forget the string, and prefix the
+ * identifier with E_LLS_ to produce an identifier for an error code like
+ * E_LLS_OVERFLOW. Finally, append a comma. While this definition of LLS_ERROR
+ * is active, LLS_ERRORS expands to a comma-separated list of error codes. See
+ * enum lls_errors below.
+ */
+#define LLS_ERROR(_n, _s) E_LLS_ ## _n,
+
+/*
+ * Declare the enumeration of all error codes as identifiers like like
+ * E_LLS_OVERFLOW. Also, the total number of error codes is declared as
+ * NUM_LLS_ERRORS.
+ */
+enum lls_errors {LLS_ERRORS NUM_LLS_ERRORS};
+#undef LLS_ERROR
diff --git a/lopsub-suite.5.m4 b/lopsub-suite.5.m4
new file mode 100644
index 0000000..d453c9c
--- /dev/null
+++ b/lopsub-suite.5.m4
@@ -0,0 +1,446 @@
+.TH lopsub-suite 5 "DATE()" GIT_VERSION()
+.SH NAME
+lopsub-suite \- lopsub suite syntax
+.SH DESCRIPTION
+A
+.B lopsub suite
+describes the options to a command line utility with zero or more
+related subcommands. The
+.BR lopsubgen (1)
+utility translates a lopsub suite into either C source code or a manual
+page. The generated C code can be compiled and linked against the
+lopsub library to produce command line parsers for the main command
+and all subcommands defined in the suite.
+
+This document explains the format of a lopsub suite. The overall
+structure is as follows:
+
+.EX
+	[suite mysuite]
+	suite directives
+
+	[supercommand sup_cmd]
+		command directives for sup_cmd
+		[option opt1]
+		... (further options)
+
+	[subcommand sub1]
+		command directives for sub1
+		[option opt_1_to_sub1]
+			option directives for opt_1
+		... (further options)
+
+	... (further subcommands)
+
+	[section see also]
+	... (optional extra section for man page)
+
+	... (further extra sections)
+.EE
+
+A suite begins with a
+.B [suite]
+line which declares the name of the suite. The
+.B suite directives,
+all subsequent lines up to the first
+.B [supercommand]
+or
+.B [subcommand]
+line, state further properties of the suite which are unrelated to
+any particular command, for example the version number. All available
+suite directives are summarized below.
+
+The
+.B [supercommand]
+and
+.B [subcommand]
+lines indicate the beginning of a command of the suite. The part between this
+line and the first
+.B [option]
+line contains the
+.B command directives,
+for example the purpose and the description of the named command.
+See the section on command directives below.
+
+Supercommands and subcommands share the same set of possible command
+directives. They differ mainly in the way the documentation is
+formated. There can only be one supercommand but arbitrary many
+subcommands. For example, the supercommand could be the name of
+the application, and the subcommands could be "load", "save" "info"
+and "quit". The subcommand would be passed as the first non-option
+argument to the supercommand, followed by options specific to that
+subcommand.
+
+Of course it is possible to define no subcommands at all. Conversely,
+one can define only subcommands but no supercommand. This makes
+sense if the commands are run by some other means, for example in an
+interactive session from a command prompt.
+
+Within the command section, an
+.B [option]
+line starts an option to the current command. It is followed by
+.B option directives,
+which specify, for example, whether or not the option takes
+an argument. All supported option directives are listed in the
+corresponding section below.
+
+Further material for man output can be included between the
+.B [section]
+and
+.B [/section]
+markers.
+This text will not be included in the generated .c and .h files and
+is thus also not part of the short and long help available at run
+time. The text is not interpreted except that leading whitespace is
+stripped from each line. Arbitrary roff source can be included here.
+
+Empty lines and lines starting with a hash character (#) are
+ignored.
+.SH SUITE DIRECTIVES
+Most directives of this section are only relevant for man page output (with
+.B aux_info_default
+being the exception), they are ignored for C output.
+.TP
+.B caption
+The optional text for an unnumbered section heading at the beginning of the
+manual page.
+.TP
+.B title
+Sets the title of the man page. Defaults to the name of the
+supercommand. If this is not given and the suite has no supercommand,
+the .TH macro to set the title of the man page is omitted.
+.TP
+.B mansect
+Sets the man page section. Defaults to 1 (user commands). Both title
+and section are positioned at the left and right in the header line.
+.TP
+.B date
+This text is positioned in the middle of the footer line of the man page. It is
+common to set this to the date of the last nontrivial change that was made to
+the man page. Defaults to the current date.
+.TP
+.B version-string
+Positioned at the left in the footer line. Defaults to the empty string. The
+value of this directive is ignored if a version string is explicitly requested
+by passing
+.B --version-string
+to
+.BR losubgen .
+.TP
+.B manual_title
+Centered in the header line. Defaults to "User commands".
+.TP
+.B introduction
+.TQ
+.B conclusion
+The text enclosed between
+.B [introduction]
+and
+.B [/introduction]
+is shown between the supercommand (if any) and the subcommand list.
+Concluding remarks after the subcommand list may be added in the same
+way with
+.B [conclusion]
+and
+.BR [/conclusion] .
+Both texts will become part of the manual page, but are not not part
+of the short or long help. Like for the
+.B section
+directive, arbitrary roff source may be included here.
+.TP
+.B aux_info_prefix
+This text is shown at the bottom of each command before the value of the
+aux_info directive. If no
+.B aux_info
+is specified for a command, the prefix is omitted as well. If
+.B aux_info_prefix
+is not given, the empty string is assumed.
+.TP
+.B aux_info_default
+This text is only used for header output.  The argument for the generated macro
+call is set to this value for all commands for which no
+.B aux_info
+directive is given. If no
+.B aux_info_default
+directive is given, the value 0 is used as the argument for the macro.
+.SH COMMAND DIRECTIVES
+.TP
+.B purpose
+A single line containing the purpose of the command. This text is printed in
+the short and long help, and is also included in the man page.
+.TP
+.B description
+.TQ
+.B closing
+Arbitrary plain text enclosed between
+.B [description]
+and
+.BR [/description] .
+The text may be split over multiple lines and paragraphs. The
+description of the supercommand (if any) becomes the description of
+the manual page, which is shown after the command summary and before
+the list of options. The descriptions of all commands are included
+in the manual page and in the long help text but not in the short help.
+
+Closing remarks for the command can be added in a similar way by enclosing
+plain text between
+.B [closing]
+and
+.BR [/closing] .
+This text will be positioned after the option list.
+.TP
+.B synopsis
+Custom synopsis of the command. If this is not given, the synopsis text will be
+auto-generated from the options and the value of the
+.B non-opts-name
+directive.
+.TP
+.B non-opts-name
+Name of the command line arguments which are not related to any option,
+for example file names. This text will be included in the automatically
+generated synopsis text.
+
+If this is not given, the command is assumed to take no arguments other than
+the specified options and their arguments. For such commands the attempt to
+parse an argv[] vector fails if it contains further non-option arguments.
+.TP
+.B aux_info
+This directive is special because its value is not included in the generated .c
+file but in the header file. More precisely, the preprocessor macro
+.B \%LSG_SUITENAME_AUX_INFOS
+will be defined which expands to a series of macro calls to
+.B \%LSG_SUITENAME_AUX_INFO(val_n),
+one for each command of the suite, where
+.B val_n
+is the (unquoted) value of the
+.B aux_info
+directive of the nth command. Commands for which no
+.B aux_info
+directive was specified receive a value of zero. The
+.B \%LSG_SUITENAME_AUX_INFO
+macro is supposed to be defined by the application.
+Hence it is up to the application to make the expansion of
+.B \%LSG_SUITENAME_AUX_INFOS
+a valid C construct.
+
+The value, if specified, is also copied to the man page at the end of the
+section for the command.
+
+.SH OPTION DIRECTIVES
+.TP
+.B short_opt
+The optional single-letter equivalent for the option. If this is
+specified, the option may be given either in the GNU-style long
+option format with two leading dashes or in the short form with a
+single dash. Otherwise only the long form will be accepted. As usual,
+multiple short option flags may be combined.
+.TP
+.B summary
+A single line which summarizes the option. This text is included in
+both the short and the long help and in the man page. Defaults to
+the empty string.
+.TP
+.B typestr
+A description for the type of the values for the option. The given text
+is printed in the synopsis of the command, which is part of the short
+and the long help and the man page. It defaults to the string "val".
+
+This directive is ignored for flag options (options without an argument).
+.TP
+.B arg_info
+This directive determines whether the option takes an argument. The
+possible values are
+.B no_arg, required_arg
+and
+.B optional_arg
+which indicate, respectively, that the option takes no argument at all,
+an argument which is mandatory, or an argument which may be omitted. The
+default value is
+.B no_arg.
+Hence an option works as a flag if the
+.B arg_info
+directive is not given.
+
+Note that arguments to options which take an optional argument must
+be given as --foo=bar rather than --foo bar because the latter form
+would be ambiguous.
+.TP
+.B arg_type
+For flag options this directive should be set to
+.B none,
+or not set at all. For options which take an argument, the value of the directive
+determines the type of the argument.
+Possible values are
+.B string
+for options which take a string argument, and
+.B int32,
+.B uint32.
+.B int64,
+.B uint64,
+for options which take a numeric argument.
+.TP
+.B flag
+Lopsub maintains for each option a bitmask which contains the value
+of each possible flag for this option. Flags may be accumulated by
+defining multiple flag directives in the suite. Note there is no
+equal sign between the
+.B flag
+directive and its value.
+
+The following flags are defined.
+.RS
+.B
+.IP multiple
+This flag instructs the lopsub library to keep track of all given
+arguments to an option, not just one as for ordinary options. This
+is only relevant for options which take an (optional or required)
+argument.
+.B
+.IP required
+Instruct the parser to fail if this option is not given in the
+argument vector. If an option may be given at the command line or
+in the config file, this flag should be avoided because the command
+line argv vector will not be parsed successfully if the option is
+only given in the config file. The recommended way to deal with
+this situation is to parse command line and config file separately,
+then merge the two parse results and check in the application if the
+option is given in the merged parse result.
+.B
+.IP ignored
+This flag indicates that the current option is in fact not a real option.
+In particular,
+.B name
+and
+.B short_opt
+are both ignored. The purpose of this flag is to add additional
+information for the help output and the man page.
+.RE
+.TP
+.B values
+Create an enumerable option.
+
+Enumerable options take one out of a fixed set of possible values
+which are predefined in the suite. Such options are always of type
+string. It is an error if a different argument type was specified or
+if the option was defined to not take an argument.
+
+The syntax for the array of values is
+
+.EX
+	values = {ID_0 = "string_0", ..., ID_N = "string_N"}
+.EE
+
+For each option for which the
+.B values
+directive was specified, the lopsubgen command generates a C
+enumeration which contains the given identifiers. This allows to
+refer to each possible value through a numeric constant.
+.TP
+.B default_val
+This directive makes only sense for options which take an argument. For
+such options it defines the value the option parser provides
+automatically if the option is not given in the argument vector.
+
+If no
+.B default_val
+is specified in the suite, and the option is not given in the argument
+vector either, the implied value depends on the argument type. For
+numeric options, a value of zero is assumed. For options which take
+a string argument, a NULL pointer is returned. For enum options,
+the first possible value (index zero) is taken as the default.
+.TP
+.B help
+The detailed, multi-line help text for the current option. Included
+in the man page and the long help.
+.SH EXAMPLE
+A minimal suite and the corresponding "application".
+
+The suite file
+.IR hello.suite :
+
+.EX
+	[suite hello]
+	[supercommand hello]
+		purpose = hello world
+		[option world]
+			summary = add "world"
+.EE
+
+The "application"
+.IR hello.c :
+
+.EX
+	#include <stdio.h> /* printf(3) */
+	#include <stdlib.h> /* exit(3) */
+	#include <lopsub.h>
+	#include "hello.lsg.h"
+
+	int main(int argc, char **argv)
+	{
+		struct lls_parse_result *lpr;
+		const struct lls_opt_result *result;
+		const struct lls_command *cmd = lls_cmd(0, hello_suite);
+		int ret;
+
+		ret = lls_parse(argc, argv, cmd, &lpr, NULL);
+		if (ret < 0) {
+			fprintf(stderr, "%s\\n", lls_strerror(-ret));
+			exit(1);
+		}
+		printf("hello");
+		result = lls_opt_result(LSG_HELLO_HELLO_OPT_WORLD, lpr);
+		if (lls_opt_given(result))
+			printf(" world");
+		printf("\\n");
+		exit(0);
+	}
+.EE
+
+Generate
+.I hello.lsg.c
+and
+.IR hello.lsg.h :
+
+.EX
+	$ lopsubgen --gen-c --gen-h < hello.suite
+.EE
+
+Compile
+.I hello.c
+and
+.I hello.lsg.c
+to produce the
+.I hello
+executable:
+
+.EX
+	$ cc hello.c hello.lsg.c -o hello -llopsub
+.EE
+
+Run it:
+
+.EX
+	$ ./hello
+	hello
+	$ ./hello --world
+	hello world
+	$ ./hello -w
+	option not recognized
+	$ ./hello 42
+	invalid number of arguments
+.EE
+
+Generate and examine the manual page:
+
+.EX
+	$ lopsubgen --gen-man < hello.suite
+	$ man -l ./hello.lsg.man
+.EE
+
+.SH SEE ALSO
+.BR lopsubgen (1),
+.BR lopsub (7),
+.BR lopsubex (1),
+.BR gengetopt (1),
+.BR getopt (1),
+.BR getopt (3)
diff --git a/lopsub.7.m4 b/lopsub.7.m4
new file mode 100644
index 0000000..ea5c123
--- /dev/null
+++ b/lopsub.7.m4
@@ -0,0 +1,183 @@
+.\" groff -m man -Thtml <file>
+.\" See groff_www(7), groff(7) and groff_man(7)
+
+.\" save current font, switch to monospace font, output, switch back
+.de MONO
+.nr mE \\n(.f
+.ft CW
+\\$*
+.ft \\n(mE
+..
+
+.\" make text on the same line appear alternately in monospace and roman
+.de MONO_ROMAN
+.  if \\n[.$] \{\
+.    ds an-result \&\f[CW]\\$1\f[R]\"
+.    shift
+.    while (\\n[.$] >= 2) \{\
+.      as an-result \/\\$1\f[CW]\,\\$2\f[R]\"
+.      shift 2
+.    \}
+.    if \\n[.$] .as an-result \/\\$1\"
+\\*[an-result]
+.    ft R
+.  \}
+..
+
+. if !'\*(.T'html' \
+. do ftr CW I
+. \}
+
+.TH lopsub 7 "DATE()" GIT_VERSION()
+.SH About
+
+.B Lopsub
+is an open source library written in
+.B C
+which aims to ease the task of creating, documenting and parsing
+the options of Unix command line utilities. It is suitable for
+simple commands as well as complex command line utilities with many
+subcommands where each subcommand has its own set of options. Options
+and documentation are kept together in a single file which can be
+translated to
+.B C
+code (to be included in the application), or to a manual page.
+The library supports single-character short options and GNU-style
+long options. The public API is well documented and stable.
+
+To make use of the library, the programmer provides a so-called
+.I suite file
+which describes the options of the application in an intuitive
+syntax. At build time the suite file is translated into
+.B C
+code by the
+.MONO lopsubgen
+utility which also ships with the
+.B lopsub
+package. The generated code defines an instance of an opaque
+.B C
+structure and exposes a reference to this structure which can be passed to
+the
+.I option parser
+at run time, together with the usual argument vector. The
+option parser is part of the
+.B lopsub
+.IR library ,
+so applications need to link with
+.MONO_ROMAN -llopsub .
+In addition to the option parser, the library offers many more
+features. For example, there is a function for merging two different
+.I parse results
+to generate an effective configuration. This is useful for applications
+which can be configured through command line options and via a
+config file.
+
+The suite file can also be processed into roff format to create
+a manual page. Conversion into html can easily be performed with
+tools like
+.MONO grohtml
+(part of
+.BR "GNU roff" )
+or
+.MONO_ROMAN man2html .
+
+.B Lopsub
+does not rely on the system's
+.MONO getopt()
+or
+.MONO getopt_long()
+functions of the C library and is thus portable across different
+flavors of Unix. It is known to work on
+.BR Linux ,
+.B NetBSD
+and
+.BR FreeBSD .
+
+.SH License
+The
+.B lopsub library
+is licensed under the
+.B LGPLv3
+while the
+.MONO lopsubgen
+utility is licensed under the
+.BR GPLv3 .
+The examples and all code generated by the utilities, however, is
+licensed with a simple all-permissive license. You are free to do
+anything you like with the generated code, including incorporating
+it into or linking it with proprietary software.
+
+.SH Installation
+Grab your copy with
+.IP
+.EX
+git clone git://git.tuebingen.mpg.de/lopsub.git
+.EE
+.PP
+Then build the package with
+.IP
+.EX
+make
+.EE
+.PP
+The suite parser and the config file parser of the
+.B lopsub
+library are both generated by running
+.MONO_ROMAN flex ,
+a tool for generating programs that perform pattern-matching on text. Hence the
+.B flex
+package must be installed for the build to succeed. Next, run
+.IP
+.EX
+sudo make install
+.EE
+.PP
+This will install the package in
+.MONO_ROMAN /usr/local .
+If you prefer to install as an unprivileged user in
+.MONO_ROMAN /somewhere/else ,
+run
+.IP
+.EX
+make PREFIX=/somewhere/else install
+.EE
+.PP
+instead. In this case, you need to specify
+.MONO -I/somewhere/else/include
+to compile the source files of your application and
+.MONO -L/somewhere/else/lib
+for linking. Alternatively, don't run
+.MONO make install
+at all and specify the path to the top level directory of the
+repository for both
+.MONO -I
+and
+.MONO_ROMAN -L .
+
+.SH Quick Start
+Compile and run the minimal example included at the end of
+.UR ./lopsub-suite.5.html
+lopsub-suite(5)
+.UE .
+Examine
+.MONO lopsubex.c
+and
+.MONO lopsubex.suite
+in the source tree and run the
+.MONO lopsubex
+command.
+
+.SH API documentation
+See
+.UR ./lopsub-api.html
+.UE .
+Alternatively, examine
+.MONO lopsub.h
+or
+.MONO_ROMAN lopsub.h.m4 .
+
+.SH
+Reporting Bugs
+.MT maan@tuebingen.mpg.de
+Andre Noll
+.ME
diff --git a/lopsub.c b/lopsub.c
new file mode 100644
index 0000000..2ba2621
--- /dev/null
+++ b/lopsub.c
@@ -0,0 +1,1610 @@
+/*
+ * Copyright (C) 2016 Andre Noll <maan@tuebingen.mpg.de>
+ *
+ * Licensed under the LGPL v3, see http://www.gnu.org/licenses/lgpl-3.0.html
+ */
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <stdbool.h>
+#include <assert.h>
+#include <stdarg.h>
+#include <inttypes.h>
+#include <errno.h>
+#include <limits.h>
+
+#include "lopsub-internal.h"
+#include "lopsub.h"
+
+/* For detecting version mismatches, see lopsub-internal.h. */
+const unsigned LLS_ABI_VERSION_VAR = 0;
+
+#define FOR_EACH_OPTION(_i, _opts) \
+	for (_i = 0; (_opts) && (_opts)[(_i)].name; (_i)++)
+
+#define FOR_EACH_OPTION_IN_COMMAND(_opt, _cmd) \
+	for ( \
+		(_opt) = (_cmd)->options; \
+		(_opt) && (_opt) < (_cmd)->options + (_cmd)->num_options; \
+		(opt)++ \
+	)
+
+/* The result of parsing one option and its arguments. */
+struct lls_arg {
+	int idx; /* index into either argv[] or the lls_option array. */
+	const char *arg; /* NULL if option has no argument. */
+};
+
+/*
+ * This structure, and the exchange_args(), decode_option() and parse_option()
+ * functions below are inspired by the glibc implementation of getopt.c,
+ * Copyright (C) 1987-2015 Free Software Foundation, Inc.
+ */
+struct lls_data {
+	const struct lls_option *opts;
+	int argc;
+	char *const *argv;
+
+	int optind; /* index into argv[] which we are parsing. */
+	const char *next_char;
+	/*
+	 * These describe the part of argv[] that contains non-options that
+	 * have been skipped. first_nonopt is the index in argv[] of the first
+	 * of them, last_nonopt is the index after the last of them. Initially
+	 * both indices are zero.
+	 */
+	int first_nonopt;
+	int last_nonopt;
+};
+
+const struct lls_command *lls_cmd(unsigned cmd_num,
+		const struct lls_suite *suite)
+{
+	if (cmd_num > suite->num_subcommands)
+		return NULL;
+	return suite->commands + cmd_num;
+}
+
+const char *lls_command_name(const struct lls_command *cmd)
+{
+	return cmd->name;
+}
+
+const void *lls_user_data(const struct lls_command *cmd)
+{
+	return cmd->user_data;
+}
+
+const struct lls_option *lls_opt(unsigned opt_num,
+		const struct lls_command *cmd)
+{
+	return cmd->options + opt_num;
+}
+
+const struct lls_opt_result *lls_opt_result(unsigned opt_num,
+		const struct lls_parse_result *lpr)
+{
+	return lpr->opt_result + opt_num;
+}
+
+unsigned lls_opt_given(const struct lls_opt_result *r)
+{
+	return r->given;
+}
+
+const char *lls_enum_string_val(unsigned idx, const struct lls_option *opt)
+{
+	return opt->values[idx].string_val;
+}
+
+const char *lls_string_val(unsigned idx, const struct lls_opt_result *r)
+{
+	return r->value[idx].string_val;
+}
+
+int32_t lls_int32_val(unsigned idx, const struct lls_opt_result *r)
+{
+	return r->value[idx].int32_val;
+}
+
+uint32_t lls_uint32_val(unsigned idx, const struct lls_opt_result *r)
+{
+	return r->value[idx].uint32_val;
+}
+
+int64_t lls_int64_val(unsigned idx, const struct lls_opt_result *r)
+{
+	return r->value[idx].int64_val;
+}
+
+uint64_t lls_uint64_val(unsigned idx, const struct lls_opt_result *r)
+{
+	return r->value[idx].uint64_val;
+}
+
+unsigned lls_num_inputs(const struct lls_parse_result *lpr)
+{
+	return lpr->num_inputs;
+}
+
+const char *lls_purpose(const struct lls_command *cmd)
+{
+	return cmd->purpose;
+}
+
+const char *lls_input(unsigned input_num, const struct lls_parse_result *lpr)
+{
+	return lpr->inputs[input_num];
+}
+
+const char *lls_strerror(int lss_errno)
+{
+	#define LLS_ERROR(_n, _s) _s,
+	static const char * const error_string[] = {LLS_ERRORS NULL};
+	#undef LLS_ERROR
+	return error_string[lss_errno];
+}
+
+static int xrealloc(void *p, size_t size)
+{
+	void **pp = p, *newp = realloc(*pp, size);
+
+	if (!newp)
+		return -E_LLS_NOMEM;
+	*pp = newp;
+	return 0;
+}
+
+/* Print a formated message to a dynamically allocated string. */
+__attribute__ ((format (printf, 2, 0)))
+static int xvasprintf(char **result, const char *fmt, va_list ap)
+{
+	int ret;
+	size_t size = 150;
+	va_list aq;
+
+	if (!result)
+		return 0;
+	if (*result)
+		free(*result);
+	*result = malloc(size + 1);
+	if (!*result)
+		return -E_LLS_NOMEM;
+	va_copy(aq, ap);
+	ret = vsnprintf(*result, size, fmt, aq);
+	va_end(aq);
+	assert(ret >= 0);
+	if (ret < size) /* OK */
+		return ret;
+	size = ret + 1;
+	ret = xrealloc(result, size);
+	if (ret < 0) {
+		free(*result);
+		*result = NULL;
+		return ret;
+	}
+	va_copy(aq, ap);
+	ret = vsnprintf(*result, size, fmt, aq);
+	va_end(aq);
+	assert(ret >= 0 && ret < size);
+	return ret;
+}
+
+/* Print to a dynamically allocated string, variable number of arguments. */
+__attribute__ ((format (printf, 2, 3)))
+static int xasprintf(char **result, const char *fmt, ...)
+{
+	va_list ap;
+	unsigned ret;
+
+	va_start(ap, fmt);
+	ret = xvasprintf(result, fmt, ap);
+	va_end(ap);
+	return ret;
+}
+
+static inline unsigned num_vals_in_parse_result(const struct lls_command *cmd,
+	int opt_num, const struct lls_parse_result *lpr)
+{
+	const struct lls_option *opt = cmd->options + opt_num;
+	struct lls_opt_result *lor = lpr->opt_result + opt_num;
+
+	if (opt->arg_info == LLS_NO_ARGUMENT)
+		return 0;
+	if (lor->given == 0)
+		return 1; /* for the default value */
+	if (!(opt->flags & LLS_MULTIPLE))
+		return 1;
+	return lor->given;
+}
+
+union atoi_result {
+	int32_t int32;
+	uint32_t uint32;
+	int64_t int64;
+	uint64_t uint64;
+};
+
+enum atoi_mode {ATOI_INT32, ATOI_UINT32, ATOI_INT64, ATOI_UINT64};
+
+/*
+ * Convert a string to a 32 or 64 bit signed or unsigned integer value.
+ *
+ * For conversions to unsigned integers, negative values are considered valid
+ * input and are silently converted.
+ */
+static int lls_atoi(const char *str, enum atoi_mode mode, union atoi_result *value)
+{
+	char *endptr;
+	union atoi_result result;
+
+	memset(value, 0, sizeof(*value));
+	errno = 0; /* To distinguish success/failure after call */
+	/*
+	 * We pass zero as the base to strtoll(3) and strtoull(3) to let the
+	 * function recognize an optional base prefix like "0x".
+	 */
+	if (mode == ATOI_UINT64) {
+		unsigned long long tmp = strtoull(str, &endptr, 0);
+		if (errno == ERANGE && tmp == ULLONG_MAX)
+			return -E_LLS_OVERFLOW;
+		result.uint64 = tmp;
+	} else { /* parse as signed 64 bit and check range */
+		long long tmp = strtoll(str, &endptr, 0);
+		if (errno == ERANGE && (tmp == LLONG_MAX || tmp == LLONG_MIN))
+			return -E_LLS_OVERFLOW;
+		switch (mode) {
+		case ATOI_INT64: /* no additional range check necessary */
+			result.int64 = tmp;
+			break;
+		case ATOI_INT32:
+			if (tmp < INT_MIN || tmp > INT_MAX)
+				return -E_LLS_OVERFLOW;
+			result.int32 = tmp;
+			break;
+		case ATOI_UINT32:
+			if (tmp > UINT_MAX)
+				return -E_LLS_OVERFLOW;
+			result.uint32 = tmp;
+			break;
+		default:
+			assert(0);
+		}
+	}
+	/*
+	 * If there were no digits at all, strtol() and friends store the
+	 * original value of str in *endptr.
+	 */
+	if (endptr == str)
+		return -E_LLS_NO_DIGITS;
+	/*
+	 * The implementation may also set errno (and return 0) in case no
+	 * conversion was performed.
+	 */
+	if (errno != 0)
+		return -E_LLS_NO_DIGITS;
+	if (*endptr != '\0') /* Further characters after number */
+		return -E_LLS_TRAILING_GARBAGE;
+	*value = result;
+	return 1;
+}
+
+static int atoi32(const char *str, int32_t *result)
+{
+	union atoi_result ar;
+	int ret = lls_atoi(str, ATOI_INT32, &ar);
+	*result = ar.int32;
+	return ret;
+}
+
+static int atou32(const char *str, uint32_t *result)
+{
+	union atoi_result ar;
+	int ret = lls_atoi(str, ATOI_UINT32, &ar);
+	*result = ar.uint32;
+	return ret;
+}
+
+static int atoi64(const char *str, int64_t *result)
+{
+	union atoi_result ar;
+	int ret = lls_atoi(str, ATOI_INT64, &ar);
+	*result = ar.int64;
+	return ret;
+}
+
+static int atou64(const char *str, uint64_t *result)
+{
+	union atoi_result ar;
+	int ret = lls_atoi(str, ATOI_UINT64, &ar);
+	*result = ar.uint64;
+	return ret;
+}
+
+static void free_opt_result(int opt_num, struct lls_parse_result *lpr,
+		const struct lls_command *cmd)
+{
+	const struct lls_option *opt = cmd->options + opt_num;
+
+	if (opt->arg_type == LLS_STRING && !opt->values) {
+		unsigned num_vals = num_vals_in_parse_result(cmd, opt_num, lpr);
+		int j;
+		for (j = 0; j < num_vals; j++)
+			if (lpr->opt_result[opt_num].value)
+				free(lpr->opt_result[opt_num].value[j].string_val);
+	}
+	if (opt->arg_info != LLS_NO_ARGUMENT)
+		free(lpr->opt_result[opt_num].value);
+}
+
+void lls_free_parse_result(struct lls_parse_result *lpr,
+		const struct lls_command *cmd)
+{
+	int i;
+
+	if (!lpr)
+		return;
+	if (lpr->inputs)
+		for (i = 0; i < lpr->num_inputs; i++)
+			free(lpr->inputs[i]);
+	free(lpr->inputs);
+	if (lpr->opt_result)
+		FOR_EACH_OPTION(i, cmd->options)
+			free_opt_result(i, lpr, cmd);
+	free(lpr->opt_result);
+	free(lpr);
+}
+
+static struct lls_data *init_lls_data(const struct lls_option *opts,
+		int argc, char *const *argv)
+{
+	struct lls_data *d = malloc(sizeof(*d));
+
+	if (!d)
+		return NULL;
+	d->optind = 0;
+	/* start with an empty non-option list */
+	d->first_nonopt = d->last_nonopt = d->optind;
+	d->opts = opts;
+	d->argc = argc;
+	d->argv = argv;
+	d->next_char = NULL;
+	return d;
+}
+
+/*
+ * Exchange two adjacent subsets of argv[].
+ *
+ * One subset is given by indices {first_nonopt, ..., last_nonopt - 1}. It
+ * contains all the non-options that have been skipped so far. The other subset
+ * corresponds to indices {last_nonopt, ... optind - 1} which contains all the
+ * options processed since those non-options were skipped.
+ *
+ * Before the function returns, ->first_nonopt and ->last_nonopt are updated to
+ * describe the new set of non-options in argv[].
+ */
+static void exchange_args(struct lls_data *d)
+{
+	int bottom = d->first_nonopt;
+	int middle = d->last_nonopt;
+	int top = d->optind;
+	char **argv = (char **)d->argv;
+
+	/*
+	 * Exchange the shorter segment with the far end of the longer segment.
+	 * That puts the shorter segment into the right place. It leaves the
+	 * longer segment in the right place overall, but it consists of two
+	 * parts that need to be swapped next.
+	*/
+	while (top > middle && middle > bottom) {
+		if (top - middle > middle - bottom) {
+			/* Bottom segment is the short one.  */
+			int i, len = middle - bottom;
+
+			/* Swap it with the top part of the top segment. */
+			for (i = 0; i < len; i++) {
+				char *tmp = argv[bottom + i];
+				argv[bottom + i] = argv[top - (middle - bottom) + i];
+				argv[top - (middle - bottom) + i] = tmp;
+			}
+			/* Exclude the moved bottom segment from further swapping. */
+			top -= len;
+		} else {
+			/* Top segment is the short one.  */
+			int i, len = top - middle;
+			/* Swap it with the bottom part of the bottom segment. */
+			for (i = 0; i < len; i++) {
+				char *tmp = argv[bottom + i];
+				argv[bottom + i] = argv[middle + i];
+				argv[middle + i] = tmp;
+			}
+			/* Exclude the moved top segment from further swapping. */
+			bottom += len;
+		}
+	}
+	/* Update records for the slots the non-options now occupy. */
+	d->first_nonopt += d->optind - d->last_nonopt;
+	d->last_nonopt = d->optind;
+}
+
+/* whether arg points to an option argument */
+static inline bool is_option(const char *arg)
+{
+	return arg[0] == '-' && arg[1] != '\0';
+}
+
+static void check_errctx(char **errctx, int ret)
+{
+	if (!errctx)
+		return;
+	if (ret >= 0)
+		assert(!*errctx); /* memory leak/uninitialized pointer */
+	else if (ret != -E_LLS_NOMEM)
+		assert(*errctx); /* we must provide an error message */
+}
+
+/*
+ * Decode the current option. On success, set result->idx to the index in the
+ * ->options array which was decoded successfully. On failure, result->idx is
+ * the index in argv[] which could not be parsed.
+ */
+static int decode_option(struct lls_data *d, struct lls_arg *result,
+		char **errctx)
+{
+	const char *word = d->argv[d->optind], *cur, *end;
+	size_t len;
+	int i;
+	const struct lls_option *match = NULL;
+	bool ambig = false, shortopt;
+
+	assert(word[0] != '\0');
+	shortopt = word[1] != '-';
+	result->idx = d->optind;
+	result->arg = word;
+
+	if (d->next_char)
+		cur = d->next_char;
+	else
+		cur = word + 1 + !shortopt; /* skip dash(es) */
+	for (end = cur; *end && *end != '='; end++)
+		; /* nothing */
+	len = end - cur;
+
+	/* test all options for exact or abbreviated matches */
+	FOR_EACH_OPTION(i, d->opts) {
+		const struct lls_option *opt = d->opts + i;
+		if (opt->flags & LLS_IGNORED)
+			continue;
+		if (shortopt) {
+			if (*cur != opt->short_opt)
+				continue;
+			match = opt;
+			d->next_char = cur + 1;
+			if (d->next_char[0] == '\0' || d->next_char[0] == '=')
+				d->next_char = NULL;
+			break;
+		}
+		if (strncmp(opt->name, cur, len) != 0)
+			continue;
+		if (strlen(opt->name) == len) { /* exact match */
+			match = opt;
+			break;
+		}
+		if (match) { /* second non-exact match */
+			ambig = true;
+			break;
+		}
+		/* first non-exact match */
+		match = opt;
+	}
+	if (!match) { /* option not found */
+		xasprintf(errctx, "error token: %s", cur);
+		return -E_LLS_BAD_OPTION;
+	}
+	if (ambig) {
+		xasprintf(errctx, "%s", word);
+		return -E_LLS_AMBIG_OPTION;
+	}
+	if (d->next_char) {
+		if (match->arg_info == LLS_REQUIRED_ARGUMENT) {
+			xasprintf(errctx, "--%s", match->name);
+			return -E_LLS_NO_ARG_GIVEN;
+		}
+		result->arg = NULL;
+		goto success;
+	}
+	d->optind++;
+	if (*end == '=') {
+		if (match->arg_info == LLS_NO_ARGUMENT) {
+			xasprintf(errctx, "--%s", match->name);
+			return -E_LLS_ARG_GIVEN;
+		}
+		result->arg = end + 1;
+	} else if (match->arg_info == LLS_REQUIRED_ARGUMENT) {
+		if (d->optind >= d->argc) {
+			xasprintf(errctx, "--%s", match->name);
+			return -E_LLS_NO_ARG_GIVEN;
+		}
+		result->arg = d->argv[d->optind++];
+	} else
+		result->arg = NULL;
+success:
+	result->idx = match - d->opts;
+	return 1;
+}
+
+/*
+ * Parse one option, including its argument (if any).
+ *
+ * We permute the contents of ARGV as we scan, so that eventually all the
+ * non-options are at the end. This allows options to be given in any order.
+ *
+ * Returns zero on end-of-argv, negative on errors, one if an option was parsed
+ * successfully. The structure pointed to by result is initialized as follows:
+ *
+ * end-of-args case: ->idx is the index of first non-option in argv[], ->arg is
+ * argv[result->idx].
+ *
+ * error case: ->idx is the index of the first problematic option in argv. ->arg is
+ * argv[result->idx] as in the end-of-args case.
+ *
+ * success case: ->idx is the index into the option array which corresponds to
+ * the option that was parsed successfully, ->arg its argument, or NULL if no
+ * argument was given.
+ *
+ * After this function returned non-positive, it must not be called again.
+ */
+static int parse_option(struct lls_data *d, struct lls_arg *result, char **errctx)
+{
+	assert(d->last_nonopt <= d->optind);
+	assert(d->first_nonopt <= d->optind);
+
+	if (d->next_char)
+		return decode_option(d, result, errctx);
+	/*
+	 * If we have just processed some options following some non-options,
+	 * exchange them so that the options come first.
+	 */
+	if (d->first_nonopt != d->last_nonopt && d->last_nonopt != d->optind)
+		exchange_args(d);
+	else if (d->last_nonopt != d->optind)
+		d->first_nonopt = d->optind;
+	/*
+	 * Skip any additional non-options and extend the range of non-options
+	 * previously skipped.
+	 */
+	while (d->optind < d->argc && !is_option(d->argv[d->optind]))
+		d->optind++;
+	d->last_nonopt = d->optind;
+	/*
+	 * The special argument `--' forces an end of option-scanning. We skip
+	 * it like a null option, then exchange it with previous non-options as
+	 * if it were an option. Then we skip everything else like a non-option.
+	 */
+	if (d->optind != d->argc && !strcmp(d->argv[d->optind], "--")) {
+		d->optind++;
+		if (d->first_nonopt != d->last_nonopt && d->last_nonopt != d->optind)
+			exchange_args(d);
+		else if (d->first_nonopt == d->last_nonopt)
+			d->first_nonopt = d->optind;
+		d->last_nonopt = d->argc;
+		d->optind = d->argc;
+	}
+	/*
+	 * If we have done all the argv elements, stop the scan and back over
+	 * any non-options that we skipped and permuted.
+	 */
+	if (d->optind == d->argc) {
+		/*
+		 * Set the index to point at the non-options that we
+		 * previously skipped.
+		 */
+		result->idx = d->first_nonopt;
+		result->arg = d->argv[result->idx];
+		return 0;
+	}
+	assert(is_option(d->argv[d->optind]));
+	return decode_option(d, result, errctx);
+}
+
+static int check_enum_arg(const char *arg, const struct lls_option *opt,
+		char **errctx)
+{
+	int i;
+	char *val;
+
+	for (i = 0; (val = opt->values[i].string_val); i++)
+		if (!strcmp(arg, val))
+			return i;
+	xasprintf(errctx, "arg: %s, option: %s", arg, opt->name);
+	return -E_LLS_ENUM;
+}
+
+/*
+ * Increase the "given" count and store argument if the option takes one.
+ * Allocates or reallocates the ->value array of struct lls_opt_result in lpr.
+ */
+static int lls_parse_arg(struct lls_arg *la, const struct lls_option *opts,
+		struct lls_parse_result *lpr, char **errctx)
+{
+	const struct lls_option *opt = opts + la->idx;
+	struct lls_opt_result *lor = lpr->opt_result + la->idx;
+	bool multiple;
+	int idx, ret;
+
+	if (!la->arg)
+		goto success;
+	if (opt->arg_info == LLS_NO_ARGUMENT) {
+		xasprintf(errctx, "arg: %s, option: %s", la->arg, opt->name);
+		return -E_LLS_ARG_GIVEN;
+	}
+	multiple = opt->flags & LLS_MULTIPLE;
+	idx = multiple? lor->given : 0;
+	if (lor->given == 0 || multiple) {
+		ret = xrealloc(&lor->value,
+			(lor->given + 1) * sizeof(*lor->value));
+		if (ret < 0) {
+			xasprintf(errctx, "option value array for --%s",
+				opt->name);
+			return ret;
+		}
+	}
+	switch (opt->arg_type) {
+	case LLS_STRING:
+		if (lor->given > 0 && !multiple)
+			free(lor->value[idx].string_val);
+		if (opt->values) {
+			ret = check_enum_arg(la->arg, opt, errctx);
+			if (ret < 0)
+				return ret;
+			lor->value[idx].uint32_val = ret;
+		} else {
+			lor->value[idx].string_val = strdup(la->arg);
+			if (!lor->value[idx].string_val) {
+				xasprintf(errctx, "string value for %s",
+					opt->name);
+				return -E_LLS_NOMEM;
+			}
+		}
+		break;
+	case LLS_INT32:
+		ret = atoi32(la->arg, &lor->value[idx].int32_val);
+		if (ret < 0)
+			goto atoi_error;
+		break;
+	case LLS_UINT32:
+		ret = atou32(la->arg, &lor->value[idx].uint32_val);
+		if (ret < 0)
+			goto atoi_error;
+		break;
+	case LLS_INT64:
+		ret = atoi64(la->arg, &lor->value[idx].int64_val);
+		if (ret < 0)
+			goto atoi_error;
+		break;
+	case LLS_UINT64:
+		ret = atou64(la->arg, &lor->value[idx].uint64_val);
+		if (ret < 0)
+			goto atoi_error;
+		break;
+	default:
+		assert(false);
+	}
+success:
+	lor->given++;
+	return 1;
+atoi_error:
+	assert(ret < 0);
+	xasprintf(errctx, "conversion error for argument \"%s\" to option --%s",
+		la->arg, opt->name);
+	return ret;
+}
+
+static int copy_val(union lls_val *dst, const union lls_val *src,
+		const struct lls_option *opt, char **errctx)
+{
+	if (opt->arg_type != LLS_STRING || opt->values) {
+		*dst = *src;
+		return 0;
+	}
+	if (!src->string_val) {
+		dst->string_val = NULL;
+		return 0;
+	}
+	dst->string_val = strdup(src->string_val);
+	if (!dst->string_val) {
+		xasprintf(errctx, "copy value for --%s", opt->name);
+		return -E_LLS_NOMEM;
+	}
+	return 1;
+}
+
+int lls_check_arg_count(const struct lls_parse_result *lpr,
+		int min_argc, int max_argc, char **errctx)
+{
+	if (errctx)
+		*errctx = NULL;
+	if (lpr->num_inputs < min_argc) {
+		xasprintf(errctx, "at least %u non-option args required, "
+			"%u given", min_argc, lpr->num_inputs);
+		return -E_LLS_BAD_ARG_COUNT;
+	}
+	if (lpr->num_inputs > max_argc) {
+		if (max_argc == 0)
+			xasprintf(errctx, "no non-option args allowed, "
+				"%u given", lpr->num_inputs);
+		else
+			xasprintf(errctx, "at most %u non-option args allowed, "
+				"%u given", max_argc, lpr->num_inputs);
+		return -E_LLS_BAD_ARG_COUNT;
+	}
+	return 1;
+}
+
+/*
+ * Unlike getopt(3) this implementation can not resume the scan where it left
+ * off.
+ */
+int lls_parse(int argc, char **argv, const struct lls_command *cmd,
+		struct lls_parse_result **lprp, char **errctx)
+{
+	const struct lls_option *opts = cmd->options;
+	struct lls_data *d = NULL;
+	int i, ret;
+	struct lls_arg la;
+	struct lls_parse_result *lpr;
+
+	if (errctx)
+		*errctx = NULL;
+	lpr = calloc(1, sizeof(*lpr));
+	if (!lpr) {
+		xasprintf(errctx, "log parse result");
+		ret = -E_LLS_NOMEM;
+		goto out;
+	}
+	d = init_lls_data(opts, argc, argv);
+	if (!d) {
+		xasprintf(errctx, "init_lls_data()");
+		ret = -E_LLS_NOMEM;
+		goto out;
+	}
+	if (cmd->num_options == 0) {
+		la.idx = 0;
+		lpr->opt_result = NULL;
+	} else {
+		lpr->opt_result = calloc(cmd->num_options,
+			sizeof(*lpr->opt_result));
+		if (!lpr->opt_result) {
+			xasprintf(errctx, "option result array for %s",
+				cmd->name);
+			ret = -E_LLS_NOMEM;
+			goto out;
+		}
+		for (;;) {
+			ret = parse_option(d, &la, errctx);
+			if (ret < 0)
+				goto out;
+			if (ret == 0)
+				break;
+			ret = lls_parse_arg(&la, opts, lpr, errctx);
+			if (ret < 0)
+				goto out;
+		}
+	}
+	lpr->num_inputs = argc - la.idx - 1;
+	if (!cmd->non_opts_name) {
+		ret = lls_check_arg_count(lpr, 0, 0, errctx);
+		if (ret < 0) {
+			/* needed for lls_free_parse_result() */
+			lpr->inputs = NULL;
+			goto out;
+		}
+	}
+	/* We always make a copy of the elements of argv[] */
+	lpr->inputs = malloc((lpr->num_inputs + 1) * sizeof(char *));
+	if (!lpr->inputs) {
+		xasprintf(errctx, "inputs array for %s", cmd->name);
+		ret = -E_LLS_NOMEM;
+		goto out;
+	}
+	for (i = 0; i < lpr->num_inputs; i++) {
+		char *arg = argv[i + la.idx + 1];
+		lpr->inputs[i] = strdup(arg);
+		if (lpr->inputs[i])
+			continue;
+		xasprintf(errctx, "option #%d (%s) of %s", i, arg, cmd->name);
+		ret = -E_LLS_NOMEM;
+		goto out;
+	}
+	lpr->inputs[lpr->num_inputs] = NULL;
+	/* initialize default values */
+	FOR_EACH_OPTION(i, opts) {
+		const struct lls_option *opt = opts + i;
+		struct lls_opt_result *lor = lpr->opt_result + i;
+		bool required = opt->flags & LLS_REQUIRED;
+		bool has_arg = opt->arg_info != LLS_NO_ARGUMENT;
+
+		if (lor->given == 0 && required) {
+			xasprintf(errctx, "--%s", opt->name);
+			ret = -E_LLS_OPT_MANDATORY;
+			goto out;
+		}
+		if (lor->value)
+			continue;
+		if (!has_arg)
+			continue;
+		/*
+		 * allocate space for the default value, even if there is no
+		 * default given in the .suite file
+		 */
+		lor->value = malloc(sizeof(*lor->value));
+		if (!lor->value) {
+			xasprintf(errctx, "value array for --%s", opt->name);
+			ret = -E_LLS_NOMEM;
+			goto out;
+		}
+		ret = copy_val(lor->value, &opt->default_val, opt, errctx);
+		if (ret < 0)
+			goto out;
+	}
+	ret = 1;
+out:
+	free(d);
+	check_errctx(errctx, ret);
+	if (ret < 0) {
+		lls_free_parse_result(lpr, cmd);
+		*lprp = NULL;
+	} else
+		*lprp = lpr;
+	return ret;
+}
+
+#define MAX_OPTION_LEN 30
+#define HELP_INDENT 6
+static const char space[MAX_OPTION_LEN + 1] = "                              ";
+
+static int short_option_help(const struct lls_option *opt, char **result)
+{
+	int ret = 0;
+	char *opt_names = NULL;
+	bool overlong, has_short = opt->short_opt;
+	const char *typestr;
+
+	*result = NULL;
+	if (opt->flags & LLS_IGNORED)
+		return xasprintf(result, "%s", opt->summary);
+	if (opt->arg_info == LLS_NO_ARGUMENT)
+		typestr = "";
+	else
+		typestr = opt->typestr? opt->typestr : "val";
+
+	ret = xasprintf(&opt_names,
+		"%s%c%s"
+		" --%s"
+		"%s%s%s%s%s"
+		,
+		has_short? "  -" : "   ",
+		has_short? opt->short_opt : ' ',
+		has_short? "," : " ",
+		opt->name,
+		opt->arg_info == LLS_OPTIONAL_ARGUMENT? "[" : "",
+		opt->arg_info == LLS_NO_ARGUMENT? "" : "=<",
+		typestr,
+		opt->arg_info == LLS_NO_ARGUMENT? "" : ">",
+		opt->arg_info == LLS_OPTIONAL_ARGUMENT? "]" : ""
+	);
+	if (ret < 0)
+		return ret;
+	overlong = ret >= MAX_OPTION_LEN;
+	ret = xasprintf(result,
+		"%s"
+		"%s"
+		"%s"
+		"%s"
+		,
+		opt_names,
+		overlong? "\n" : "",
+		overlong? space : space + ret,
+		opt->summary? opt->summary : ""
+	);
+	free(opt_names);
+	return ret;
+}
+
+static int format_default_val(const struct lls_option *opt, char **result)
+{
+	const union lls_val *val = &opt->default_val;
+
+	*result = NULL;
+	if (opt->arg_info == LLS_NO_ARGUMENT)
+		return 0;
+	if (!(opt->flags & LLS_HAS_DEFAULT))
+		return 0;
+	switch (opt->arg_type) {
+	case LLS_STRING:
+		if (opt->values)
+			return 0;
+		return xasprintf(result, "(string, default: %s)",
+			val->string_val? val->string_val : "[NULL]");
+	case LLS_INT32:
+		return xasprintf(result, "(int32, default: %" PRId32 ")",
+			val->int32_val);
+	case LLS_UINT32:
+		return xasprintf(result, "(uint32, default: %" PRIu32 ")",
+			val->uint32_val);
+	case LLS_INT64:
+		return xasprintf(result, "(int64, default: %" PRId64 ")",
+			val->int64_val);
+	case LLS_UINT64:
+		return xasprintf(result, "(uint64, default: %" PRIu64 ")",
+			val->uint64_val);
+	default:
+		assert(0);
+	}
+	return 1;
+}
+
+static int format_values(const struct lls_option *opt, char **result)
+{
+	int i;
+	uint32_t dflt_idx;
+	const char *val, *pfx = "values: ";
+	size_t len, line_len;
+	const int indent_len = 6, max_len = 75, pfx_len = 8;
+	char *p;
+
+	*result = NULL;
+	if (!opt->values)
+		return 0;
+	assert(opt->arg_type == LLS_STRING);
+	dflt_idx = opt->default_val.uint32_val;
+	line_len = indent_len + pfx_len;
+	len = line_len;
+	for (i = 0; (val = opt->values[i].string_val); i++) {
+		size_t val_len = strlen(val);
+		/* comma and space, and [] around default val */
+		int extra_len = 2 * (i != 0) + 2 * (i == dflt_idx);
+		bool cr = line_len + val_len + extra_len > max_len;
+		if (cr) {
+			line_len = indent_len + pfx_len;
+			len += 1 + indent_len + pfx_len; /* +1 for \n */
+		}
+		len += val_len + extra_len;
+		line_len += val_len + extra_len;
+	}
+	*result = malloc(len + 1); /* +1 for terminating zero byte */
+	if (!*result)
+		return -E_LLS_NOMEM;
+	p = *result + sprintf(*result, "%.*s%s", indent_len, space, pfx);
+	line_len = p - *result;
+	for (i = 0; (val = opt->values[i].string_val); i++) {
+		size_t val_len = strlen(val);
+		int extra_len = 2 * (i != 0) + 2 * (i == dflt_idx);
+		bool cr = line_len + val_len + extra_len > max_len;
+		p += sprintf(p,
+			"%s"
+			"%s"
+			"%.*s"
+			"%s%s%s",
+			i == 0? "" : ", ",
+			cr? "\n" : "",
+			cr? pfx_len + indent_len : 0, cr? space : "",
+			i == dflt_idx? "[" : "", val, i == dflt_idx? "]" : ""
+		);
+		if (cr)
+			line_len = indent_len + pfx_len;
+		line_len += val_len + extra_len;
+	}
+	return 1;
+}
+
+static char *create_help_buf(const struct lls_command *cmd, bool long_help)
+{
+	char *header, *option_help, *result;
+	const struct lls_option *opt;
+	int ret;
+	const char *desc = (long_help && cmd->description)?
+		cmd->description : "";
+	const char *closing = (long_help && cmd->closing)? cmd->closing : NULL;
+
+	result = NULL;
+	header = NULL;
+	ret = xasprintf(&header,
+		"%s - %s\n\n"
+		"Usage: %s %s\n"
+		"%s%s"
+	,
+		cmd->name, cmd->purpose,
+		cmd->name, cmd->synopsis,
+		desc,
+		cmd->options? "\n" : ""
+	);
+	if (ret < 0)
+		return NULL;
+	if (!cmd->options)
+		return header;
+	option_help = NULL;
+	FOR_EACH_OPTION_IN_COMMAND(opt, cmd) {
+		char *tmp, *soh, *loh = NULL, *dflt, *values;
+		int indent = (opt->flags & LLS_IGNORED)? 0 : HELP_INDENT;
+
+		ret = short_option_help(opt, &soh);
+		if (ret < 0)
+			goto out;
+		if (long_help && opt->help) {
+			const char *p, *q;
+			for (p = opt->help; (q = strchr(p, '\n')); p = q + 1) {
+				tmp = NULL;
+				ret = xasprintf(&tmp, "%s%.*s%.*s",
+					loh? loh : "\n", indent, space,
+					(int)(q - p + 1), p);
+				free(loh);
+				if (ret < 0) {
+					free(soh);
+					goto out;
+				}
+				loh = tmp;
+			}
+		}
+		ret = format_default_val(opt, &dflt);
+		if (ret < 0) {
+			free(soh);
+			free(loh);
+			goto out;
+		}
+		if (long_help) {
+			ret = format_values(opt, &values);
+			if (ret < 0) {
+				free(dflt);
+				free(soh);
+				free(loh);
+				goto out;
+			}
+		} else
+			values = NULL;
+		tmp = NULL;
+		ret = xasprintf(&tmp,
+			"%s"
+			"%s"
+			"%s%s%s"
+			"%s%s"
+			"%s\n",
+			option_help? option_help : "",
+			soh ? soh : "",
+			dflt? "\n" : "", dflt? space : "", dflt? dflt : "",
+			values? "\n" : "", values? values : "",
+			loh? loh : ""
+		);
+		free(values);
+		free(dflt);
+		free(soh);
+		free(loh);
+		if (ret < 0)
+			goto out;
+		free(option_help);
+		option_help = tmp;
+	}
+	ret = xasprintf(&result, "%s%s%s%s", header, option_help,
+		closing? "\n" : "", closing? closing : "");
+out:
+	free(header);
+	free(option_help);
+	return ret < 0? NULL : result;
+}
+
+char *lls_long_help(const struct lls_command *cmd)
+{
+	return create_help_buf(cmd, true /* include help */);
+}
+
+char *lls_short_help(const struct lls_command *cmd)
+{
+	return create_help_buf(cmd, false /* only options */);
+}
+
+static int partial_match(const char *arg, const char *name)
+{
+	size_t arglen = strlen(arg);
+
+	if (strncmp(arg, name, arglen) != 0)
+		return 1; /* no match */
+	if (name[arglen] == '\0')
+		return 0; /* exact match */
+	return -1; /* partial match */
+}
+
+int lls_lookup_subcmd(const char *string, const struct lls_suite *suite,
+		char **errctx)
+{
+	int i, ret;
+
+	if (errctx)
+		*errctx = NULL;
+	if (!string) {
+		xasprintf(errctx, "nothing to look up");
+		return -E_LLS_BAD_SUBCMD;
+	}
+	ret = 0; /* no match so far */
+	for (i = 1; i <= suite->num_subcommands; i++) {
+		switch (partial_match(string, suite->commands[i].name)) {
+		case 1: /* no match */
+			continue;
+		case 0: /* exact match */
+			return i;
+		case -1: /* partial match */
+			if (ret > 0) {
+				ret = -E_LLS_AMBIG_SUBCMD;
+				goto fail;
+			}
+			ret = i;
+		}
+	}
+	if (ret > 0) /* unique partial match */
+		return ret;
+	ret = -E_LLS_BAD_SUBCMD;
+fail:
+	xasprintf(errctx, "%s", string);
+	return ret;
+}
+
+static size_t get_opt_result_pointer(const struct lls_option *opt, int val_num,
+		struct lls_opt_result *lor, void **result)
+{
+	union lls_val *val = lor->value + val_num;
+
+	switch (opt->arg_type) {
+	case LLS_INT32:
+		*result = &val->int32_val;
+		return 4;
+	case LLS_UINT32:
+		*result = &val->uint32_val;
+		return 4;
+	case LLS_INT64:
+		*result = &val->int64_val;
+		return 8;
+	case LLS_UINT64:
+		*result = &val->uint64_val;
+		return 8;
+	default:
+		assert(0);
+	}
+}
+
+/* never fails, returns number of bytes needed/written */
+static size_t serialize_parse_result(const struct lls_parse_result *lpr,
+	const struct lls_command *cmd, char *result)
+{
+	int i, j;
+	size_t nbytes;
+
+	/* num_inputs */
+	if (result)
+		memcpy(result, &lpr->num_inputs, 4);
+	nbytes = 4;
+
+	/* inputs */
+	for (i = 0; i < lpr->num_inputs; i++) {
+		if (result)
+			strcpy(result + nbytes, lpr->inputs[i]);
+		nbytes += strlen(lpr->inputs[i]) + 1;
+	}
+	/* options */
+	FOR_EACH_OPTION(i, cmd->options) {
+		const struct lls_option *opt = cmd->options + i;
+		struct lls_opt_result *lor = lpr->opt_result + i;
+		unsigned num_vals;
+
+		if (result)
+			memcpy(result + nbytes, &lor->given, 4);
+		nbytes += 4;
+		if (opt->arg_info == LLS_NO_ARGUMENT)
+			continue;
+		num_vals = num_vals_in_parse_result(cmd, i, lpr);
+		if (opt->arg_type == LLS_STRING && !opt->values) {
+			for (j = 0; j < num_vals; j++) {
+				if (result)
+					strcpy(result + nbytes,
+						lor->value[j].string_val);
+				nbytes += strlen(lor->value[j].string_val) + 1;
+			}
+		} else {
+			for (j = 0; j < num_vals; j++) {
+				size_t bytes;
+				void *p;
+				bytes = get_opt_result_pointer(opt, j, lor, &p);
+				if (result)
+					memcpy(result + nbytes, p, bytes);
+				nbytes += bytes;
+			}
+		}
+	}
+	return nbytes;
+}
+
+int lls_serialize_parse_result(const struct lls_parse_result *lpr,
+	const struct lls_command *cmd, char **result, size_t *nbytes)
+{
+	size_t sz;
+	int ret;
+
+	if (!result || !*result) { /* need to compute needed space */
+		sz = serialize_parse_result(lpr, cmd, NULL);
+		if (!result) { /* just report needed space */
+			ret = 0;
+			goto out;
+		}
+		*result = malloc(sz);
+		if (!*result) {
+			sz = 0;
+			ret = -E_LLS_NOMEM;
+			goto out;
+		}
+	}
+	/* serialize it */
+	sz = serialize_parse_result(lpr, cmd, *result);
+	ret = 1;
+out:
+	if (nbytes)
+		*nbytes = sz;
+	return ret;
+}
+
+int lls_deserialize_parse_result(const char *buf, const struct lls_command *cmd,
+		struct lls_parse_result **lprp)
+{
+	int i, j;
+	const char *p = buf;
+	struct lls_parse_result *lpr;
+
+	*lprp = NULL;
+	lpr = malloc(sizeof(*lpr));
+	if (!lpr)
+		return -E_LLS_NOMEM;
+	memcpy(&lpr->num_inputs, p, 4);
+	p += 4;
+	if (lpr->num_inputs > 0) {
+		lpr->inputs = malloc(lpr->num_inputs * sizeof(char *));
+		if (!lpr->inputs)
+			goto free_lpr;
+	} else
+		lpr->inputs = NULL;
+	for (i = 0; i < lpr->num_inputs; i++) {
+		lpr->inputs[i] = strdup(p);
+		if (!lpr->inputs[i])
+			goto free_inputs;
+		p += strlen(p) + 1;
+	}
+	lpr->opt_result = malloc(cmd->num_options * sizeof(*lpr->opt_result));
+	if (!lpr->opt_result)
+		goto free_inputs;
+	FOR_EACH_OPTION(i, cmd->options) {
+		const struct lls_option *opt = cmd->options + i;
+		struct lls_opt_result *lor = lpr->opt_result + i;
+		uint32_t num_vals;
+
+		memcpy(&lor->given, p, 4);
+		p += 4;
+		if (opt->arg_info == LLS_NO_ARGUMENT)
+			continue;
+		num_vals = num_vals_in_parse_result(cmd, i, lpr);
+		lor->value = malloc(num_vals * sizeof(*lor->value));
+		if (!lor->value)
+			goto free_options;
+		if (opt->arg_type == LLS_STRING && !opt->values) {
+			for (j = 0; j < num_vals; j++) {
+				lor->value[j].string_val = strdup(p);
+				if (!lor->value[j].string_val) {
+					for (; j >= 0; j--)
+						free(lor->value[j].string_val);
+					goto free_options;
+				}
+				p += strlen(lor->value[j].string_val) + 1;
+			}
+		} else {
+			for (j = 0; j < num_vals; j++) {
+				size_t bytes;
+				void *q;
+				bytes = get_opt_result_pointer(opt, j, lor, &q);
+				memcpy(q, p, bytes);
+				p += bytes;
+			}
+		}
+	}
+	*lprp = lpr;
+	return 1;
+free_options:
+	for (; i >= 0; i--) {
+		const struct lls_option *opt = cmd->options + i;
+		struct lls_opt_result *lor = lpr->opt_result + i;
+		unsigned num_vals = (opt->flags & LLS_MULTIPLE)? lor->given : 1;
+		for (j = 0; j < num_vals; j++)
+			if (opt->arg_type == LLS_STRING && !opt->values)
+				free(lor->value[j].string_val);
+		free(lor->value);
+	}
+	free(lpr->opt_result);
+free_inputs:
+	for (; i >= 0; i--)
+		free(lpr->inputs[i]);
+	free(lpr->inputs);
+free_lpr:
+	free(lpr);
+	return -E_LLS_NOMEM;
+}
+
+static int merge_option(int opt_num, const struct lls_parse_result *primary,
+		const struct lls_parse_result *secondary,
+		const struct lls_command *cmd, struct lls_parse_result *result,
+		char **errctx)
+{
+	int l, m, ret;
+	const struct lls_option *opt = cmd->options + opt_num;
+	struct lls_opt_result *lor1, *lor2, *lor;
+
+	lor1 = primary->opt_result + opt_num;
+	lor2 = secondary->opt_result + opt_num;
+	lor = result->opt_result + opt_num;
+	lor->given = lor1->given + lor2->given;
+	if (opt->arg_info == LLS_NO_ARGUMENT)
+		return 0;
+	if (lor->given > 0 && (opt->flags & LLS_MULTIPLE)) {
+		lor->value = malloc(lor->given * sizeof(*lor->value));
+		if (!lor->value) {
+			xasprintf(errctx, "value array for option %s", opt->name);
+			goto fail;
+		}
+		for (l = 0; l < lor1->given; l++) {
+			ret = copy_val(lor->value + l, lor1->value + l,
+				opt, errctx);
+			if (ret < 0)
+				goto free_primary_options;
+		}
+		for (m = 0; m < lor2->given; m++) {
+			ret = copy_val(lor->value + l + m, lor2->value + m,
+				opt, errctx);
+			if (ret < 0)
+				goto free_secondary_options;
+		}
+		return 1;
+	}
+	lor->value = malloc(sizeof(*lor->value)); /* one value only */
+	if (!lor->value) {
+		xasprintf(errctx, "(single) value for option %s", opt->name);
+		goto fail;
+	}
+	if (lor1->given) {
+		ret = copy_val(lor->value, lor1->value, opt, errctx);
+		if (ret < 0)
+			goto free_value;
+	} else if (lor2->given) {
+		ret = copy_val(lor->value, lor2->value, opt, errctx);
+		if (ret < 0)
+			goto free_value;
+	} else {
+		ret = copy_val(lor->value, &opt->default_val, opt, errctx);
+		if (ret < 0)
+			goto free_value;
+	}
+	return 1;
+free_secondary_options:
+	if (opt->arg_type == LLS_STRING && !opt->values)
+		for (m--; m >= 0; m--)
+			free(lor->value[l + m].string_val);
+free_primary_options:
+	if (opt->arg_type == LLS_STRING && !opt->values)
+		for (l--; l >= 0; l--)
+			free(lor->value[l].string_val);
+free_value:
+	free(lor->value);
+fail:
+	return -E_LLS_NOMEM;
+}
+
+int lls_merge(const struct lls_parse_result *primary,
+		const struct lls_parse_result *secondary,
+		const struct lls_command *cmd, struct lls_parse_result **lprp,
+		char **errctx)
+{
+	int i, j, k, ret;
+	unsigned num = primary->num_inputs + secondary->num_inputs;
+	struct lls_parse_result *result;
+
+	if (errctx)
+		*errctx = NULL;
+	result = malloc(sizeof(*result));
+	if (!result) {
+		ret = -E_LLS_NOMEM;
+		xasprintf(errctx, "parse result");
+		goto fail;
+	}
+	result->inputs = malloc((num + 1) * sizeof(char *));
+	if (!result->inputs) {
+		ret = -E_LLS_NOMEM;
+		xasprintf(errctx, "inputs array of size %u", num);
+		goto free_parse_result;
+	}
+	for (i = 0; i < primary->num_inputs; i++) {
+		result->inputs[i] = strdup(primary->inputs[i]);
+		if (!result->inputs[i]) {
+			ret = -E_LLS_NOMEM;
+			xasprintf(errctx, "primary input #%d", i);
+			goto free_primary_inputs;
+		}
+	}
+	for (j = 0; j < secondary->num_inputs; j++) {
+		result->inputs[i + j] = strdup(secondary->inputs[j]);
+		if (!result->inputs[i + j]) {
+			ret = -E_LLS_NOMEM;
+			xasprintf(errctx, "secondary input #%d", i);
+			goto free_secondary_inputs;
+		}
+	}
+	result->inputs[i + j] = NULL;
+	result->opt_result = malloc(cmd->num_options
+		* sizeof(*result->opt_result));
+	if (!result->opt_result)
+		goto free_secondary_inputs;
+	FOR_EACH_OPTION(k, cmd->options) {
+		ret = merge_option(k, primary, secondary, cmd, result, errctx);
+		if (ret < 0)
+			goto free_opt_results;
+	}
+	result->num_inputs = num;
+	*lprp = result;
+	ret = 1;
+	goto out;
+free_opt_results:
+	for (k--; k >= 0; k--)
+		free_opt_result(k, result, cmd);
+free_secondary_inputs:
+	for (j--; j >= 0; j--)
+		free(result->inputs[i + j]);
+free_primary_inputs:
+	for (i--; i >= 0; i--)
+		free(result->inputs[i]);
+	free(result->inputs);
+free_parse_result:
+	free(result);
+fail:
+	assert(ret < 0);
+	*lprp = NULL;
+out:
+	check_errctx(errctx, ret);
+	return ret;
+}
+
+static bool is_default_val(const union lls_val *val,
+		const struct lls_option *opt)
+{
+	bool has_default = opt->flags & LLS_HAS_DEFAULT;
+	bool has_arg = opt->arg_info != LLS_NO_ARGUMENT;
+	const union lls_val *dflt;
+
+	if (!has_arg)
+		return false;
+	if (!has_default)
+		return false;
+	dflt = &opt->default_val;
+	switch (opt->arg_type) {
+	case LLS_INT32:
+		return val->int32_val == dflt->int32_val;
+	case LLS_UINT32:
+		return val->uint32_val == dflt->uint32_val;
+	case LLS_INT64:
+		return val->int64_val == dflt->int64_val;
+	case LLS_UINT64:
+		return val->uint64_val == dflt->uint64_val;
+	case LLS_STRING:
+		{
+		const char *s1, *s2;
+
+		if (opt->values)
+			return val->uint32_val == dflt->uint32_val;
+		s1 = val->string_val;
+		s2 = dflt->string_val;
+		if (!s1 && !s2)
+			return true;
+		if (!s1 || !s2)
+			return false;
+		return !strcmp(s1, s2);
+		}
+	default:
+		assert(0);
+	}
+}
+
+static char *append_opt_val(const union lls_val *val,
+		const struct lls_option *opt, char *result)
+{
+	char *line = NULL, *tmp = NULL;
+
+	switch (opt->arg_type) {
+	case LLS_INT32:
+		xasprintf(&line, "%" PRId32, val->int32_val);
+		break;
+	case LLS_UINT32:
+		xasprintf(&line, "%" PRIu32, val->uint32_val);
+		break;
+	case LLS_INT64:
+		xasprintf(&line, "%" PRId64, val->int64_val);
+		break;
+	case LLS_UINT64:
+		xasprintf(&line, "%" PRIu64, val->uint64_val);
+		break;
+	case LLS_STRING:
+		{
+		const char *s, *p;
+		char *q;
+
+		if (opt->values)
+			s = lls_enum_string_val(val->uint32_val, opt);
+		else {
+			s = val->string_val;
+			if (!s)
+				return result;
+		}
+		line = malloc(2 * strlen(s) + 3);
+		if (!line) {
+			free(result);
+			return NULL;
+		}
+		line[0] = '"';
+		for (p = s, q = line + 1; *p; p++, q++) {
+			if (*p == '\\' || *p == '\n' || *p == '\t' || *p == '"') {
+				*q = '\\';
+				q++;
+			}
+			*q = *p;
+		}
+		q[0] = '"';
+		q[1] = '\0';
+		break;
+		}
+	default:
+		assert(0);
+	}
+	xasprintf(&tmp, "%s%s=%s\n", result? result : "", opt->name, line);
+	free(line);
+	free(result);
+	return tmp;
+}
+
+char *lls_dump_parse_result(const struct lls_parse_result *lpr,
+		const struct lls_command *cmd, bool non_default_only)
+{
+	int i;
+	char *result = NULL;
+
+	FOR_EACH_OPTION(i, cmd->options) {
+		const struct lls_option *opt = cmd->options + i;
+		struct lls_opt_result *lor = lpr->opt_result + i;
+		bool given = lor->given;
+		int j, n;
+
+		if (!given && non_default_only)
+			continue;
+		if (opt->arg_info == LLS_NO_ARGUMENT) {
+			char *tmp = NULL;
+			if (!given)
+				continue;
+			xasprintf(&tmp, "%s%s\n", result? result : "",
+				opt->name);
+			free(result);
+			result = tmp;
+			continue;
+		}
+		n = num_vals_in_parse_result(cmd, i, lpr);
+		for (j = 0; j < n; j++) {
+			union lls_val *val = lor->value + j;
+			if (non_default_only && is_default_val(val, opt))
+				continue;
+			result = append_opt_val(val, opt, result);
+		}
+	}
+	if (!result) { /* empty dump */
+		result = malloc(1);
+		if (result)
+			result[0] = '\0';
+	}
+	return result;
+}
diff --git a/lopsub.h.m4 b/lopsub.h.m4
new file mode 100644
index 0000000..20d3a69
--- /dev/null
+++ b/lopsub.h.m4
@@ -0,0 +1,806 @@
+VERBATIM_C(«
+/*
+ * Copyright (C) 2016 Andre Noll <maan@tuebingen.mpg.de>
+ *
+ * Licensed under the LGPL v3, see http://www.gnu.org/licenses/lgpl-3.0.html
+ */
+
+#include <string.h>
+#include <inttypes.h>
+#include <stdbool.h>
+
+#ifndef _LOPSUB_H
+#define _LOPSUB_H
+»)
+
+STATEMENT(
+	«struct lls_suite»,
+	«Opaque structure which describes a lopsub suite.»,
+«
+	This structure is defined in the .c file which is generated by
+	lopsubgen(1). The corresponding header file exposes a const pointer
+	to a this structure for use in the application.
+
+	Applications can not de-reference this pointer or access its content
+	directly. They must call one of the accessor functions described below.
+»)
+
+STATEMENT(
+	«struct lls_command»,
+	«Represents one command of a suite.»,
+«
+	A command is identified by a suite and a command number. The symbolic
+	names of all commands defined in a suite are exposed in the enumeration
+	defined in the header file which is generated by lopsubgen(1),
+
+	Applications can obtain an opaque pointer to a command by calling
+	lls_cmd(), providing the command number and the suite pointer as
+	arguments.
+»)
+
+STATEMENT(
+	«struct lls_option»,
+	«Represents one option of a command.»,
+«
+	Similar to a command, an option is identified by a command and an
+	option number. The header file created by the lopsubgen(1) utility
+	provides an enumeration for all options of each command.
+
+	The lls_opt() function returns an opaque pointer to an option, given
+	a command pointer and an option number.
+»)
+
+STATEMENT(
+	«struct lls_parse_result»,
+	«An argument vector, fully parsed according to a lopsub command.»,
+«
+	A pointer to an opaque structure of this type is returned by
+	lls_parse() if the argument vector was found valid for the given
+	command.
+
+	Several functions (described below) take a pointer to such a
+	structure. This enables applications to obtain details about the
+	options and arguments that were given in the argument vector, for
+	example whether an option was specified and how many non-options
+	(aka inputs) were given.
+»)
+
+STATEMENT(
+	«struct lls_opt_result»,
+	«The part of a parse result related to a specific option»,
+«
+	Given an option and a parse result, the lls_opt_result() function
+	returns an opaque pointer to a structure of this type which contains
+	information about the option in the argument vector that was used to
+	create the parse result.
+
+	A pointer to a structure of this type can be passed to the various
+	accessor functions described below. These functions return information
+	about the option in the argument vector, for example how many times
+	the option was given.
+»)
+
+DECLARE_FUNCTION(
+	«lls_strerror»,
+	«A strerror-like function for lopsub error codes.»,
+«
+	This works just like strerror(3).
+», «
+	«int lss_errno», «positive error code returned from a lopsub library function»
+», «
+»,
+	«const char *», «points to static memory, must not be freed by the caller»
+)
+
+DECLARE_FUNCTION(
+	«lls_parse»,
+	«Parse an argument vector according to a lopsub command.»,
+«
+	This function turns a broken-up command line into a parse result,
+	completely parsing all arguments according to the options defined
+	in the given a lopsub command. As usual, options may be given in any
+	order and the special argument "--" forces an end of option-scanning.
+
+	For each option defined in the suite, if the multiple flag is set
+	for the option, the parse result contains an array of values, with
+	one value for each time the option was given. Conversely, if the
+	multiple flag is not set, only a single value is stored in the parse
+	result. Those options may still be given multiple times, but only
+	the last given argument is stored while all previous arguments are
+	discarded.
+
+	For options which take an integer value, conversion is performed in
+	a way that recognizes an optional base prefix like "0x". The empty
+	string and strings with trailing non-digit characters result in a
+	parse error. Range violations are detected and also cause the function
+	to fail.
+», «
+	«int argc», «Usual argument counter.»,
+	«char **argv», «Usual argument vector to parse.»,
+	«const struct lls_command *cmd», «Contains names and characteristics of all allowed options.»,
+	«struct lls_parse_result **lprp», «Result pointer.»,
+	«char **errctx», «Optional error context string, only set on failure»
+», «
+	The parse_result pointer returned through lprp can be passed to several
+	accessor functions described below in order to obtain information
+	about the options and arguments in argv[].
+»,
+	«int», «Standard (negative error code on failure, non-negative on success).»,
+«
+	On success lprp is initialized according to the options that have been
+	parsed successfully. In this case either errctx or *errctx is NULL,
+	so no cleanup needs to be performed in the caller. However, when the
+	caller is no longer interested in the parse result, it should call
+	lls_free_parse_result() to release the memory that was allocated
+	during the call to lls_parse().
+
+	On errors, *lprp is set to NULL and the function returns a negative
+	error code. This can happen for various reasons, for example if an
+	invalid option or argument was given. Another possible reason is worth
+	mentioning: when the non-opts-name directive was not specified in the
+	suite, the subcommand is assumed to take no non-option arguments. In
+	this case, lls_parse() fails if the argument vector does contain any
+	non-option arguments.
+
+	In the error case, if errctx is not NULL, *errctx points to a
+	zero-terminated string which describes the context of the error
+	condition, for example the problematic element of argv[]. The only
+	exception is when an out of memory condition occurs. In this case
+	*errctx may be NULL because the function was unable to allocate
+	the memory needed for the error context. If *errctx is not NULL,
+	the memory it points to should be freed by the caller. However,
+	lls_free_parse_result() need not be called in this case.
+»)
+
+DECLARE_FUNCTION(
+	«lls_free_parse_result»,
+	«Deallocate a parse result.»,
+«
+	This frees the memory space allocated by lls_parse().
+», «
+	«struct lls_parse_result *lpr», «As returned by lls_parse().»,
+	«const struct lls_command *cmd»,
+		«This must match the pointer passed earlier to lls_parse().»
+», «
+	The parse result pointer must have been returned by a previous
+	call to lls_parse() or lls_serialize_parse_result(). Otherwise, or
+	if lls_free_parse_result has already been called before, undefined
+	behavior occurs. It's OK to pass a NULL pointer though. In this case
+	no action is performed.
+»,
+	«void»
+)
+
+DECLARE_FUNCTION(
+	«lls_long_help»,
+	«Return the long help text of a command.»,
+«
+	The long help text contains the synopsis, the purpose and the help
+	text of the command, followed by the option list including descriptions
+	and help for each option.
+», «
+	«const struct lls_command *cmd», «As returned from lls_cmd().»
+», «
+»,
+	«char *», «A dynamically allocated string that must be freed by the caller.»
+)
+
+DECLARE_FUNCTION(
+	«lls_short_help»,
+	«Return the short help text of a command.»,
+«
+	This is similar to lls_long_help() but help texts are omitted from
+	the output.
+», «
+	«const struct lls_command *cmd», «See lls_long_help().»
+», «
+»,
+	«char *», «See lls_long_help().»
+)
+
+DECLARE_FUNCTION(
+	«lls_lookup_subcmd»,
+	«Tell whether the given string is the name of a subcommand.»,
+«
+	This tries to match the given string against the subcommands of the
+	suite. Exact matches and unique partial matches count as success.
+», «
+	«const char *string», «The name to look up.»,
+	«const struct lls_suite *suite», «Contains the command list.»,
+	«char **errctx», «Contains lookup string and the name of the suite.»
+», «
+»,
+	«int», «The command number on success, negative error code on failure.»,
+«
+	The lookup fails if (a) the given string pointer is NULL, or (b) if
+	the string is no prefix of any subcommand of the suite, or (c) if it
+	is a proper prefix of more than one subcommand.
+
+	On success the error context pointer is set to NULL. In the error case,
+	if errctx is not NULL, *errctx is pointed to a string that must be
+	freed by the caller.
+»)
+
+DECLARE_FUNCTION(
+	«lls_cmd»,
+	«Return a pointer to a command structure.»,
+«
+	Applications usually call this at the beginning of each function that
+	implements a lopsub command (aka command handler). The returned
+	pointer serves as an abstract reference to the command. This
+	reference is needed to call other functions of the lopsub library,
+	notably lls_parse().
+», «
+	«unsigned cmd_num», «Appropriate enum value from the header file.»,
+	«const struct lls_suite *suite», «Also declared in the header file.»
+», «
+	The suite pointer and all valid command numbers are defined in the
+	header file which is generated by lopsubgen(1). Hence this header
+	file must be included from the application to get the name of the
+	suite pointer variable and the command numbers.
+»,
+	«const struct lls_command *», «Never returns NULL.»,
+«
+	This function always succeeds if both arguments are valid. That is,
+	the command number is a symbolic constant from the LSG_XXX_COMMANDS
+	enumeration of the header file generated by lopsubgen(1), and the suite
+	pointer equals the pointer that is declared in the same header file.
+
+	If at least one of the arguments are invalid, the behavior is
+	undefined.
+»)
+
+DECLARE_FUNCTION(
+	«lls_command_name»,
+	«Obtain the name of the command, given a command pointer.»,
+«
+	Even in situations where the application knows the name of the command,
+	it is less error-prone to call this function rather than to duplicate
+	the command name in the application.
+», «
+	«const struct lls_command *cmd», «As obtained from lls_cmd().»
+», «
+»,
+	«const char *», «Never returns NULL.»,
+«
+	This function succeeds unless the given command pointer is invalid
+	(was not obtained through an earlier call to lls_cmd() or is NULL),
+	in which case the behavior is undefined. The return pointer refers
+	to static storage that must not be freed by the caller.
+»)
+
+DECLARE_FUNCTION(
+	«lls_user_data»,
+	«Obtain the application-specific data pointer.»,
+«
+	Some applications need to store further information for each subcommand,
+	for example a function pointer which refers to the implementation of
+	the subcommand. The optional user data feature allows to define one
+	application defined pointer that can be retrieved by calling this
+	function.
+
+	Of course storing one function pointer per command could simply be
+	done by defining a suitable array in the application which contains
+	one pointer per (sub)command. However, this approach has the disadvantage
+	that it effectively creates two command lists (one in the suite
+	file and one for the array) that need to be maintained and kept in
+	sync. Moreover, functions can not be declared as static if they are
+	defined in a different source file than the one that defines the array.
+
+	Therefore, lopsub offers an alternative: The .c file generated by
+	lopsubgen(1) declares one const void * pointer per command. These
+	pointers are marked with the "weak" attribute (a gcc extension, but
+	also available for clang). This instructs the compiler to store the
+	declaration as a weak symbol in the object file. Since the linker
+	does not require weak symbols to be defined, linking succeeds even
+	if the application chooses to not employ the user data feature.
+
+	To make use of the user data feature, the application needs to define
+	one pointer for each command called lsg_xxx_com_yyy_user_data, where
+	xxx is the name of the suite and yyy the name of the command. A
+	suitable preprocessor macro can make this as simple as EXPORT_CMD(foo).
+», «
+	«const struct lls_command *cmd», «As obtained from lls_cmd().»
+», «
+»,
+	«const void *», «The user data pointer defined in the application.»,
+«
+	If the application did not define a user data pointer for the given
+	command, the function returns NULL.
+»)
+
+DECLARE_FUNCTION(
+	«lls_opt_result»,
+	«Extract information about one option from a parse result.»,
+«
+	The returned pointer can be passed to the accessor functions described
+	below. Those functions let the applications tell how many times the
+	option was given and retrieve any argument(s) for the option.
+», «
+	«unsigned opt_num», «As declared in the header file.»,
+	«const struct lls_parse_result *lpr», «As returned from lls_parse().»
+», «
+	The header file generated by lopsubgen(1) generates for each command
+	an enumeration which declares one option number per option as a
+	symbolic constant.
+»,
+	«const struct lls_opt_result *», «Never returns NULL.»,
+«
+	If the parse result pointer is invalid (was not returned by
+	lls_parse(), or is NULL), or the option number does not correspond to
+	the command that was used to create the parse result, the behaviour
+	is undefined. Otherwise this function succeeds.
+»)
+
+DECLARE_FUNCTION(
+	«lls_opt»,
+	«Get a reference to an option, given a command and an option number.»,
+«
+	While an opt_result pointer described above is used to obtain
+	information in an argument vector, the pointer returned by this
+	function allows to obtain information about the option itself.
+
+	Applications rarely need to care about the option pointer. It
+	is required to get the possible values of an enumeration option
+	though. See lls_enum_string_val().
+», «
+	«unsigned opt_num», «See lls_opt_result()»,
+	«const struct lls_command *cmd», «Obtained from lls_cmd().»
+», «
+»,
+	«const struct lls_option *», «Never returns NULL.»,
+«
+	This function always succeeds if both arguments are
+	valid. Otherwise the behavior is undefined.
+»)
+
+DECLARE_FUNCTION(
+	«lls_opt_given»,
+	«Return how many times an option was given.»,
+«
+	This is employed as follows. Applications first call lls_parse() to
+	initialize the parse result, followed by lls_opt_result() to obtain a
+	reference to those parts of the parse result that are related to one
+	specific option. The reference can then be passed to this function
+	to find out how many times the option was given.
+», «
+	«const struct lls_opt_result *r», «As returned from lls_opt_result().»
+», «
+»,
+	«unsigned», «Zero means: Not given at all.»,
+«
+	Even if the multiple flag was not set for the option, the returned
+	value may be greater than one because this flag only affects how many
+	arguments are stored in the parse result.
+
+	This function succeeds unless the opt_result pointer is invalid
+	(was not returned by lls_opt_result(), or is NULL), in which case
+	the behaviour is undefined.
+»)
+
+DECLARE_FUNCTION(
+	«lls_string_val»,
+	«Retrieve one argument to a string option.»,
+«
+	This function may only be called for options which take an optional or
+	required argument of string type. Enum options (which take as their
+	argument one of a fixed, finite set of possible strings), however,
+	are treated as if the option took an argument of uint32 type. Hence
+	this function must not be called for these options.
+», «
+	«unsigned idx», «The index in the array of values.»,
+	«const struct lls_opt_result *r», «As returned from lls_opt_result.»
+», «
+	The first argument must be zero if the multiple flag is not set for
+	the option. Otherwise any number between zero and n - 1 (inclusively)
+	may be passed, where n is the number of times the option was given,
+	that is, the return value of lls_opt_given().
+
+	As as special case, if the option was not given at all (i.e., n == 0),
+	it is still OK to call this function with an index value of zero. In
+	this case, the default value for the option will be returned, or NULL
+	if no default value was specified in the suite.
+»,
+	«const char *», «The argument that corresponds to the given index.»,
+«
+	The memory referenced by the return pointer is part of the parse
+	result and must not be freed by the caller. It will be freed when
+	lls_free_parse_result() is called.
+
+	Undefined behaviour occurs in all of the following cases: (a) the
+	index is out of range, (b) the opt_result pointer is NULL or was
+	not obtained through a previous call to lls_opt_result(), (c) the
+	opt_result pointer corresponds to an option which takes an argument
+	of different type or no argument at all. If none of these conditions
+	apply, the function is guaranteed to succeed.
+»)
+
+DECLARE_FUNCTION(
+	«lls_int32_val»,
+	«Retrieve one argument to an option that takes an int32 argument.»,
+«
+	This is like lls_string_val(), but for options which take an optional
+	or required argument of type int32.
+», «
+	«unsigned idx», «See lls_string_val()»,
+	«const struct lls_opt_result *r», «See lls_string_val().»
+», «
+	As for lls_string_val(), a zero index value is considered a valid
+	input even if the option was not given at all. In this case. the
+	default value is returned, or zero if the option has no default value.
+»,
+	«int32_t», «The argument, converted to a 32 bit signed integer.»,
+«
+	Since conversion of the argument to int32_t takes place earlier during
+	lls_parse(), no errors are possible unless the index parameter or the
+	the opt result pointer (or both) are invalid. See above for details.
+»)
+
+DECLARE_FUNCTION(
+	«lls_uint32_val»,
+	«Retrieve one argument to an option that takes an uint32 argument.»,
+«
+	Identical to lls_int32_val(), except the argument type of the option
+	and the return value are different.
+
+	For enum options, this is the correct function to call in order
+	to obtain the index into the array of possible values, see
+	lls_enum_string_val() below.
+», «
+	«unsigned idx», «See lls_int32_val().»,
+	«const struct lls_opt_result *r», «See lls_int32_val().»
+», «
+»,
+	«uint32_t», «See lls_int32_val().»
+)
+
+DECLARE_FUNCTION(
+	«lls_int64_val»,
+	«Retrieve one argument to an option that takes an int64 argument.»,
+«
+	Identical to lls_int32_val(), except that this function must be used
+	for options which take a 64 bit signed integer argument.
+», «
+	«unsigned idx», «See lls_int32_val().»,
+	«const struct lls_opt_result *r», «See lls_int32_val().»
+», «
+»,
+	«int64_t», «See lls_int32_val().»
+)
+
+DECLARE_FUNCTION(
+	«lls_uint64_val»,
+	«Retrieve one argument to an option that takes an uint64 argument.»,
+«
+	Identical to lls_int32_val(), except that this function must be used
+	for options which take a 64 bit unsigned integer argument.
+», «
+	«unsigned idx», «See lls_int32_val().»,
+	«const struct lls_opt_result *r», «See lls_int32_val().»
+», «
+»,
+	«uint64_t», «See lls_int32_val().»
+)
+
+DECLARE_FUNCTION(
+	«lls_enum_string_val»,
+	«Get one possible argument value for an option.»,
+«
+	This function must only be called for enum options. That is, options
+	for which the set of possible arguments was defined through the values
+	directive in the suite.
+», «
+	«unsigned idx», «Determines which of the possible values to get.»,
+	«const struct lls_option *opt», «As returned by lls_opt().»
+», «
+	The possible values of an enum option are a property of the option
+	itself and are thus independent of the command line. Therefore this
+	function expects an option pointer rather than a pointer to an opt
+	result.
+
+	The index parameter must be a value between zero and the number of
+	possible values minus one, inclusively. This number is declared as
+	the last member of the enumeration for the option, which is defined
+	of the generated header file.
+»,
+	«const char *», «Static memory, must not be freed.»,
+«
+	Behavior is undefined if the given option is not an enum option, a
+	NULL pointer is passed, or if the index value is out of range.
+»
+)
+
+DECLARE_FUNCTION(
+	«lls_num_inputs»,
+	«Get the number of non-option arguments.»,
+«
+	In addition to options and their arguments, subcommands may accept
+	any number of additional arguments which are not related to any
+	particular option. For example, file names are frequently passed
+	as such non-option arguments (aka inputs).
+», «
+	«const struct lls_parse_result *lpr», «As returned from lls_parse().»
+», «
+	Passing a NULL pointer to this function results in undefined behaviour.
+»,
+	«unsigned», «Number of non-option arguments.»,
+«
+	This function never fails. See also lls_input(), lls_check_arg_count().
+»)
+
+DECLARE_FUNCTION(
+	«lls_input»,
+	«Get a reference to one non-option argument.»,
+«
+	If the argument vector passed to lls_parse() contained non-option
+	arguments, the value of each of them can be obtained by calling
+	this function.
+», «
+	«unsigned idx», «The index into the array of non-option arguments.»,
+	«const struct lls_parse_result *lpr», «As returned from lls_parse().»
+», «
+	The index must be between zero and n-1, inclusively, where n is the
+	number returned by lls_num_inputs(). The parse_result pointer must have
+	been obtained by an earlier call to lls_parse().
+»,
+	«const char *», «Pointer to the corresponding non-option argument.»,
+«
+	If the conditions described above are met, the function is guaranteed
+	to succeed. It will never return a NULL pointer in this case.
+»
+)
+
+DECLARE_FUNCTION(
+	«lls_version»,
+	«Get the version string of the lopsub library.»,
+«
+	The version string is determined at build time from the sha1 of the
+	HEAD git commit or from the name of the top level directory for compiling
+	from a gitweb snapshot.
+», «
+	«void»,
+», «
+»,
+	«const char *», «Static storage, must not be freed by the caller.»,
+«
+	The returned string is of the form <tag>-<d>-g<sha1>, where <tag>
+	is the name of the last tagged commit contained in the HEAD commit,
+	<d> is the number of commits between <tag> and HEAD, and <sha1> is the
+	first four hex digits of the hash of the HEAD commit. If the working
+	tree was dirty at compile time, the string "-dirty" is appended to
+	the version string.
+
+	This function always succeeds.
+»
+)
+
+DECLARE_FUNCTION(
+	«lls_purpose»,
+	«Get the line which describes the purpose of a command.»,
+«
+	This function is useful for applications which need to print
+	their own command summary rather than employ lls_short_help() and
+	lls_long_help(). One reason for this could be that the application
+	has additional per-command informations which should be included in
+	the command summary.
+», «
+	«const struct lls_command *cmd», «Obtained from lls_cmd().»
+», «
+»,
+	«const char *», «Static storage, must not be freed.»,
+«
+	The returned string is the content of the corresponding directive of
+	the suite file, with leading and trailing whitespace removed.
+»
+)
+
+DECLARE_FUNCTION(
+	«lls_convert_config»,
+	«Transform the contents of a config file into an argument vector.»,
+«
+	This function scans the given input buffer to compute an (argc,
+	argv) pair which is suitable to be fed to lls_parse(). The function
+	is config-agnostic. That is, it does not know anything about option
+	names and their type.
+
+	Arguments are separated from the option by whitespace and an optional
+	'=' character. Arguments to string options should be enclosed in double
+	quotes and must not spawn multiple lines. Newline or tab characters
+	may be embedded into the argument string with '\n' and '\t'. To embed
+	a backslash, double it. To embed a quote, prefix it with a backslash.
+», «
+	«const char *buf», «Input buffer (content of the config file).»,
+	«size_t nbytes», «The buffer size.»,
+	«const char *subcmd», «NULL means supercommand.»,
+	«char ***result», «Argument vector is returned here.»,
+	«char **errctx», «Error context, see lls_parse().»
+», «
+	If a subcommand is specified, only the part of the input buffer which
+	is started by a [subcmd] marker is taken into account. Conversely,
+	if a NULL pointer is passed, only the beginning part until the first
+	section marker will be considered. This allows config files to contain
+	options for the supercommand and subcommands.
+»,
+	«int», «Length of the argument vector.»,
+«
+	On success, the number of elements in the computed argument vector
+	is returned. Slot zero of the argument vector is initialized to a
+	dummy value while the remaining values correspond to the options and
+	arguments found in the input buffer. The argument vector should be
+	freed with lls_free_argv() when it is no longer needed.
+
+	On failure a negative error code is returned and *result is set to
+	NULL. Several types of failure are possible, including allocation
+	failure, errors from the lexer and various syntax errors.
+»
+)
+
+DECLARE_FUNCTION(
+	«lls_free_argv»,
+	«Deallocate an argument vector.»,
+«
+	lls_convert_config() dynamically allocates memory for the argument
+	and for each of its elements. This function frees this memory.
+», «
+	«char **argv», «The argument vector to free.»
+», «
+	It's OK to pass a NULL pointer, in which case the function does
+	nothing.
+»,
+	«void»
+)
+
+DECLARE_FUNCTION(
+	«lls_check_arg_count»,
+	«Check the number of non-option arguments.»,
+«
+	This helper verifies that the number of non-option arguments lies
+	within the specified range. Although this function is kind of trivial,
+	it can help applications to provide nice and consistent error messages.
+», «
+	«const struct lls_parse_result *lpr», «As obtained from lls_parse().»,
+	«int min_argc», «Lower bound on the number of non-option arguments.»,
+	«int max_argc», «Upper bound on the number of non-option arguments.»,
+	«char **errctx», «Describes the range violation, only set on failure.»
+», «
+	For the function to succeed, the number of non-option arguments (as
+	returned by lls_num_inputs()) must be greater or equal to min_argc
+	and less or equal to max_argc.
+
+	Both min_argc and max_argc may be zero (but not negative), and min_argc
+	must be less or equal to max_argc. The value INT_MAX for max_argc
+	indicates that the number of allowed non-option arguments is unbounded.
+»,
+	«int», «Standard. The only possible error is -LLS_E_BAD_ARG_COUNT.»,
+«
+	Examples:
+
+	min_argc = 0, max_argc = 0: no non-option argument may be given.
+
+	min_argc = 0, max_argc = INT_MAX: any number of non-option arguments OK.
+
+	min_argc = 1, max_argc = 2: either one or two non-option arguments OK.
+
+	Behaviour is undefined if min_argc or max_argc is negative, if min_argc
+	is greater than max_argc, or if lpr is invalid.
+»
+)
+
+DECLARE_FUNCTION(
+	«lls_serialize_parse_result»,
+	«Create a buffer from a parse result.»,
+«
+	This function is handy for passing the result from lls_parse() to a
+	different process.
+», «
+	«const struct lls_parse_result *lpr», «The parse result to serialize.»,
+	«const struct lls_command *cmd», «Must point to the command used to create the parse result.»,
+	«char **result», «The serialized parse result.»,
+	«size_t *nbytes», «The size of the serialized buffer.»
+», «
+	Depending on the initial value of the result pointer, the function
+	behaves as follows.
+
+	(a) If result is NULL, the size required to store the serialized
+	buffer is computed and returned through the nbytes argument, but no
+	serialization takes place.
+
+	(b) If result is not NULL, but *result is NULL, a suitable buffer is
+	allocated with malloc() and *result is pointed at this buffer. The
+	caller is responsible for freeing this buffer when it is no longer
+	needed.
+
+	(c) If *result is not NULL, the buffer pointed at by *result is assumed
+	be be large enough for the serialized parse result, and this buffer
+	is used to store the result.
+»,
+	«int», «Standard.»,
+«
+	See also: lls_deserialize_parse_result().
+»
+)
+
+DECLARE_FUNCTION(
+	«lls_deserialize_parse_result»,
+	«Initialize a parse result from a buffer.»,
+«
+	This is the counterpart to lls_serialize_parse_result().
+», «
+	«const char *buf», «The buffer to de-serialize.»,
+	«const struct lls_command *cmd», «Must match the pointer used for serializing.»,
+	«struct lls_parse_result **lprp», «Result pointer.»
+», «
+	The input buffer should have been obtained through an earlier call
+	to lls_serialize_parse_result().
+»,
+	«int», «Standard.»,
+«
+	On success all fields of lpr match the original values. After the
+	call, no fields of *lprp contain references to buf, so buf may safely
+	be freed.
+»
+)
+
+DECLARE_FUNCTION(
+	«lls_merge»,
+	«Combine two parse results, creating an effective configuration.»,
+«
+	This is useful for applications which receive options from the command
+	line and the configuration file.
+», «
+	«const struct lls_parse_result *primary», «From command line options.»,
+	«const struct lls_parse_result *secondary», «From config file.»,
+	«const struct lls_command *cmd», «Common command for both parse results.»,
+	«struct lls_parse_result **lprp», «Effective configuration is returned here.»,
+	«char **errctx», «Error context, see lls_parse().»
+», «
+	Merging works on a per-option basis as follows. If the multiple flag
+	is set for the option, the argument arrays of the primary and the
+	secondary parse result are concatenated and the concatenation is the
+	argument array for the merge result. It the multiple flag is not set,
+	the value of the primary parse result becomes the argument for the
+	merge result.
+
+	The two non-option argument arrays are concatenated in the same way
+	as the arguments to options with the multiple flag set.
+
+	All arguments are copied from the two input parse results. It is safe
+	to free them after the function returns. The merge result should be
+	freed with lls_parse_result() when it is no longer needed.
+»,
+	«int», «Standard.»,
+«
+	The only possible error is an out of memory condition. However,
+	behaviour is undefined if the primary or secondary parse result is
+	NULL, or was not obtained from the given command.
+»
+)
+
+DECLARE_FUNCTION(
+	«lls_dump_parse_result»,
+	«Create contents of a configuration file from a parse result.»,
+«
+	The subcommand marker ([subcommand]) is not included in the output.
+», «
+	«const struct lls_parse_result *lpr», «As obtained from lls_parse() or lls_merge().»,
+	«const struct lls_command *cmd», «Subcommand or supercommand.»,
+	«bool non_default_only», «Only include option values that differ from the default.»
+»,«
+	If non_default_only is false, options are included in the dump even
+	if they are not given in the parse result. However, flag options are
+	excluded in this case as well as options which take an argument for
+	which no default value has been defined.
+»,
+	«char *», «Must be freed by the caller.»,
+«
+	If no options are given, or if every option argument of the parse
+	result matches the default value of the option and non_default_only
+	is true, the function returns the empty string.
+
+	The only possible error is an out of memory condition, in which case
+	the NULL pointer is returned. Behaviour is undefined if any of the
+	pointer arguments is NULL, or if the parse result does not match the
+	given command.
+»
+)
+VERBATIM_C(«#endif /* _LOPSUB_H */»)
diff --git a/lopsubex.c b/lopsubex.c
new file mode 100644
index 0000000..8c10684
--- /dev/null
+++ b/lopsubex.c
@@ -0,0 +1,332 @@
+/*
+ * Written 2016 by Andre Noll <maan@tuebingen.mpg.de>
+ *
+ * Public domain, no copyright claims.
+ */
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <inttypes.h>
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <unistd.h>
+#include <stdbool.h>
+
+#include "lopsub.h"
+#include "lopsubex.lsg.h"
+
+typedef int (*example_handler_t)(struct lls_parse_result *);
+
+struct local_command_info {
+	example_handler_t handler;
+};
+
+#define EXPORT_CMD(_cmd) \
+	const struct local_command_info lsg_lopsubex_com_ ## _cmd ## _user_data = { \
+		.handler = com_ ## _cmd \
+	};
+
+#define CMD_PTR(_cmd) lls_cmd(LSG_LOPSUBEX_CMD_ ## _cmd, lopsubex_suite)
+#define OPT_PTR(_cmd, _opt) \
+	lls_opt(LSG_LOPSUBEX_ ## _cmd ## _OPT_ ## _opt, CMD_PTR(_cmd))
+
+#define OPT_RESULT(_cmd, _opt, _lpr) \
+	lls_opt_result(LSG_LOPSUBEX_ ## _cmd ## _OPT_ ## _opt, _lpr)
+
+static void print_available_commands(void)
+{
+	const struct lls_command *cmd;
+	int i;
+	printf("Available subcommands:\n");
+	for (i = 1; (cmd = lls_cmd(i, lopsubex_suite)); i++) {
+		const char *name = lls_command_name(cmd);
+		const char *purpose = lls_purpose(cmd);
+		printf("%-20s%s\n", name, purpose);
+	}
+}
+
+static const struct lls_command *lookup_subcmd_or_die(const char *str)
+{
+	char *errctx;
+	int ret = lls_lookup_subcmd(str, lopsubex_suite, &errctx);
+
+	if (ret < 0) {
+		if (errctx)
+			printf("%s: ", errctx);
+		printf("%s\n", lls_strerror(-ret));
+		print_available_commands();
+		exit(EXIT_FAILURE);
+	}
+	return lls_cmd(ret, lopsubex_suite);
+}
+
+static int com_flag(struct lls_parse_result *lpr)
+{
+	const struct lls_opt_result *r = OPT_RESULT(FLAG, SIMPLE, lpr);
+
+	/* flag count is obtained with lls_given() */
+	printf("--simple is given %u times\n", lls_opt_given(r));
+
+	r = OPT_RESULT(FLAG, SQRT4, lpr);
+	printf("--sqrt4 (aka -2) is given %u times\n", lls_opt_given(r));
+	return 0;
+}
+EXPORT_CMD(flag)
+
+static int com_int_param(struct lls_parse_result *lpr)
+{
+	const struct lls_opt_result *r_r = OPT_RESULT(INT_PARAM, ROTATE, lpr);
+	printf("rotating by %d degrees\n", lls_int32_val(0, r_r));
+	return 0;
+}
+EXPORT_CMD(int_param)
+
+static int com_multiple(struct lls_parse_result *lpr)
+{
+	const struct lls_opt_result *r;
+	int i;
+	unsigned given;
+
+	r = OPT_RESULT(MULTIPLE, VERBOSE, lpr);
+	printf("--verbose is given %d times\n", lls_opt_given(r));
+	r = OPT_RESULT(MULTIPLE, INPUT_FILE, lpr);
+	given = lls_opt_given(r);
+	printf("--input-file is given %d times\n", lls_opt_given(r));
+	for (i = 0; i < given; i++)
+		printf("--input-file val #%d: %s\n", i, lls_string_val(i, r));
+	r = OPT_RESULT(MULTIPLE, OUTPUT_FILE, lpr);
+	printf("--output-file is given %d times\n", lls_opt_given(r));
+	printf("--output-file val: %s\n", lls_string_val(0, r));
+	return 0;
+}
+EXPORT_CMD(multiple)
+
+static int com_custom_synopsis(struct lls_parse_result *lpr)
+{
+	const struct lls_command *cmd = CMD_PTR(CUSTOM_SYNOPSIS);
+	char *long_help = lls_long_help(cmd);
+	printf("%s\n", long_help);
+	free(long_help);
+	return 0;
+}
+EXPORT_CMD(custom_synopsis)
+
+static void fruit_salad(struct lls_parse_result *lpr)
+{
+	const struct lls_opt_result *r_f = OPT_RESULT(SERIALIZE, FRUIT, lpr);
+	const struct lls_opt_result *r_a = OPT_RESULT(SERIALIZE, AMOUNT, lpr);
+	const struct lls_opt_result *r_s = OPT_RESULT(SERIALIZE, SUGAR, lpr);
+	const struct lls_opt_result *r_c = OPT_RESULT(SERIALIZE, CONTAINER, lpr);
+	int i, num_vals;
+
+	printf("Put %d gramms of fruits (", lls_uint32_val(0, r_a));
+	num_vals = lls_opt_given(r_f) > 0? lls_opt_given(r_f) : 1;
+	for (i = 0; i < num_vals; i++)
+		printf("%s%s", lls_string_val(i, r_f),
+			i == num_vals - 1? "" : ", ");
+	printf(") in a %s, ", lls_string_val(0, r_c));
+	if (lls_opt_given(r_s))
+		printf("add sugar, ");
+	printf("and serve cold.\n");
+}
+
+static int com_serialize(struct lls_parse_result *lpr)
+{
+	const struct lls_command *cmd = CMD_PTR(SERIALIZE);
+	char *buf = NULL;
+	int ret;
+	size_t nbytes;
+	struct lls_parse_result *dlpr; /* deserialized */
+
+	fruit_salad(lpr);
+	ret = lls_serialize_parse_result(lpr, cmd, &buf, &nbytes);
+	if (ret < 0)
+		return ret;
+	printf("serialized parse result into %zu byte buffer\n", nbytes);
+	ret = lls_deserialize_parse_result(buf, cmd, &dlpr);
+	free(buf);
+	if (ret < 0)
+		return ret;
+	printf("successfully deserialized parse result\n");
+	fruit_salad(dlpr);
+	lls_free_parse_result(dlpr, cmd);
+	return 1;
+}
+EXPORT_CMD(serialize)
+
+static int com_non_ascii(struct lls_parse_result *lpr)
+{
+	const struct lls_opt_result *r_c = OPT_RESULT(NON_ASCII, CITY, lpr);
+	const char *city = lls_string_val(0, r_c);
+
+	if (strcmp(city, "Göttingen"))
+		printf("I don't know anything about %s\n", city);
+	else
+		printf("One of the most famous citicens of Göttingen was\n"
+			"the mathematician Carl Friedrich Gauß.\n");
+	exit(EXIT_SUCCESS);
+}
+EXPORT_CMD(non_ascii)
+
+static int com_enum(struct lls_parse_result *lpr)
+{
+	const struct lls_option *o_c = OPT_PTR(ENUM, COLOR);
+	const struct lls_opt_result *r_c = OPT_RESULT(ENUM, COLOR, lpr);
+	bool c_given = lls_opt_given(r_c);
+	uint32_t num;
+	const char *color;
+
+	num = lls_uint32_val(0, r_c);
+	color = lls_enum_string_val(num, o_c);
+	printf("%s value: #%d: %s\n", c_given? "good" : "default", num, color);
+	printf("Band names containing '%s'\n", color);
+	switch (num) {
+	case COLOR_RED:
+		printf("Red Snapper\n");
+		printf("Red Lorry Yellow Lorry\n");
+		break;
+	case COLOR_GREEN:
+		printf("Green Day\n");
+		printf("Green Jelly\n");
+		break;
+	case COLOR_BLUE:
+		printf("Blue Cheer\n");
+		printf("Blue Öyster Cult\n");
+		break;
+	default:
+		printf("Nothing appropriate\n");
+	}
+	if (!c_given) {
+		printf("Available colors:\n");
+		for (num = 0; num < LSG_NUM_LOPSUBEX_ENUM_COLOR_VALUES; num++)
+			printf("color #%d: %s\n", num,
+				lls_enum_string_val(num, o_c));
+	}
+	return 1;
+}
+EXPORT_CMD(enum)
+
+static int com_quotes(struct lls_parse_result *lpr)
+{
+	const struct lls_opt_result *r_s = OPT_RESULT(QUOTES, CHARS, lpr);
+	const char *val= lls_string_val(0, r_s);
+
+	printf("Special characters: %s\n", val);
+	return 0;
+}
+EXPORT_CMD(quotes)
+
+static int com_help(struct lls_parse_result *lpr)
+{
+	const struct lls_command *cmd = CMD_PTR(HELP);
+	const struct lls_opt_result *r_l = OPT_RESULT(HELP, LONG, lpr);
+	char *txt;
+	int ret;
+
+	ret = lls_check_arg_count(lpr, 0, 1, NULL);
+	if (ret < 0)
+		return ret;
+	if (lls_num_inputs(lpr) > 0)
+		cmd = lookup_subcmd_or_die(lls_input(0, lpr));
+	if (lls_opt_given(r_l))
+		txt = lls_long_help(cmd);
+	else
+		txt = lls_short_help(cmd);
+	printf("%s", txt);
+	free(txt);
+	return 0;
+}
+EXPORT_CMD(help)
+
+static int com_default_val(struct lls_parse_result *lpr)
+{
+	const struct lls_opt_result *r;
+	uint32_t val1, val2;
+	const char *txt1, *txt2;
+
+	r = OPT_RESULT(DEFAULT_VAL, WIDTH, lpr);
+	val1 = lls_uint32_val(0, r);
+	r = OPT_RESULT(DEFAULT_VAL, HEIGHT, lpr);
+	val2 = lls_uint32_val(0, r);
+	printf("geometry: %" PRIu32 "x%" PRIu32 "\n", val1, val2);
+
+	r = OPT_RESULT(DEFAULT_VAL, TOWN, lpr);
+	txt1 = lls_string_val(0, r);
+	r = OPT_RESULT(DEFAULT_VAL, STREET, lpr);
+	txt2 = lls_string_val(0, r);
+	printf("address: %s, %s\n", txt2, txt1);
+
+	r = OPT_RESULT(DEFAULT_VAL, TIME, lpr);
+	val1 = lls_uint32_val(0, r);
+	txt1 = lls_enum_string_val(val1, OPT_PTR(DEFAULT_VAL, TIME));
+	r = OPT_RESULT(DEFAULT_VAL, WEEKDAY, lpr);
+	val2 = lls_uint32_val(0, r);
+	txt2 = lls_enum_string_val(val2, OPT_PTR(DEFAULT_VAL, WEEKDAY));
+	printf("when: %s %s\n", txt2, txt1);
+
+	return 0;
+}
+EXPORT_CMD(default_val)
+
+static int com_optional_arg(struct lls_parse_result *lpr)
+{
+	const struct lls_opt_result *r;
+
+	r = OPT_RESULT(OPTIONAL_ARG, WIDTH, lpr);
+
+	printf("width: %u (%u times given)\n", lls_uint32_val(0, r),
+		lls_opt_given(r));
+	r = OPT_RESULT(OPTIONAL_ARG, HEIGHT, lpr);
+	printf("height: %u (%u times given)\n", lls_uint32_val(0, r),
+		lls_opt_given(r));
+	printf("%u non-option arguments\n", lls_num_inputs(lpr));
+	return 0;
+}
+EXPORT_CMD(optional_arg)
+
+/* stringify the first argument (author information) */
+#define LOPSUBEX_AUX_INFO(_author, _perms) #_author,
+static const char * const authors[] = {LSG_LOPSUBEX_AUX_INFOS};
+#undef LOPSUBEX_AUX_INFO
+#define LOPSUBEX_AUX_INFO(_author, _perms) _perms,
+static const mode_t permissions[] = {LSG_LOPSUBEX_AUX_INFOS};
+static int com_aux_info(struct lls_parse_result *lpr)
+{
+	const struct lls_command *cmd;
+	int i;
+
+	for (i = 0; (cmd = lls_cmd(i, lopsubex_suite)); i++) {
+		const char *name = lls_command_name(cmd);
+		printf("%s: ", name);
+		printf("author: %s, permissions: %o\n", authors[i],
+			permissions[i]);
+	}
+	return 0;
+}
+EXPORT_CMD(aux_info)
+
+int main(int argc, char **argv)
+{
+	int ret;
+	const struct lls_command *cmd;
+	struct lls_parse_result *lpr;
+	const struct local_command_info *lci;
+	char *errctx;
+
+	if (argc <= 1) {
+		printf("Usage: %s <subcommand> [options]\n", argv[0]);
+		print_available_commands();
+		exit(EXIT_FAILURE);
+	}
+	cmd = lookup_subcmd_or_die(argv[1]);
+	ret = lls_parse(argc - 1, argv + 1, cmd, &lpr, &errctx);
+	if (ret < 0) {
+		printf("%s: %s\n", errctx, lls_strerror(-ret));
+		free(errctx);
+		exit(EXIT_FAILURE);
+	}
+	lci = lls_user_data(cmd);
+	ret = lci->handler(lpr);
+	lls_free_parse_result(lpr, cmd);
+	exit(ret < 0? EXIT_FAILURE : EXIT_SUCCESS);
+}
diff --git a/lopsubex.suite b/lopsubex.suite
new file mode 100644
index 0000000..98c5649
--- /dev/null
+++ b/lopsubex.suite
@@ -0,0 +1,392 @@
+# Written 2016 by Andre Noll <maan@tuebingen.mpg.de>
+#
+# Public domain, no copyright claims.
+
+[suite lopsubex]
+aux_info_prefix = further information:
+aux_info_default = (unknown), S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH
+caption = lopsubex subcommands
+# This will be printed before the list of subcommands
+[supercommand lopsubex]
+	purpose = illustrate lopsub features
+	non-opts-name = [<subcommand>] [options]
+	[description]
+		This program illustrates the various features of the lopsub option
+		parser. Consult the lopsubex.suite file and the source in lopsubex.c
+		to see how the subcommands described in this document are implemented.
+	[/description]
+	[closing]
+		When executed with no argument, the program lists the available
+		subcommands.  Otherwise the first argument must be a subcommand from
+		the list below.
+	[/closing]
+
+[introduction]
+	Each subcommand of lopsubex illustrates a different feature of the
+	lopsub library.
+[/introduction]
+
+[subcommand flag]
+	purpose = options with no arguments
+	[description]
+		Flags are the simplest type of options as they take no argument.
+		To create a flag option, simply omit arg_type, arg_info, and typestr
+		in the suite file.
+	[/description]
+	[option simple]
+		summary = simplest option on the planet
+	[option sqrt4]
+		short_opt = 2
+		summary = Flag option with a short option equivalent.
+	[closing]
+		Lopsub counts the number of times an option was given. This can be
+		used, for example, to set the verbosity level of the application.
+
+		Decimal digits are allowed as short option equivalent for a long
+		option.
+	[/closing]
+
+[subcommand int-param]
+	purpose = options which take an integer argument
+	[description]
+		Options may be specified to take an integer argument. This subcommand
+		provides a simple example.
+	[/description]
+	[option rotate]
+		short_opt = r
+		summary = example option which takes a required integer argument
+		arg_info = required_arg
+		arg_type = int32
+		typestr = degrees
+		[help]
+			Integers may be specified as a C99 decimal, hexadecimal or octal
+			constant.
+
+			The type of the argument for this option is a signed 32 bit integer,
+			so negative values are allowed.
+		[/help]
+
+[subcommand multiple]
+	purpose = options that can be specified more than once
+	[description]
+		The multiple flag indicates that an option may be given more than
+		once. This instructs the parser to make all given arguments available
+		to the application via the parse_result structure which is returned
+		from lls_parse().
+	[/description]
+	[option verbose]
+		short_opt = v
+		summary = may be given multiple times, takes no argument
+		[help]
+			For flag options (options which do not take an argument), the number
+			of times the flag was given is stored in the parse result, regardless
+			of whether the multiple flag was set in the suite file.
+
+			To specify the option twice, one may write either -v -v or -vv.
+		[/help]
+	[option input-file]
+		short_opt = i
+		summary = multiple string values may be given
+		[help]
+			The subcommand will print all given values.
+		[/help]
+		arg_info = required_arg
+		arg_type = string
+		typestr = path
+		flag multiple
+	[option output-file]
+		short_opt = o
+		summary = only one value is stored in the parse result.
+		[help]
+			Since this option is not declared as multiple, only one value is
+			stored in the parse result. If the option was given more than once,
+			the last given value wins.
+		[/help]
+		arg_info = required_arg
+		arg_type = string
+		typestr = path
+		default_val = /dev/null
+	[closing]
+		Run this command and specify each option more than once to see
+		the effect.
+	[/closing]
+
+[subcommand custom-synopsis]
+	purpose = overwrite the default usage string
+	synopsis = [file...]
+	[description]
+		If a synopsis text is specified, this text is shown
+		as the usage string in the help output. Otherwise,
+		lopsub creates a suitable string on its own.
+
+		In this example, the synopsis text is set to "[file...]".
+	[/description]
+
+[subcommand enum]
+	purpose = enumerable options
+	[description]
+		In this command, --color is an enum option, which takes the name of a
+		color as its argument. Only a pre-defined set of colors are accepted,
+		as defined in the suite file.
+
+		The last value (black) shows how to specify values with embedded
+		spaces and quotes.
+	[/description]
+	[option color]
+		summary = name of a color
+		short_opt = c
+		arg_info = required_arg
+		arg_type = string
+		typestr = color
+		values = {
+			COLOR_RED = "red",
+			COLOR_GREEN = "green",
+			COLOR_BLUE = "blue",
+			COLOR_YELLOW = "yellow",
+			COLOR_BLACK = "black (that's not really a \"color\")"
+		}
+		default_val = green
+
+[subcommand serialize]
+	purpose = write a parse result into a buffer
+	[description]
+		The lopsub library provides a function to serialize the result
+		of a successful call to lls_parse(). This subcommand illustrates
+		this feature. First it parses the given arguments to produce a
+		parse result. Next it serializes the parse result into a buffer
+		and de-serializes this buffer into a second parse result. A text
+		which refers to the parsed values is printed twice, first with the
+		original parse result, then with the de-serialized version. The two
+		texts should be identical.
+	[/description]
+	[option fruit]
+		short_opt = f
+		arg_info = required_arg
+		arg_type = string
+		typestr = fruit
+		flag multiple
+		default_val = apples
+	[option amount]
+		short_opt = a
+		arg_info = required_arg
+		arg_type = uint32
+		typestr = g
+		default_val = 100
+	[option sugar]
+		short_opt = s
+	[option container]
+		short_opt = c
+		arg_type = string
+		arg_info = optional_arg
+		default_val = bowl
+
+[subcommand non-ascii]
+	purpose = use of non-ASCII characters (e.g., umlauts like 'ä')
+	[description]
+		Non-ASCII characters are not allowed for command and option names. They
+		may appear, however, in the purpose text of a command (see above),
+		in the type string and the description of an option (see below),
+		and also in a help text like this: öäüß. Of course, non-ASCII
+		characters are also allowed in the argument to a string option.
+
+		The help text generated by the lopsub library functions should just
+		work on any system where UTF-8 is the default character encoding.
+
+		For generating man pages, however, UTF-8 will not do, because
+		groff interprets input character codes between 127 and 255 as the
+		corresponding characters in the latin1 (ISO-8859-1) code set. Hence,
+		it is necessary to format the generated with the command preconv -e
+		UTF-8. The man(1) command of the man-db package (default on most
+		Linux distributions) does this automatically, so man pages should
+		render correctly on those systems. On other systems it might help to
+		convert the suite file to ISO-8859-1 before feeding it to lopsubgen:
+
+		     iconv -t ISO_8859-1 app.suite | ./lopsubgen --gen-man
+
+	[/description]
+	[option city]
+		summary = name of a big city (Großstadt)
+		[help]
+			The command prints a more or less interesting sentence about the
+			given city. At the moment, only Göttingen is supported.
+		[/help]
+		short_opt = c
+		arg_info = required_arg
+		arg_type = string
+		typestr = Großstadt
+		default_val = Göttingen
+
+[subcommand quotes]
+	purpose = embedded quotes (") and backslashes (\).
+	[description]
+		In the C language a double quote (") denotes the beginning or the end
+		of a string literal. Embedded double quotes must be prefixed with a
+		backslash (\), and embedded backslashes need to be doubled.
+
+		Lopsubgen handles these issues internally. Hence all help texts,
+		purpose and description strings and default values may contain single
+		(') or double quotes ("), balanced or unbalanced.
+
+		Man output has similar issues. For example, if the first word of a
+		line starts with a dot or a single quote, lopsubgen prevents roff
+		from interpreting the word. Examples:
+
+		.SH This is the path to a hidden version of /bin/sh. It should not
+		be mistaken as a roff man macro for an unnumbered section heading.
+
+		'In the roff type-setting system, a single quote at the beginning
+		of a line indicates a non-breaking control character. Lopsubgen will
+		escape such lines automatically.
+
+	[/description]
+	[option chars]
+		summary = specify problematic characters (e.g., "'`$\.)
+		[help]
+			Single (') and  double quotes (") are also allowed in the type string
+			and the default value of an option.
+		[/help]
+		short_opt = s
+		arg_info = required_arg
+		arg_type = string
+		typestr = "set"
+		default_val = .$`"'%#?*!/\
+
+[subcommand help]
+	purpose = automatically generated help texts
+	non-opts-name = [<subcommand>]
+	[description]
+		The lopsub library provides functions which format the options and
+		the help text of a command. Short and long help texts are available.
+	[/description]
+	[option long]
+		summary = print the long help text
+		short_opt = l
+		[help]
+			The short help omits the text of the suite file enclosed between the
+			[help] and [/help] markers while the long version includes this text.
+		[/help]
+
+[subcommand aux_info]
+	purpose = stash additional per-command information into a suite file
+	[description]
+		The aux_info feature of lopsub allows to add additional information
+		to the subcommands of a suite without the need to maintain another
+		per-command array, which would be error-prone.
+
+		To illustrate the feature, the command section for this subcommand
+		contains an author name and a (fictitious) permission value,
+		realized as the OR of the usual file mode bits. When the subcommand
+		is executed, it prints this information for each subcommand.
+
+		Note that the man page contains the symbolic names of the permission
+		bits while the code in the aux_info command handler of lopsubex.c
+		gets the numeric value.
+	[/description]
+	aux_info = Random J. Hacker, S_IRWXU
+
+[subcommand default-val]
+	purpose = how default values are handled
+	[description]
+		Run this subcommand with no arguments to see how default values apply,
+		depending on the type of the argument and whether a default value is
+		specified in the suite file.
+	[/description]
+	[option width]
+		summary = numeric argument with default value
+		short_opt = w
+		arg_info = required_arg
+		arg_type = uint32
+		typestr = pixels
+		default_val = 42
+	[option height]
+		summary = numeric argument without default value
+		short_opt = h
+		arg_info = required_arg
+		arg_type = uint32
+		typestr = pixels
+	[option town]
+		short_opt = t
+		summary = string argument with default value
+		arg_info = required_arg
+		arg_type = string
+		typestr = name
+		default_val = Berlin
+	[option street]
+		short_opt = s
+		summary = string argument without default value
+		arg_info = required_arg
+		arg_type = string
+		typestr = streetname
+	[option time]
+		summary = enum option with default value
+		short_opt = T
+		arg_info = required_arg
+		arg_type = string
+		typestr = daytime
+		values = {
+			DT_MORNING = "morning",
+			DT_AFTERNOON = "afternoon",
+			DT_EVENING = "evening",
+			DT_NIGHT = "night"
+		}
+		default_val = night
+	[option weekday]
+		summary = enum option without default value
+		short_opt = w
+		arg_info = required_arg
+		arg_type = string
+		typestr = dayofweek
+		values = {
+			DOW_MONDAY = "Monday",
+			DOW_TUESDAY = "Tuesday",
+			DOW_WEDNESDAY = "Wednesday",
+			DOW_THURSDAY = "Thursday",
+			DOW_FRIDAY = "Friday",
+			DOW_SATURDAY = "Saturday",
+			DOW_SUNDAY = "Sunday"
+		}
+
+[subcommand optional-arg]
+	purpose = options with optional argument
+	non-opts-name = <file>
+	[description]
+		Options which take an optional argument behave much like like options
+		with required argument. If the option is not given, or is given with
+		no argument supplied, the default value is substituted, with the
+		semantics illustrated in the default-val subcommand.
+
+		Note that the optional argument must be specified as in --opt=arg
+		rather than --opt arg because the latter form is ambiguous (arg could
+		also be a non-option argument).
+
+		Run this subcommand with -w=1, then with -w 1 to see the
+		difference. Also note the difference between -w 1 and -h 1.
+	[/description]
+	[option width]
+		summary = option with optional uint32 argument
+		short_opt = w
+		arg_info = optional_arg
+		arg_type = uint32
+		typestr = pixels
+		default_val = 42
+	[option height]
+		summary = option with required uint32 argument
+		short_opt = h
+		arg_info = required_arg
+		arg_type = uint32
+		typestr = pixels
+
+[conclusion]
+	This concludes the description of the subcommands of lopsubex. For
+	further information, consult the source code.
+[/conclusion]
+[section copyright]
+	Written by Andre Noll
+	.br
+	Public domain, no copyright claims.
+	.br
+	Report bugs to
+	.MT <maan@tuebingen.mpg.de>
+	Andre Noll
+	.ME
+[/section]
diff --git a/lopsubgen.l b/lopsubgen.l
new file mode 100644
index 0000000..f5db52b
--- /dev/null
+++ b/lopsubgen.l
@@ -0,0 +1,481 @@
+/*
+ * Copyright (C) 2016 Andre Noll <maan@tuebingen.mpg.de>
+ *
+ * Licensed under the GPL v3, see http://www.gnu.org/licenses/gpl-3.0.html
+ */
+
+%option noyywrap
+%option stack
+%option never-interactive
+%option yylineno
+
+%s SC_COMMAND
+%s SC_OPTION
+%s SC_ARG_INFO
+%s SC_ARG_TYPE
+%s SC_OPTION_FLAG
+%s SC_CHAR
+%s SC_INTEGER
+%s SC_UNQUOTED_LINE
+%s SC_UNQUOTED_LINE_CHECK_DEFAULT
+%s SC_ERROR
+%s SC_VALUES_ID
+%s SC_VALUES_COMMA_OR_BRACE
+
+%x SC_INTRODUCTION
+%x SC_DESCRIPTION
+%x SC_CLOSING
+%x SC_HELP
+%x SC_CONCLUSION
+%x SC_SECTION
+%{
+	#include <ctype.h>
+	#include <stdlib.h>
+	#include <assert.h>
+	#include <stdbool.h>
+
+	#include "lsg.h"
+
+	static char **charpp;
+	static char *text_buf;
+	static size_t text_buf_len;
+	struct lsg_suite suite;
+
+	#define CURCMD (suite.commands[suite.num_subcommands])
+	#define CUROPT (CURCMD.options[CURCMD.num_options - 1])
+	#define CURSECT (suite.sections[suite.num_sections - 1])
+
+	static void *xmalloc(size_t size)
+	{
+		void *p;
+
+		assert(size > 0);
+		p = malloc(size);
+		assert(p);
+		return p;
+	}
+	void *xrealloc(void *ptr, size_t size)
+	{
+		void *p;
+		assert(size > 0);
+		p = realloc(ptr, size);
+		assert(p);
+		return p;
+	}
+
+	/*
+	 * Extract ID from a string like [foo ID] or bar = ID, or a substring
+	 * of a list: ID1, ID2, ...
+	 */
+	static char *parse_identifier(char *p)
+	{
+		char *p2, *eq;
+
+		if (*p == '[') {
+			while (*p && isspace(*p))
+				p++;
+			while (*p && !isspace(*p))
+				p++;
+		} else {
+			if ((eq = strchr(p + 1, '=')))
+				p = eq + 1;
+			else
+				while (*p && (isspace(*p) || *p == ','))
+					p++;
+		}
+		assert(*p);
+		while (*p && isspace(*p))
+			p++;
+		assert(*p);
+		p2 = p;
+		while (isalnum(*p2) || *p2 == '_' || *p2 == '-')
+			p2++;
+		*p2 = '\0';
+		return strdup(p);
+	}
+
+	static char *parse_simple_string(void)
+	{
+		char *result, *p = yytext;
+		while (isspace(*p))
+			p++;
+		assert(*p == '[');
+		p++;
+		while (isspace(*p))
+			p++;
+		while (!isspace(*p)) /* skip "section" */
+			p++;
+		while (isspace(*p))
+			p++;
+		result = strdup(p);
+		p = strrchr(result, ']');
+		do {
+			*p = '\0';
+			p--;
+		} while (isspace(*p));
+		return result;
+	}
+	static void parse_id_string(void)
+	{
+		char *p, *q;
+		int val_num = CUROPT.num_values++, num_vals = val_num + 1;
+		bool backslash;
+
+		CUROPT.values = xrealloc(CUROPT.values,
+			num_vals * sizeof(char *));
+		CUROPT.value_ids = xrealloc(CUROPT.value_ids,
+			num_vals * sizeof(char *));
+		CUROPT.value_literals = xrealloc(CUROPT.value_literals,
+			num_vals * sizeof(char *));
+		CUROPT.value_ids[val_num] = p = strdup(yytext);
+		while (*p && !isspace(*p) && *p != '=')
+			p++;
+		*p = '\0';
+		p++;
+		while (*p && *p != '\"')
+			p++;
+		CUROPT.value_literals[val_num] = p;
+		p++;
+		CUROPT.values[val_num] = q = xmalloc(strlen(p) + 1);
+		for (backslash = false; *p; p++) {
+			if (*p == '\\') {
+				if (!backslash) {
+					backslash = true;
+					continue;
+				}
+			} else if (*p == '"') {
+				if (!backslash) {
+					*q = '\0';
+					return;
+				}
+			}
+			*q++ = *p;
+			backslash = false;
+		}
+		assert(false);
+	}
+	static char *parse_unquoted_line(void)
+	{
+		char *p = strdup(yytext);
+		size_t n = strlen(p);
+		for (; n > 0; n--) {
+			if (isspace(p[n - 1]))
+				continue;
+			p[n] = '\0';
+			break;
+		}
+		return p;
+	}
+	static void check_default_val(void)
+	{
+		int i;
+
+		if (!CUROPT.default_val)
+			return;
+		if (!CUROPT.values)
+			return;
+		for (i = 0; i < CUROPT.num_values; i++) {
+			char *val = CUROPT.values[i];
+			char buf[40];
+			if (strcmp(val, CUROPT.default_val))
+				continue;
+			sprintf(buf, "%i", i);
+			free(CUROPT.default_val);
+			CUROPT.default_val = strdup(buf);
+			return;
+		}
+		fprintf(stderr, "option %s: bad default value %s\n",
+			CUROPT.name.orig, CUROPT.default_val);
+		exit(EXIT_FAILURE);
+	}
+
+%}
+EQUALS [[:space:]]*=[[:space:]]*
+IDENTIFIER [a-zA-Z]+[a-zA-Z0-9_-]*
+C99_DECIMAL_CONSTANT -?([[:digit:]]{-}[0])[[:digit:]]*
+C99_HEXADECIMAL_CONSTANT 0[xX][[:xdigit:]]+
+C99_OCTAL_CONSTANT 0[01234567]*
+INT_CONSTANT {C99_DECIMAL_CONSTANT}|{C99_HEXADECIMAL_CONSTANT}|{C99_OCTAL_CONSTANT}
+STRING_VALUE \"([^\"\\\n]|(\\[\"\\]))*\"
+SIMPLE_STRING [[:alnum:]]([[:alnum:]]|[[:space:]])*
+%%
+
+ /* skip comments and whitespace */
+^[[:space:]]*#.*\n ;
+[[:space:]]|\n+ ;
+
+<INITIAL>\[[[:space:]]*suite[[:space:]]+{IDENTIFIER}[[:space:]]*\] {
+	free(suite.name.orig);
+	suite.name.orig = parse_identifier(yytext);
+}
+
+<INITIAL>caption{EQUALS} {
+	charpp = &suite.caption;
+	yy_push_state(SC_UNQUOTED_LINE);
+}
+
+<INITIAL>title{EQUALS} {
+	charpp = &suite.title;
+	yy_push_state(SC_UNQUOTED_LINE);
+}
+
+<INITIAL>mansect{EQUALS} {
+	charpp = &suite.mansect;
+	yy_push_state(SC_UNQUOTED_LINE);
+}
+
+<INITIAL>date{EQUALS} {
+	charpp = &suite.date;
+	yy_push_state(SC_UNQUOTED_LINE);
+}
+
+<INITIAL>version-string{EQUALS} {
+	charpp = &suite.version_string;
+	yy_push_state(SC_UNQUOTED_LINE);
+}
+
+<INITIAL>manual_title{EQUALS} {
+	charpp = &suite.manual_title;
+	yy_push_state(SC_UNQUOTED_LINE);
+}
+
+<INITIAL>aux_info_prefix{EQUALS} {
+	charpp = &suite.aux_info_prefix;
+	yy_push_state(SC_UNQUOTED_LINE);
+}
+
+<INITIAL>aux_info_default{EQUALS} {
+	charpp = &suite.aux_info_default;
+	yy_push_state(SC_UNQUOTED_LINE);
+}
+
+<INITIAL,SC_COMMAND,SC_OPTION>\[[[:space:]]*introduction[[:space:]]*\] {
+	text_buf = NULL;
+	text_buf_len = 0;
+	yy_push_state(SC_INTRODUCTION);
+}
+
+<SC_INTRODUCTION>[[:space:]]*\[[[:space:]]*\/introduction[[:space:]]*\]\n {
+	suite.introduction = text_buf;
+	yy_pop_state();
+}
+
+<INITIAL,SC_COMMAND,SC_OPTION>\[[[:space:]]*conclusion[[:space:]]*\] {
+	text_buf = NULL;
+	text_buf_len = 0;
+	yy_push_state(SC_CONCLUSION);
+}
+
+<SC_CONCLUSION>[[:space:]]*\[[[:space:]]*\/conclusion[[:space:]]*\]\n {
+	suite.conclusion = text_buf;
+	yy_pop_state();
+}
+
+<INITIAL>\[[[:space:]]*supercommand[[:space:]]+{IDENTIFIER}[[:space:]]*\] {
+	struct lsg_command *cmd;
+
+	if (!suite.commands)
+		suite.commands = xmalloc(sizeof(*suite.commands));
+	cmd = suite.commands;
+	memset(cmd, 0, sizeof(*cmd));
+	cmd->name.orig = parse_identifier(yytext);
+	cmd->options = xmalloc(sizeof(*cmd->options));
+	BEGIN(SC_COMMAND);
+}
+
+<INITIAL,SC_COMMAND,SC_OPTION>\[[[:space:]]*subcommand[[:space:]]+{IDENTIFIER}[[:space:]]*\] {
+	int command_num = ++suite.num_subcommands;
+	struct lsg_command *cmd;
+
+	suite.commands = realloc(suite.commands,
+		(suite.num_subcommands + 1) * sizeof(*suite.commands));
+	cmd = suite.commands + command_num;
+	memset(cmd, 0, sizeof(*cmd));
+	cmd->name.orig = parse_identifier(yytext);
+	cmd->options = xmalloc(sizeof(*cmd->options));
+	BEGIN(SC_COMMAND);
+}
+
+<SC_COMMAND>\[[[:space:]]*description[[:space:]]*\] {
+	text_buf = NULL;
+	text_buf_len = 0;
+	yy_push_state(SC_DESCRIPTION);
+}
+
+<SC_COMMAND,SC_OPTION>\[[[:space:]]*closing[[:space:]]*\] {
+	text_buf = NULL;
+	text_buf_len = 0;
+	yy_push_state(SC_CLOSING);
+}
+
+<SC_OPTION>\[[[:space:]]*help[[:space:]]*\] {
+	text_buf = NULL;
+	text_buf_len = 0;
+	yy_push_state(SC_HELP);
+}
+<INITIAL,SC_OPTION,SC_COMMAND>\[[[:space:]]*section[[:space:]]+{SIMPLE_STRING}[[:space:]]*\] {
+	int sect_num = suite.num_sections++;
+	suite.sections = realloc(suite.sections,
+		 suite.num_sections * sizeof(*suite.sections));
+	CURSECT.name.orig = parse_simple_string();
+	text_buf = NULL;
+	text_buf_len = 0;
+	yy_push_state(SC_SECTION);
+}
+
+<SC_DESCRIPTION>[[:space:]]*\[[[:space:]]*\/description[[:space:]]*\]\n {
+	CURCMD.description = text_buf;
+	yy_pop_state();
+}
+
+<SC_CLOSING>[[:space:]]*\[[[:space:]]*\/closing[[:space:]]*\]\n {
+	CURCMD.closing = text_buf;
+	yy_pop_state();
+}
+
+<SC_HELP>[[:space:]]*\[[[:space:]]*\/help[[:space:]]*\]\n {
+	CUROPT.help = text_buf;
+	yy_pop_state();
+}
+
+<SC_SECTION>[[:space:]]*\[[[:space:]]*\/section[[:space:]]*\]\n {
+	CURSECT.text = text_buf;
+	yy_pop_state();
+}
+
+<SC_DESCRIPTION,SC_HELP,SC_SECTION,SC_CLOSING,SC_INTRODUCTION,SC_CONCLUSION>.*\n {
+	size_t new_len = text_buf_len + yyleng;
+	size_t num_tabs = 0;
+
+	while (yytext[num_tabs] == '\t')
+		num_tabs++;
+	new_len = text_buf_len + yyleng - num_tabs;
+	text_buf = realloc(text_buf, new_len + 1);
+	memcpy(text_buf + text_buf_len, yytext + num_tabs, yyleng - num_tabs);
+	text_buf[new_len] = '\0';
+	text_buf_len = new_len;
+}
+
+<SC_COMMAND,SC_OPTION>\[[[:space:]]*option[[:space:]]+{IDENTIFIER}[[:space:]]*\] {
+	int option_num = CURCMD.num_options++;
+	struct lsg_option *opt;
+
+	CURCMD.options = realloc(CURCMD.options,
+		CURCMD.num_options * sizeof(*CURCMD.options));
+	memset(&CUROPT, 0, sizeof(CUROPT));
+	CUROPT.name.orig = parse_identifier(yytext);
+	BEGIN(SC_OPTION);
+}
+
+<SC_OPTION>arg_info{EQUALS} BEGIN(SC_ARG_INFO);
+<SC_ARG_INFO>no_arg CUROPT.arg_info = "LLS_NO_ARGUMENT"; BEGIN(SC_OPTION);
+<SC_ARG_INFO>required_arg CUROPT.arg_info = "LLS_REQUIRED_ARGUMENT"; BEGIN(SC_OPTION);
+<SC_ARG_INFO>optional_arg CUROPT.arg_info = "LLS_OPTIONAL_ARGUMENT"; BEGIN(SC_OPTION);
+
+<SC_OPTION>arg_type{EQUALS} BEGIN(SC_ARG_TYPE);
+<SC_ARG_TYPE>none CUROPT.arg_type = "LLS_NONE"; BEGIN(SC_OPTION);
+<SC_ARG_TYPE>string CUROPT.arg_type = "LLS_STRING"; BEGIN(SC_OPTION);
+<SC_ARG_TYPE>int32 CUROPT.arg_type = "LLS_INT32"; BEGIN(SC_OPTION);
+<SC_ARG_TYPE>uint32 CUROPT.arg_type = "LLS_UINT32"; BEGIN(SC_OPTION);
+<SC_ARG_TYPE>int64 CUROPT.arg_type = "LLS_INT64"; BEGIN(SC_OPTION);
+<SC_ARG_TYPE>uint64 CUROPT.arg_type = "LLS_UINT64"; BEGIN(SC_OPTION);
+
+<SC_OPTION>flag BEGIN(SC_OPTION_FLAG);
+<SC_OPTION_FLAG>multiple CUROPT.multiple = true; BEGIN(SC_OPTION);
+<SC_OPTION_FLAG>required CUROPT.required = true; BEGIN(SC_OPTION);
+<SC_OPTION_FLAG>ignored CUROPT.ignored = true; BEGIN(SC_OPTION);
+
+<SC_OPTION>default_val{EQUALS} {
+	charpp = &CUROPT.default_val;
+	if (!CUROPT.arg_type || strcmp(CUROPT.arg_type, "LLS_NONE") == 0) {
+		fprintf(stderr, "default_value for option w/o arguments!?\n");
+		exit(1);
+	} else if (strcmp(CUROPT.arg_type, "LLS_STRING") == 0)
+		yy_push_state(SC_UNQUOTED_LINE_CHECK_DEFAULT);
+	else
+		yy_push_state(SC_INTEGER);
+}
+<SC_OPTION>short_opt{EQUALS} BEGIN(SC_CHAR);
+<SC_CHAR>[a-zA-Z0-9] CUROPT.short_opt = yytext[0]; BEGIN(SC_OPTION);
+
+<SC_OPTION>values{EQUALS}\{ {
+	if (!CUROPT.arg_type || strcmp(CUROPT.arg_type, "LLS_STRING")) {
+		fprintf(stderr, "value list is only supported for string options\n");
+		exit(EXIT_FAILURE);
+	}
+	if (!CUROPT.arg_info || !strcmp(CUROPT.arg_info, "LLS_NO_ARGUMENT")) {
+		fprintf(stderr, "enum options must take an argument\n");
+		exit(EXIT_FAILURE);
+	}
+	if (CUROPT.default_val) {
+		fprintf(stderr, "value list must preceed default value\n");
+		exit(EXIT_FAILURE);
+	}
+	BEGIN(SC_VALUES_ID);
+}
+
+<SC_VALUES_ID>{IDENTIFIER}{EQUALS}{STRING_VALUE} {
+	parse_id_string();
+	BEGIN(SC_VALUES_COMMA_OR_BRACE);
+}
+
+<SC_VALUES_COMMA_OR_BRACE>[,\}] {
+	if (*yytext == ',')
+		BEGIN(SC_VALUES_ID);
+	else {
+		check_default_val();
+		BEGIN(SC_OPTION);
+	}
+}
+
+<SC_OPTION>summary{EQUALS} {
+	charpp = &CUROPT.summary;
+	yy_push_state(SC_UNQUOTED_LINE);
+}
+<SC_OPTION>typestr{EQUALS} {
+	charpp = &CUROPT.typestr;
+	yy_push_state(SC_UNQUOTED_LINE);
+}
+
+<SC_COMMAND>purpose{EQUALS} {
+	charpp = &CURCMD.purpose;
+	yy_push_state(SC_UNQUOTED_LINE);
+}
+
+<SC_COMMAND>non-opts-name{EQUALS} {
+	charpp = &CURCMD.non_opts_name;
+	yy_push_state(SC_UNQUOTED_LINE);
+}
+
+<SC_COMMAND>synopsis{EQUALS} {
+	charpp = &CURCMD.synopsis;
+	yy_push_state(SC_UNQUOTED_LINE);
+}
+
+<SC_COMMAND>aux_info{EQUALS} {
+	charpp = &CURCMD.aux_info;
+	yy_push_state(SC_UNQUOTED_LINE);
+}
+
+<SC_UNQUOTED_LINE>.*\n {
+	*charpp = parse_unquoted_line();
+	yy_pop_state();
+}
+<SC_UNQUOTED_LINE_CHECK_DEFAULT>.*\n {
+	*charpp = parse_unquoted_line();
+	check_default_val();
+	yy_pop_state();
+}
+
+<SC_INTEGER>{INT_CONSTANT} *charpp = strdup(yytext); yy_pop_state();
+
+ /* This rule runs iff none of the above patterns matched */
+. {
+	fprintf(stderr, "parse error at line %d. Unmatched: \"%s\"\n",
+		yyget_lineno(), yytext);
+	BEGIN(SC_ERROR);
+}
+<SC_ERROR>.*\n {
+	fprintf(stderr, "subsequent unparsed input: %s\n", yytext);
+	exit(EXIT_FAILURE);
+}
diff --git a/lopsubgen.suite b/lopsubgen.suite
new file mode 100644
index 0000000..d8166ab
--- /dev/null
+++ b/lopsubgen.suite
@@ -0,0 +1,118 @@
+# Copyright (C) 2016 Andre Noll <maan@tuebingen.mpg.de>
+#
+# Licensed under the GPL v3, see http://www.gnu.org/licenses/gpl-3.0.html
+
+[suite lopsubgen]
+[supercommand lopsubgen]
+	[description]
+		The lopsubgen command reads a lobsub suite from stdin and converts
+		it to zero or more output formats. If no output format is specified,
+		the input is only checked for syntactic correctness.
+
+		The format of the input (the lopsub suite) is described in
+		lopsub-suite(5).
+	[/description]
+	purpose = convert a lobsup suite into C or roff format
+	[option ignored]
+		summary = General options
+		flag ignored
+	[option help]
+		short_opt = h
+		summary = print help and exit (give twice for detailed help)
+	[option version]
+		short_opt = V
+		summary = print version and exit
+	[option output-dir]
+		short_opt = o
+		summary = where to write output file(s)
+		arg_info = required_arg
+		arg_type = string
+		default_val = .
+		typestr = dir
+		[help]
+			The default is to create all output files in the current working
+			directory.
+		[/help]
+	[option gen-c]
+		summary = generate C output
+		arg_info = optional_arg
+		arg_type = string
+		typestr = path
+		[help]
+			This produces a C file containing the definition of a subsub suite
+			structure.
+
+			If <path> is absolute, the output is written to this path and the
+			argument to --output-dir is ignnored. Otherwise, the output path
+			is relative to the value of the --output-dir option.
+
+			If the optional argument is not given, the output file name is
+			derived from the suite name by appending the string ".lsg.c".
+		[/help]
+	[option gen-header]
+		summary = generate a .h file
+		arg_info = optional_arg
+		arg_type = string
+		typestr = path
+		[help]
+			The generated header file is intended to be included from the
+			application. It defines handy C enums and preprocessor macros like
+			the number of commands defined in the suite.
+
+			The path for the generated header file is determined in the same way
+			as for C output, see --gen-c.
+		[/help]
+	[option ignored]
+		summary = Options for man output
+		flag ignored
+	[option gen-man]
+		summary = generate the man page
+		arg_info = optional_arg
+		arg_type = string
+		typestr = path
+		[help]
+			If this is not given, all subsequent options in this section are
+			ignored.
+
+			The path for the output file is determined in the same way as for C
+			output, see --gen-c.
+		[/help]
+	[option version-string]
+		summary = override version string
+		arg_info = required_arg
+		arg_type = string
+		typestr = string
+		[help]
+			If this option is given, its argument is used as the version string
+			while the value of the version-string directive of the suite is
+			ignored. This is useful for applications which dynamically create
+			the version string by running a command like git-describe.
+		[/help]
+
+[section copyright]
+
+	Written by Andre Noll
+	.br
+	Copyright (C) 2016 Andre Noll
+	.br
+	License: GNU GPL version 3,
+	.UR http://www.gnu.org/licenses/gpl-3.0.html
+	.UE
+	.br
+	This is free software: you are free to change and redistribute it.
+	.br
+	There is NO WARRANTY, to the extent permitted by law.
+	.br
+	Report bugs to
+	.MT <maan@tuebingen.mpg.de>
+	Andre Noll
+	.ME
+[/section]
+
+[section see also]
+	lopsub-suite(5), lopsub(7)
+
+	Homepage:
+	.UR http://people.tuebingen.mpg.de/~maan/lopsub
+	.UE
+[/section]
diff --git a/lsg.c b/lsg.c
new file mode 100644
index 0000000..54b7816
--- /dev/null
+++ b/lsg.c
@@ -0,0 +1,812 @@
+/*
+ * Copyright (C) 2016 Andre Noll <maan@tuebingen.mpg.de>
+ *
+ * Licensed under the GPL v3, see http://www.gnu.org/licenses/gpl-3.0.html
+ */
+
+#include <stdlib.h>
+#include <stdio.h>
+#include <ctype.h>
+#include <stdbool.h>
+#include <assert.h>
+#include <string.h>
+#include <time.h>
+
+#include "lsg.h"
+#include "lopsub-internal.h"
+#include "lopsub.h"
+
+/*
+ * To stringify the result of the *expansion* of a macro argument, we have to
+ * use two levels of macros.
+ */
+#define LLS_STRINGIFY_EXPAND(_arg) LLS_STRINGIFY(_arg)
+#define LLS_STRINGIFY(_arg) #_arg
+#define LLS_ABI_VERSION_VAR_STRING LLS_STRINGIFY_EXPAND(LLS_ABI_VERSION_VAR)
+
+int yylex(void);
+
+static void gen_license_header(FILE *out, const char *cmdline, const char *pfx,
+		const char *sfx)
+{
+	fprintf(out, "%sautogenerated by lopsubgen version %s%s\n",
+		pfx, lls_version(), sfx);
+	if (cmdline) {
+		fprintf(out, "%scommand line:", pfx);
+		fprintf(out, " %s", cmdline);
+		fprintf(out, "%s\n", sfx);
+	}
+	fprintf(out, "%sPublic domain, no copyright claims.%s\n",
+		pfx, sfx);
+}
+
+static void inplace_sanitize(char *src)
+{
+	for (; *src; src++)
+		if (*src == '-')
+			*src = '_';
+}
+
+static void inplace_toupper(char *src)
+{
+	for (; *src; src++)
+		*src = toupper((int)*src);
+}
+
+static void lsg_init_name(struct lsg_name *name)
+{
+	assert(name->orig);
+	name->sanitized = strdup(name->orig);
+	inplace_sanitize(name->sanitized);
+	name->capitalized = strdup(name->sanitized);
+	inplace_toupper(name->capitalized);
+}
+
+static void print_tabs(int num, FILE *out)
+{
+	while (--num >= 0)
+		fprintf(out, "\t");
+}
+
+static void format_c_text(const char *text, const char *member, int indent,
+		FILE *out)
+{
+	int i;
+
+	if (!text)
+		return;
+	print_tabs(indent, out);
+	fprintf(out, ".%s = (char []) {", member);
+	for (i = 0; text[i]; i++) {
+		if ((i % 8) == 0) {
+			fprintf(out, "\n");
+			print_tabs(indent + 1, out);
+		}
+		fprintf(out, "0x%02x,", (unsigned char)text[i]);
+	}
+	fprintf(out, "0x00\n");
+	print_tabs(indent, out);
+	fprintf(out, "},\n");
+}
+
+static void format_flags(struct lsg_option *opt, FILE *out)
+{
+	fprintf(out, "\t\t\t\t\t.flags = 0");
+	if (opt->multiple)
+		fprintf(out, " | LLS_MULTIPLE");
+	if (opt->required)
+		fprintf(out, " | LLS_REQUIRED");
+	if (opt->ignored)
+		fprintf(out, " | LLS_IGNORED");
+	if (opt->default_val)
+		fprintf(out, " | LLS_HAS_DEFAULT");
+	fprintf(out, ",\n");
+}
+
+static int string_literal(const char *src, FILE *out)
+{
+	int len = 0;
+
+	len += fprintf(out, "\"");
+	while (src && *src) {
+		if (*src == '"' || *src == '\\')
+			len += fprintf(out, "\\");
+		len += fprintf(out, "%c", *src);
+		src++;
+	}
+	len += fprintf(out, "\"");
+	return len;
+}
+
+static void format_man_text(FILE *out, bool bol, const char *text)
+{
+	int i;
+
+	if (!text)
+		return;
+	for (i = 0; text[i]; i++) {
+		switch (text[i]) {
+		case '\n':
+			fprintf(out, "\n");
+			bol = true;
+			continue;
+		case '.':
+		case '\'':
+			if (bol)
+				fprintf(out, "\\&");
+			break;
+		case '\\':
+			fprintf(out, "\\");
+			break;
+		case ' ':
+		case '\t':
+			if (bol)
+				continue;
+		}
+		bol = false;
+		fprintf(out, "%c", text[i]);
+	}
+}
+
+static int format_option_arg(const struct lsg_option *opt, FILE *out,
+		bool man_format)
+{
+	char *typestr = opt->typestr? opt->typestr : "val";
+	int arg_info, len = 0;
+
+	if (opt->ignored)
+		return 0;
+	if (!opt->arg_info)
+		arg_info = 0;
+	else if (strcmp(opt->arg_info, "LLS_NO_ARGUMENT") == 0)
+		arg_info = 0;
+	else if (strcmp(opt->arg_info, "LLS_OPTIONAL_ARGUMENT") == 0)
+		arg_info = -1;
+	else if (strcmp(opt->arg_info, "LLS_REQUIRED_ARGUMENT") == 0)
+		arg_info = 1;
+	else
+		assert(0);
+
+	if (arg_info == -1)
+		len += fprintf(out, "[");
+	if (arg_info != 0) {
+		len += fprintf(out, "=<");
+		if (man_format)
+			len += fprintf(out, "%s", typestr);
+		else {
+			len += fprintf(out, "\"");
+			len += string_literal(typestr, out);
+			len += fprintf(out, "\"");
+		}
+		fprintf(out, ">");
+	}
+	if (arg_info == -1)
+		len += fprintf(out, "]");
+	return len;
+}
+
+static void format_synopsis(const struct lsg_command *cmd, FILE *out,
+		bool man_format)
+{
+	int j, len;
+
+	if (man_format)
+		fprintf(out, "\\&");
+	if (cmd->synopsis) {
+		if (man_format)
+			format_man_text(out, true, cmd->synopsis);
+		else {
+			string_literal(cmd->synopsis, out);
+			fprintf(out, ",\n");
+		}
+		return;
+	}
+	if (!man_format)
+		fprintf(out, "\"");
+	len = strlen(cmd->name.orig) + 8;
+	for (j = 0; j < cmd->num_options; j++) {
+		struct lsg_option *opt = cmd->options + j;
+		if (opt->ignored)
+			continue;
+		if (j > 0) {
+			if (!man_format && len > 70) {
+				fprintf(out, "\\n\"\n\t\t\t\t\"       ");
+				len = 8;
+			} else
+				len += fprintf(out, " ");
+		}
+		if (!opt->required)
+			len += fprintf(out, "[");
+		len += fprintf(out, "--%s", opt->name.orig);
+		len += format_option_arg(opt, out, man_format);
+		if (!opt->required)
+			len += fprintf(out, "]");
+	}
+	if (cmd->non_opts_name) {
+		len += strlen(cmd->non_opts_name);
+		if (!man_format && len > 70)
+			fprintf(out, "\\n\"\n\t\t\t\t\"      ");
+		if (cmd->num_options > 0)
+			fprintf(out, " [--]");
+		fprintf(out, " %s", cmd->non_opts_name);
+	}
+	if (!man_format)
+		fprintf(out, "\",");
+}
+
+static void gen_c_options(const struct lsg_command *cmd, FILE *out)
+{
+	int i, j;
+
+	if (cmd->num_options == 0)
+		return;
+	fprintf(out, "\t\t.options = (struct lls_option[]) {\n");
+	for (j = 0; j < cmd->num_options; j++) {
+		struct lsg_option *opt = cmd->options + j;
+		fprintf(out, "\t\t\t{\n");
+		fprintf(out, "\t\t\t\t.name = \"%s\",\n",
+			opt->name.orig);
+		if (opt->short_opt)
+			fprintf(out, "\t\t\t\t.short_opt = '%c',\n",
+				opt->short_opt);
+		if (opt->summary) {
+			fprintf(out, "\t\t\t\t.summary = ");
+			string_literal(opt->summary, out);
+			fprintf(out, ",\n");
+		}
+		if (opt->arg_info)
+			fprintf(out, "\t\t\t\t.arg_info = %s,\n",
+				opt->arg_info);
+		if (opt->arg_type)
+			fprintf(out, "\t\t\t\t.arg_type = %s,\n",
+				opt->arg_type);
+		if (opt->typestr) {
+			fprintf(out, "\t\t\t\t.typestr = ");
+			string_literal(opt->typestr, out);
+			fprintf(out, ",\n");
+		}
+		fprintf(out, "\t\t\t\t.values = ");
+		if (opt->values) {
+			fprintf(out, "(union lls_val *)(union lls_val[]) {\n");
+			for (i = 0; i < opt->num_values; i++)
+				fprintf(out, "\t\t\t\t\t{.string_val = %s},\n",
+					opt->value_literals[i]);
+			fprintf(out, "\t\t\t\t\t{.string_val = NULL}\n");
+			fprintf(out, "\t\t\t\t},\n");
+		} else
+			fprintf(out, "NULL,\n");
+		format_flags(opt, out);
+		if (opt->default_val) {
+			bool string = strcmp(opt->arg_type, "LLS_STRING") == 0;
+			fprintf(out, "\t\t\t\t.default_val = {");
+			if (string) {
+				if (opt->values)
+					fprintf(out, ".uint32_val = ");
+				else {
+					fprintf(out, ".string_val = ");
+					string_literal(opt->default_val, out);
+				}
+			} else if (strcmp(opt->arg_type, "LLS_INT32") == 0)
+				fprintf(out, ".int32_val = ");
+			else if (strcmp(opt->arg_type, "LLS_UINT32") == 0)
+				fprintf(out, ".uint32_val = ");
+			else if (strcmp(opt->arg_type, "LLS_INT64") == 0)
+				fprintf(out, ".int64_val = ");
+			else if (strcmp(opt->arg_type, "LLS_UINT64") == 0)
+				fprintf(out, ".uint64_val = ");
+			if (!string || opt->values)
+				fprintf(out, "%s", opt->default_val);
+			fprintf(out, "},\n");
+		}
+		format_c_text(opt->help, "help", 5, out);
+		fprintf(out, "\t\t\t},\n");
+	}
+	fprintf(out, "\t\t\t{\n\t\t\t\t\t.name = NULL\n\t\t\t}\n");
+	fprintf(out, "\t\t}\n");
+}
+
+static void format_command(const struct lsg_command *cmd, FILE *out)
+{
+	if (!cmd->name.orig) {
+		fprintf(out, "{.name = NULL}\n");
+		return;
+	}
+	fprintf(out, "{\n\t\t.name = \"%s\",\n", cmd->name.orig);
+	fprintf(out, "\t\t.purpose = ");
+	string_literal(cmd->purpose, out);
+	fprintf(out, ",\n");
+	format_c_text(cmd->description, "description", 3, out);
+	if (cmd->non_opts_name || cmd->synopsis)
+		fprintf(out, "\t\t.non_opts_name = \"%s\",\n",
+			cmd->non_opts_name? cmd->non_opts_name : "");
+	fprintf(out, "\t\t.synopsis = ");
+	format_synopsis(cmd, out, false);
+	format_c_text(cmd->closing, "closing", 3, out);
+	fprintf(out, "\n\t\t.user_data = &lsg_%s_com_%s_user_data,\n",
+		suite.name.sanitized, cmd->name.sanitized);
+	fprintf(out, "\t\t.num_options = %d,\n", cmd->num_options);
+	gen_c_options(cmd, out);
+	fprintf(out, "\t}");
+}
+
+static void format_user_data(const struct lsg_command *cmd, FILE *out)
+{
+	if (!cmd->name.orig)
+		return;
+	fprintf(out, "extern const void *lsg_%s_com_%s_user_data "
+		"__attribute__ ((weak));\n",
+		suite.name.sanitized,
+		cmd->name.sanitized
+	);
+}
+
+static void gen_c(const char *outpath, const char *cmdline)
+{
+	int i;
+
+	FILE *out = fopen(outpath, "w");
+	if (!out) {
+		perror("fopen");
+		exit(EXIT_FAILURE);
+	}
+	gen_license_header(out, cmdline, "/* ", " */");
+	fprintf(out, "#include <stdlib.h>\n");
+	fprintf(out, "#include <inttypes.h>\n");
+	fprintf(out, "#include <lopsub-internal.h>\n");
+	fprintf(out, "#include <lopsub.h>\n");
+	fprintf(out, "__attribute__ ((unused)) "
+		"static const unsigned *abi_version = &%s;\n",
+		LLS_ABI_VERSION_VAR_STRING);
+	fprintf(out, "#if LLS_ABI_VERSION - %d\n", LLS_ABI_VERSION);
+	fprintf(out, "#error: \"ABI version mismatch: header version "
+		"differs from lopsubgen version\"\n");
+	fprintf(out, "#endif\n");
+	for (i = 0; i <= suite.num_subcommands; i++)
+		format_user_data(suite.commands + i, out);
+	fprintf(out, "static const struct lls_suite the_%s_suite = {\n",
+		suite.name.sanitized);
+	fprintf(out, "\t.name = \"%s\",\n", suite.name.orig);
+	if (suite.caption)
+		fprintf(out, "\t.caption = \"%s\",\n", suite.caption);
+	fprintf(out, "\t.num_subcommands = %d,\n", suite.num_subcommands);
+	fprintf(out, "\t.commands = (struct lls_command[]) {\n");
+	for (i = 0; i <= suite.num_subcommands; i++) {
+		struct lsg_command *cmd = suite.commands + i;
+		fprintf(out, "%s", i? ", " : "\t\t");
+		format_command(cmd, out);
+	}
+	fprintf(out, ", {\n\t\t\t.name = NULL\n\t\t}\n");
+	fprintf(out, "\t}\n");
+	fprintf(out, "};\n");
+	fprintf(out, "const struct lls_suite *%s_suite = &the_%s_suite;\n",
+		suite.name.sanitized, suite.name.sanitized);
+	fclose(out);
+}
+
+static inline bool has_arg(struct lsg_option *opt)
+{
+	if (!opt->arg_info)
+		return false;
+	return strcmp(opt->arg_info, "LLS_NO_ARGUMENT");
+}
+
+static void gen_header(const char *outpath, const char *cmdline)
+{
+	int i, j, k;
+	FILE *out = fopen(outpath, "w");
+	char *name;
+
+	if (!out) {
+		perror("fopen");
+		exit(EXIT_FAILURE);
+	}
+	gen_license_header(out, cmdline, "/* ", " */");
+	/* generate command enum */
+	fprintf(out, "extern const struct lls_suite *%s_suite;\n",
+		suite.name.sanitized);
+	fprintf(out, "#define LSG_%s_SUBCOMMANDS \\\n", suite.name.capitalized);
+	for (i = 1; i <= suite.num_subcommands; i++)
+		fprintf(out, "\tLSG_%s_CMD(%s), \\\n", suite.name.capitalized,
+			suite.commands[i].name.sanitized);
+	fprintf(out, "\n");
+	fprintf(out, "#define LSG_%s_COMMANDS \\\n", suite.name.capitalized);
+	name = suite.commands[0].name.sanitized;
+	fprintf(out, "\tLSG_%s_CMD(%s), \\\n", suite.name.capitalized,
+		name? name : "SUPERCOMMAND_UNAVAILABLE");
+	fprintf(out, "\tLSG_%s_SUBCOMMANDS\n", suite.name.capitalized);
+	fprintf(out, "enum lsg_%s_command {\n", suite.name.sanitized);
+	for (i = 0; i <= suite.num_subcommands; i++) {
+		struct lsg_command *cmd = suite.commands + i;
+		char *name = cmd->name.capitalized;
+
+		if (!name)
+			name = "SUPERCOMMAND_UNAVAILABLE";
+		fprintf(out, "\tLSG_%s_CMD_%s,\n", suite.name.capitalized, name);
+	}
+	fprintf(out, "};\n#define LSG_NUM_%s_SUBCOMMANDS %u\n", suite.name.capitalized,
+		suite.num_subcommands);
+	fprintf(out, "#define LSG_%s_AUX_INFOS \\\n", suite.name.capitalized);
+	for (i = 0; i <= suite.num_subcommands; i++) {
+		struct lsg_command *cmd = suite.commands + i;
+		char *ai = cmd->aux_info;
+		if (!ai) {
+			ai = suite.aux_info_default;
+			if (!ai)
+				ai = "0";
+		}
+		fprintf(out, "\t%s_AUX_INFO(%s) /* %s */ \\\n",
+			suite.name.capitalized, ai, cmd->name.orig?
+				cmd->name.orig : "NO_SUPERCOMMAND");
+	}
+	fprintf(out, "\n");
+	/* generate one option enum per command */
+	for (i = 0; i <= suite.num_subcommands; i++) {
+		struct lsg_command *cmd = suite.commands + i;
+		if (!cmd->name.orig)
+			continue;
+		fprintf(out, "enum lsg_%s_%s_option {\n", suite.name.sanitized,
+			cmd->name.sanitized);
+		for (j = 0; j < cmd->num_options; j++) {
+			struct lsg_option *opt = cmd->options + j;
+			char suffix[20] = "";
+			if (opt->ignored)
+				sprintf(suffix, "%d", j);
+			fprintf(out, "\tLSG_%s_%s_OPT_%s%s,\n",
+				suite.name.capitalized,
+				cmd->name.capitalized,
+				opt->name.capitalized,
+				suffix
+			);
+		}
+		fprintf(out, "\tLSG_NUM_%s_%s_OPTIONS\n};\n",
+			suite.name.capitalized, cmd->name.capitalized);
+
+	}
+	/* generate enumeration for options of type enum */
+	for (i = 0; i <= suite.num_subcommands; i++) {
+		struct lsg_command *cmd = suite.commands + i;
+		if (!cmd->name.orig)
+			continue;
+		for (j = 0; j < cmd->num_options; j++) {
+			struct lsg_option *opt = cmd->options + j;
+			if (!opt->values)
+				continue;
+			fprintf(out, "/* cmd %s, opt %s */\n", cmd->name.orig,
+				opt->name.orig);
+			fprintf(out, "enum {");
+			for (k = 0; k < opt->num_values; k++)
+				fprintf(out, "%s, ", opt->value_ids[k]);
+			fprintf(out, "LSG_NUM_%s_%s_%s_VALUES};\n",
+				suite.name.capitalized, cmd->name.capitalized,
+				opt->name.capitalized);
+		}
+	}
+	for (i = 0; i <= suite.num_subcommands; i++) {
+		struct lsg_command *cmd = suite.commands + i;
+		if (!cmd->name.orig)
+			continue;
+		fprintf(out, "#define LSG_%s_%s_SHORT_OPTS ",
+			suite.name.capitalized, cmd->name.capitalized);
+		for (j = 0; j < cmd->num_options; j++) {
+			struct lsg_option *opt = cmd->options + j;
+			if (!opt->short_opt)
+				continue;
+			fprintf(out, "\"-%c%s\"%s", opt->short_opt,
+				has_arg(opt)? "=" : "",
+				j == cmd->num_options - 1? "" : ", ");
+		}
+		fprintf(out, "\n");
+
+		fprintf(out, "#define LSG_%s_%s_LONG_OPTS ",
+			suite.name.capitalized, cmd->name.capitalized);
+		for (j = 0; j < cmd->num_options; j++) {
+			struct lsg_option *opt = cmd->options + j;
+			fprintf(out, "\"--%s%s\"%s", opt->name.orig,
+				has_arg(opt)? "=" : "",
+				j == cmd->num_options - 1? "" : ", ");
+		}
+		fprintf(out, "\n");
+		fprintf(out, "#define LSG_%s_%s_OPTS "
+			"LSG_%s_%s_SHORT_OPTS, LSG_%s_%s_LONG_OPTS\n",
+			suite.name.capitalized, cmd->name.capitalized,
+			suite.name.capitalized, cmd->name.capitalized,
+			suite.name.capitalized, cmd->name.capitalized
+		);
+	}
+	fclose(out);
+}
+
+static void check_option(struct lsg_option *opt)
+{
+	if (!opt->arg_info || !strcmp(opt->arg_info, "no_arg"))
+		return;
+	if (opt->arg_type && strcmp(opt->arg_type, "none"))
+		return;
+	fprintf(stderr, "option '%s': inconsistent arg_type/arg_info\n",
+		opt->name.orig);
+	exit(EXIT_FAILURE);
+}
+
+static void sanity_check(void)
+{
+	int i, j;
+
+	if (suite.num_subcommands == 0 && !suite.commands) {
+		fprintf(stderr, "no (sub)commands defined\n");
+		exit(EXIT_FAILURE);
+	}
+	for (i = 0; i <= suite.num_subcommands; i++) {
+		struct lsg_command *cmd = suite.commands + i;
+		if (!cmd->name.orig)
+			continue;
+		for (j = 0; j < cmd->num_options; j++)
+			check_option(cmd->options + j);
+	}
+}
+
+static void run_yylex(void)
+{
+	int i, j;
+
+	yylex();
+	if (!suite.name.orig)
+		suite.name.orig = strdup("lopsubgen");
+	sanity_check();
+	lsg_init_name(&suite.name);
+	for (i = 0; i <= suite.num_subcommands; i++) {
+		struct lsg_command *cmd = suite.commands + i;
+		if (!cmd->name.orig)
+			continue;
+		lsg_init_name(&cmd->name);
+		for (j = 0; j < cmd->num_options; j++)
+			lsg_init_name(&cmd->options[j].name);
+	}
+	for (i = 0; i < suite.num_sections; i++)
+		lsg_init_name(&suite.sections[i].name);
+}
+
+#ifdef STAGE1
+int main(int argc, char **argv)
+{
+	run_yylex();
+	gen_c("lopsubgen.lsg.c", NULL);
+	gen_header("lopsubgen.lsg.h", NULL);
+	return EXIT_SUCCESS;
+}
+
+#else /* STAGE1 */
+
+#include "lopsubgen.lsg.h"
+
+static char *get_output_path(const char *suffix, const char *arg,
+		const struct lls_parse_result *lpr)
+{
+	size_t len;
+	char *result, *output_dir;
+
+	output_dir = OPT_STRING_VAL(OUTPUT_DIR, lpr);
+
+	if (arg && arg[0] == '/') {
+		result = strdup(arg);
+		assert(result);
+		return result;
+	}
+	if (arg) { /* relative path */
+		len = strlen(output_dir) + strlen(arg) + 1;
+		result = malloc(len + 1);
+		assert(result);
+		sprintf(result, "%s/%s", output_dir, arg);
+		return result;
+	}
+	/* default: suite name plus suffix */
+	len = strlen(output_dir) + 1 /* slash */ + strlen(suite.name.orig)
+		+ 1 /* dot */ + 3 /* "lsg" */ + 1 /* dot */ + strlen(suffix);
+	result = malloc(len + 1);
+	assert(result);
+	sprintf(result, "%s/%s.lsg.%s", output_dir, suite.name.orig, suffix);
+	return result;
+}
+
+static void gen_man(struct lls_parse_result *lpr, const char *cmdline)
+{
+	int i;
+	time_t t;
+	struct tm *tmp;
+	FILE *out;
+	char *outpath = get_output_path("man",
+		OPT_STRING_VAL(GEN_MAN, lpr), lpr);
+
+	out = fopen(outpath, "w");
+	free(outpath);
+	if (!out) {
+		perror("fopen");
+		exit(EXIT_FAILURE);
+	}
+	gen_license_header(out, cmdline, ".\\\" ", "");
+	if (suite.commands[0].name.orig) {
+		char date[200];
+		const char *version_string;
+
+		if (!suite.date) {
+			t = time(NULL);
+			tmp = localtime(&t);
+			if (tmp == NULL) {
+				perror("localtime");
+				exit(EXIT_FAILURE);
+			}
+			if (strftime(date, sizeof(date), "%B %Y", tmp) == 0) {
+				fprintf(stderr, "strftime returned 0\n");
+				exit(EXIT_FAILURE);
+			}
+		}
+		if (OPT_GIVEN(VERSION_STRING, lpr))
+			version_string = OPT_STRING_VAL(VERSION_STRING, lpr);
+		else
+			version_string = suite.version_string?
+				suite.version_string : "";
+		fprintf(out, ".TH %s \"%s\" \"%s\" \"%s\" \"%s\"\n",
+			suite.title? suite.title : suite.commands[0].name.orig,
+			suite.mansect? suite.mansect : "1",
+			suite.date? suite.date : date,
+			version_string,
+			suite.manual_title? suite.manual_title : "User commands"
+		);
+	}
+	for (i = 0; i <= suite.num_subcommands; i++) {
+		struct lsg_command *cmd = suite.commands + i;
+		int opt_num;
+		if (!cmd->name.orig)
+			continue;
+		if (i == 0) {
+			fprintf(out, ".SH NAME\n");
+			fprintf(out, ".B\n%s \\- ", cmd->name.orig);
+			format_man_text(out, false, cmd->purpose);
+		} else {
+			if (i == 1 && suite.caption) {
+				char *caption = strdup(suite.caption);
+				inplace_toupper(caption);
+				fprintf(out, ".SH %s\n.P\n", caption);
+				free(caption);
+			}
+			if (i == 1 && suite.introduction)
+				format_man_text(out, true, suite.introduction);
+			fprintf(out, ".SS \n%s \\- ", cmd->name.orig);
+			format_man_text(out, false, cmd->purpose);
+		}
+		fprintf(out, "\n.P\n");
+		if (i == 0)
+			fprintf(out, ".SH SYNOPSIS\n");
+		else
+			fprintf(out, "Usage: \n");
+		fprintf(out, ".B %s\n", cmd->name.orig);
+		format_synopsis(cmd, out, true);
+		fprintf(out, "\n.P\n");
+		if (cmd->description) {
+			if (i == 0)
+				fprintf(out, ".SH DESCRIPTION\n");
+			format_man_text(out, true, cmd->description);
+		}
+		if (cmd->num_options > 0)
+			if (i == 0)
+				fprintf(out, ".SH OPTIONS\n");
+		for (opt_num = 0; opt_num < cmd->num_options; opt_num++) {
+			struct lsg_option *opt = cmd->options + opt_num;
+
+			if (opt->ignored) {
+				fprintf(out, ".SS ");
+				format_man_text(out, false, opt->summary);
+				fprintf(out, "\n");
+				if (opt->help)
+					format_man_text(out, true, opt->help);
+				continue;
+
+			}
+			fprintf(out, ".TP\n");
+			if (opt->short_opt != '\0')
+				fprintf(out, "\\fB\\-%c\\fR, ", opt->short_opt);
+			fprintf(out, "\\fB\\-\\-%s\\fR", opt->name.orig);
+			format_option_arg(opt, out, true /* man_format */);
+			fprintf(out, "\n");
+			format_man_text(out, true, opt->summary);
+			fprintf(out, "\n");
+			if (opt->values) {
+				unsigned n, dflt;
+				fprintf(out, ".IP\n");
+				fprintf(out, "values:\n");
+				dflt = opt->default_val?
+					atoi(opt->default_val) : 0;
+				for (n = 0; n < opt->num_values; n++) {
+					if (n == dflt)
+						fprintf(out, ".B ");
+					fprintf(out, "%s%s\n", opt->values[n],
+						n == opt->num_values - 1?
+							"" : ",");
+				}
+			} else if (opt->default_val) {
+				fprintf(out, ".IP\n");
+				fprintf(out, "default: ");
+				format_man_text(out, false, opt->default_val);
+				fprintf(out, "\n.P\n");
+			}
+			if (opt->help) {
+				fprintf(out, ".IP\n");
+				format_man_text(out, true, opt->help);
+			}
+		}
+		fprintf(out, ".PP\n");
+		if (cmd->aux_info) {
+			char *pfx = suite.aux_info_prefix;
+			fprintf(out, ".RS\n");
+			if (pfx)
+				fprintf(out, "%s ", pfx);
+			fprintf(out, "%s\n.PP\n", cmd->aux_info);
+			fprintf(out, ".RE\n");
+		}
+		if (cmd->closing)
+			format_man_text(out, true, cmd->closing);
+	}
+	if (suite.conclusion)
+		format_man_text(out, true, suite.conclusion);
+	for (i = 0; i < suite.num_sections; i++) {
+		struct lsg_section *sec = suite.sections + i;
+		fprintf(out, "\n.P\n.SH \"%s\"\n", sec->name.capitalized);
+		fprintf(out, "%s\n.P\n", sec->text);
+	}
+	fclose(out);
+}
+
+int main(int argc, char **argv)
+{
+	const struct lls_command *cmd = lls_cmd(0, lopsubgen_suite);
+	char *errctx, *outpath, *cmdline;
+	struct lls_parse_result *lpr;
+	int i, ret;
+
+	/* Make a copy of the command line because lls_parse() permutes argv[] */
+	for (i = 0, ret = 0; argv[i]; i++)
+		ret += strlen(argv[i]) + 1;
+	cmdline = malloc(ret + 1);
+	assert(cmdline);
+	for (i = 0, ret = 0; argv[i]; i++)
+		ret += sprintf(cmdline + ret, "%s ", argv[i]);
+	cmdline[ret - 1] = '\0';
+
+	ret = lls_parse(argc, argv, cmd, &lpr, &errctx);
+	if (ret < 0) {
+		if (errctx)
+			fprintf(stderr, "%s\n", errctx);
+		fprintf(stderr, "%s\n", lls_strerror(-ret));
+		return EXIT_FAILURE;
+	}
+	if (OPT_GIVEN(VERSION, lpr)) {
+		printf("lopsubgen-%s\n", lls_version());
+		return EXIT_SUCCESS;
+	}
+	if (OPT_GIVEN(HELP, lpr)) {
+		char *help;
+		if (OPT_GIVEN(HELP, lpr) > 1)
+			help = lls_long_help(cmd);
+		else
+			help = lls_short_help(cmd);
+		printf("%s", help);
+		free(help);
+		return EXIT_SUCCESS;
+	}
+	run_yylex();
+	if (OPT_GIVEN(GEN_C, lpr)) {
+		outpath = get_output_path("c",
+			OPT_STRING_VAL(GEN_C, lpr), lpr);
+		gen_c(outpath, cmdline);
+		free(outpath);
+	}
+	if (OPT_GIVEN(GEN_HEADER, lpr)) {
+		outpath = get_output_path("h",
+			OPT_STRING_VAL(GEN_HEADER, lpr), lpr);
+		gen_header(outpath, cmdline);
+		free(outpath);
+	}
+	if (OPT_GIVEN(GEN_MAN, lpr))
+		gen_man(lpr, cmdline);
+	return EXIT_SUCCESS;
+}
+#endif /* STAGE1 */
diff --git a/lsg.h b/lsg.h
new file mode 100644
index 0000000..277648b
--- /dev/null
+++ b/lsg.h
@@ -0,0 +1,70 @@
+/*
+ * Copyright (C) 2016 Andre Noll <maan@tuebingen.mpg.de>
+ *
+ * Licensed under the GPL v3, see http://www.gnu.org/licenses/gpl-3.0.html
+ */
+
+struct lsg_name {
+	char *orig;
+	char *sanitized;
+	char *capitalized;
+};
+
+struct lsg_option {
+	struct lsg_name name;
+	char short_opt;
+	char *summary;
+	char *arg_info;
+	char *arg_type;
+	char *typestr;
+	bool multiple, required, ignored;
+	char *default_val;
+	char *help;
+	int num_values;
+	char **values;
+	char **value_literals;
+	char **value_ids;
+};
+
+struct lsg_command {
+	struct lsg_name name;
+	char *purpose;
+	char *description;
+	char *closing;
+	char *non_opts_name;
+	char *synopsis;
+	char *aux_info;
+	struct lsg_option *options;
+	int num_options;
+};
+
+struct lsg_section {
+	struct lsg_name name;
+	char *text;
+};
+
+struct lsg_suite {
+	struct lsg_name name;
+	char *caption; /* additional section heading (.SH), default: empty */
+	char *title; /* defaults to suite name */
+	char *mansect; /* default: 1 */
+	char *date; /* default: current date */
+	char *version_string; /* default: empty */
+	char *manual_title; /* default: User commands */
+	char *aux_info_prefix;
+	char *aux_info_default;
+	char *introduction, *conclusion;
+	/* supercommand is #0, subcommands start at index 1 */
+	struct lsg_command *commands;
+	int num_subcommands;
+	struct lsg_section *sections;
+	int num_sections;
+};
+
+extern struct lsg_suite suite;
+
+#ifndef STAGE1
+#define OPT_RESULT(_name, _lpr) ((_lpr)->opt_result + LSG_LOPSUBGEN_LOPSUBGEN_OPT_ ## _name)
+#define OPT_GIVEN(_name, _lpr) (OPT_RESULT(_name, (_lpr))->given)
+#define OPT_STRING_VAL(_name, _lpr) (OPT_RESULT(_name, (_lpr))->value[0].string_val)
+#endif /* STAGE1 */
diff --git a/version-gen.sh b/version-gen.sh
new file mode 100755
index 0000000..ed3a22e
--- /dev/null
+++ b/version-gen.sh
@@ -0,0 +1,25 @@
+#!/bin/sh
+
+version_file='version.c'
+ver='unnamed_version'
+# First try git, then gitweb, then default.
+if [ -e '.git' -o -e '../.git' ]; then
+	git_ver=$(git describe --abbrev=4 HEAD 2>/dev/null)
+	[ -z "$git_ver" ] && git_ver="$ver"
+	# update stat information in index to match working tree
+	git update-index -q --refresh
+	# if there are differences (exit code 1), the working tree is dirty
+	git diff-index --quiet HEAD || git_ver=$git_ver-dirty
+	ver=$git_ver
+elif [ "${PWD%%-*}" = 'lopsub-' ]; then
+	ver=${PWD##*/lopsub-}
+fi
+ver=${ver#v}
+
+echo "$ver"
+
+# update version file if necessary
+content="const char *lls_version(void) {return \"$ver\";};"
+[ -r "$version_file" ] && echo "$content" | cmp -s - $version_file && exit 0
+echo >&2 "new git version: $ver"
+echo "$content" > $version_file
diff --git a/web/footer.html b/web/footer.html
new file mode 100644
index 0000000..308b1d0
--- /dev/null
+++ b/web/footer.html
@@ -0,0 +1,2 @@
+</body>
+</html>
diff --git a/web/header.html b/web/header.html
new file mode 100644
index 0000000..3cf72cc
--- /dev/null
+++ b/web/header.html
@@ -0,0 +1,46 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+   "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+	<meta http-equiv='Content-Type' content='text/html; charset=utf-8'>
+	<title>Lopsub</title>
+</head>
+
+<body>
+
+	<table width=100%>
+		<tr>
+			<td>
+				<h2>The long option parser for subcommands</h2>
+
+			</td>
+			<td align="right">
+				<a href="./index.html">
+					<img
+						src="lopsub.png"
+						alt="lopsub logo"
+					>
+				</a>
+			</td>
+		</tr>
+	</table>
+
+	<hr>
+
+	<table width=100%>
+		<tr>
+			<td align="center">
+				<a href="./index.html">About</a>
+			</td>
+			<td align="center">
+				<a href="./lopsub-suite.5.html">lopsub-suite(5)</a>
+			</td>
+			<td align="center">
+				<a href="./lopsubgen.1.html">lopsubgen(1)</a>
+			</td>
+			<td align="center">
+				<a href="./lopsub-api.html">API</a>
+			</td>
+	</table>
+
+	<hr>
diff --git a/web/lopsub.png b/web/lopsub.png
new file mode 100644
index 0000000000000000000000000000000000000000..23dfb642fb8d9e8a3bc4b688e55f93fa03c77be7
GIT binary patch
literal 11493
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

literal 0
HcmV?d00001

-- 
2.30.2