Document most of libsimple-arg.h

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 325 insertions, 0 deletions

diff --git a/man0/libsimple-arg.h.0 b/man0/libsimple-arg.h.0
new file mode 100644
index 0000000..d6cfd2e
--- /dev/null
+++ b/man0/libsimple-arg.h.0
@@ -0,0 +1,325 @@
+.TH LIBSIMPLE-ARG.H 0 2018-11-08 libsimple
+.SH NAME
+libsimple-arg.h \- command line argument parsing header for libsimple
+.SH SYNOPSIS
+.nf
+#include <libsimple-arg.h>
+
+extern char *\fIargv0\fP;
+
+struct longopt {
+	const char *long_flag;
+	char short_flag;
+	int with_arg;
+};
+
+#define ARGBEGIN                          ARGBEGIN3(1, argc, argv)
+#define SUBARGBEGIN                       ARGBEGIN3(0, argc, argv)
+#define ARGBEGIN3(\fIWITH_ARGV0\fP, \fIargc\fP, \fIargv\fP) /* implementation omitted */
+#define ARGMAPLONG(\fILONGOPTS\fP)              /* implementation omitted */
+#define ARGALT(\fISYMBOL\fP)                    /* implementation omitted */
+#define ARGEND                            /* implementation omitted */
+#define ARGNUM                            /* implementation omitted */
+#define FLAG()                            /* implementation omitted */
+#define LFLAG()                           /* implementation omitted */
+#define ARG()                             /* implementation omitted */
+#define ARGHERE()                         /* implementation omitted */
+#define NOFLAGS(...)                      /* implementation omitted */
+#define TESTLONG(\fIFLG\fP, \fIWARG\fP)               /* implementation omitted */
+#define USAGE(\fISYNOPSIS\fP)                   /* implementation omitted */
+#define NUSAGE(\fISTATUS\fP, \fISYNOPSIS\fP)          /* implementation omitted */
+.fi
+.SH DESCRIPTION
+The
+.I <libsimple-arg.h>
+header define a collection of macros for parsing the
+command line arguments, thatis, the data in the
+two first parameters of the
+.IR main ()
+function, according to the default behaviour specified
+by POSIX (extensions of the specification is available).
+It also includes the three headers the macros need:
+.IR <stdio.h> ,
+.IR <stdlib.h> ,
+and
+.IR <string.h> ,
+additionally in defines the variable
+.I argv0
+which the macros set to the command line argument with
+index zero which is the process was invoked with, normally,
+but not always, this the filename of or the path to the
+binary the process runs; one common exception to this is
+for login shells: when a user logs in, the shell that is
+started is started with the filename of the shell's binary
+prefix with a dash
+.RB ( - )
+as the zeroth command line argument. Assuming the second
+argument in the
+.IR main ()
+function is named
+.IR argv ,
+the program should set
+.I argv0
+to
+.I argv[0]
+if the process may call a either of the
+.BR libsimple_eprintf (3),
+.BR libsimple_enprintf (3),
+.BR libsimple_weprintf (3),
+.BR libsimple_veprintf (3),
+.BR libsimple_venprintf (3),
+and
+.BR libsimple_vweprintf (3)
+functions before the either of the
+.B ARGBEGIN
+macro is used, and must do so if the function
+.BR usage (),
+defined by the
+.B USAGE
+and
+.B NUSAGE
+macros, is called before the
+.B ARGBEGIN
+macro is used.
+.PP
+Applications should normally parse or validate the command
+line arguments and print usage information on usage error.
+The macros
+.BI USAGE( SYNOPSIS )
+and
+.BI NUSAGE( STATUS ,\  SYNOPSIS )
+define a
+.RI ( static )
+function, name
+.IR usage (),
+that print the usage information and terminate the process,
+the also declare the variable
+.IR argv0 .
+.IR usage ()
+does take any arguments.
+.IR usage ()
+defined by
+.B USAGE
+terminate the process with exit value 1.
+.IR usage ()
+defined by
+.B NUSAGE
+terminate the process with exit value
+.IR STATUS.
+Both print the an error message to the standard error
+in the following format:
+.nf
+
+	\fB\(dqusage: %s %s\en\(dq,\fP \fIargv0\fP\fB, \fP\fISYNOPSIS\fP
+
+.fi
+However, if
+.I SYNOPSIS
+is
+.B NULL
+or the empty string, the error message printed in the
+following format.
+.nf
+
+	\fB\(dqusage: %s\en\(dq,\fP \fIargv0\fP
+.fi
+.PP
+The macros
+.B ARGBEGIN
+and
+.B ARGEND
+are used to parse command line arguments, they use the variable
+named
+.I argc
+(number of command line arguments)
+and
+.I argv
+(command line arguments) and set
+.I argv0
+to
+.IR argv[0] ,
+.I argv[argc]
+must be
+.BR NULL ,
+which is the case for the
+.IR main ()
+function. The
+value that should be stored to
+.I argv0
+is not available at
+.IR argv[0] ,
+the macro
+.B SUBARGBEGIN
+should be used instead of
+.BR ARGBEGIN .
+These macros work similar to a switch statement in a loop:
+.nf
+
+	ARGBEGIN {
+	case 'a':
+		/* handle -a */
+		break;
+	case 'b':
+		/* handle -b */
+		break;
+	case ARGNUM:
+		/* handle -0, -1, -2, ..., -9 */
+		break;
+	default:
+		/* print usage information for other flags */
+		usage();
+	} ARGEND;
+
+.fi
+After
+.BR ARGEND ,
+.I argc
+and
+.I argv
+are set to only contain the remaining, unparsed, arguments.
+.PP
+The
+.BR ARGBEGIN3 ()
+macro can be used instead of the
+.B ARGBEGIN
+and
+.B SUBARGBEGIN
+macros for greater flexibility. If
+.I WITH_ARGV0
+is non-zero it behaves like the
+.B ARGBEGIN
+macro, otherwise it behaves like the
+.B SUBARGBEGIN
+macro. The
+.BR ARGBEGIN3 ()
+also lets the user choose which variables to use as
+.I argc
+and
+.IR argv .
+.PP
+If the application should support flags starting with
+another symbol than a dash
+.RB ( - ),
+the macro
+.BR ARGALT ()
+can be used. Its argument, 
+.IR SYMBOL ,
+should be
+.B char
+and it is used thusly:
+.nf
+
+	ARGBEGIN {
+	case 'a':
+		/* handle -a */
+		break;
+	default:
+		usage();
+	} ARGALT('+') {
+	case 'a':
+		/* handle +a */
+		break;
+	default:
+		usage();
+	} ARGALT('/') {
+	case 'a':
+		/* handle /a */
+		break;
+	default:
+		usage();
+	} ARGEND;
+.fi
+.PP
+In multicase statement (any case statement actually), the
+.BR FLAG ()
+macro can be used to identify which flag is being parsed.
+For example, in
+.I case 'a'
+.BR FLAG ()
+returns
+.IR 'a' .
+The
+.BR LFLAG ()
+macro returns the entire element in
+.IR argv .
+Note that one such element can contain multiple flags,
+and the it can contain the flags argument, but the
+argument can also be in the next element.
+.PP
+The macros
+.BR ARG (),
+.BR ARGNULL (),
+and
+.BR ARGHERE ()
+are used the get the value provided with an option, one
+of the must be used to let the parse know that the option
+should have a value.
+.BR ARG ()
+returns the current option's value, or terminates the
+by calling
+.IR usage ()
+if the option does not have a value.
+.BR ARGNULL ()
+returns the current option's value, or returns
+.B NULL
+if the option does not have a value.
+.BR ARGHERE ()
+Remaining part of the current argument in the command
+line, including the character the specifies the flag.
+It can be used together with
+.B ARGNUM
+to parse numerical options (a dash followed by a
+multidigit number). It can also be used to parse
+options where the value is optional be must appear
+in the same argument, for example, if the current
+argument is
+.BR -n1000 ,
+.BR ARGHERE ()
+will return
+.B \(dqn1000\(dq
+when the
+.B -n
+option is parsed, but if the argument is just
+.BR -n ,
+.BR ARGHERE ()
+will return
+.BR \(dqn\(dq ,
+even if the next argument is
+.BR 1000 .
+.PP
+If your application, does not recognise any options,
+but should still have like normal programs and support
+.BR -- ,
+the macro
+.BR NOFLAGS ()
+can be used instead of the
+.B ARGBEGIN
+and
+.B ARGEND
+macros. It behaves just like
+.nf
+
+	ARGBEGIN {
+	default:
+		usage();
+	} ARGEND;
+
+.fi
+but is optimised. Additionally, if the last argument
+is non-zero, the
+.IR usage ()
+function is called. All arguments evaluated exactly
+once, or if flags are used, never. So if your application
+should not have any options or operands,
+.I NOFLAGS(argc)
+can be used.
+.SH APPLICATION USAGE
+None.
+.SH RATIONALE
+None.
+.SH FUTURE DIRECTIONS
+None.
+.SH NOTES
+None.
+.SH SEE ALSO
+.BR libsimple.h (0)