initial commit

2 files changed, 306 insertions, 0 deletions

diff --git a/doc/example.c b/doc/example.c
new file mode 100644
index 0000000..878dbb6
--- /dev/null
+++ b/doc/example.c
@@ -0,0 +1,120 @@
+#include "../src/simple-opt.h"
+
+int main(int argc, char **argv)
+{
+	/* array containing all options and their types / attributes */
+	struct simple_opt options[] = {
+		{ SIMPLE_OPT_FLAG, 'h', "help", false,
+			"print this help message and exit" },
+		{ SIMPLE_OPT_INT, '\0', "int", true,
+			"this thing needs an integer!" },
+		{ SIMPLE_OPT_UNSIGNED, 'u', "uns", true,
+			"this one has a custom_arg_string. normally it would say" 
+				" \"UNSIGNED\" rather than \"NON-NEG-INT\"",
+			"NON-NEG-INT" },
+		{ SIMPLE_OPT_STRING, 's', NULL, true,
+			"this one doesn't have a long opt version" },
+		{ SIMPLE_OPT_BOOL, 'b', "bool", false,
+			"(optionally) takes a boolean arg!" },
+		{ SIMPLE_OPT_END },
+	};
+
+	/* contains an enum for identifying simple_opt_parse's return value as well
+	 * as the argv index of the first non-option and information relevant for
+	 * error handling */
+	struct simple_opt_result result;
+
+	int i;
+
+	result = simple_opt_parse(argc, argv, options);
+
+	/* handle errors */
+	switch (result.result_type) {
+	case SIMPLE_OPT_RESULT_UNRECOGNISED_OPTION:
+		fprintf(stderr, "err: unrecognised option `%s`\n",
+				result.option_string);
+		return 1;
+
+	case SIMPLE_OPT_RESULT_BAD_ARG:
+		fprintf(stderr, "err: bad argument `%s` passed to option `%s`\n",
+				result.argument_string, result.option_string);
+		return 1;
+
+	case SIMPLE_OPT_RESULT_MISSING_ARG:
+		fprintf(stderr, "err: argument expected for option `%s`\n",
+				result.option_string);
+		return 1;
+
+	case SIMPLE_OPT_RESULT_OPT_ARG_TOO_LONG:
+		fprintf(stderr, "internal err: argument passed to option `%s` is too long\n",
+				result.option_string);
+		return 1;
+
+	case SIMPLE_OPT_RESULT_TOO_MANY_ARGS:
+		fprintf(stderr, "internal err: too many cli arguments passed\n");
+		return 1;
+
+	case SIMPLE_OPT_RESULT_MALFORMED_OPTION_STRUCT:
+		fprintf(stderr, "internal err: malformed option struct\n");
+		return 1;
+
+	default:
+		break;
+	}
+
+	/* if the help flag was passed, print usage */
+	if (options[0].was_seen) {
+		simple_opt_print_usage(stdout, 80, argv[0],
+				"[OPTION]... [--] [NON-OPTION]...",
+				"This is where you would put an overview description of the "
+				"program and it's general functionality.", options);
+		return 0;
+	}
+
+	/* print a summary of options passed */
+	for (i = 0; options[i].type != SIMPLE_OPT_END; i++) {
+		if (options[i].long_name != NULL)
+			printf("--%s, ", options[i].long_name);
+		else
+			printf("-%c, ", options[i].short_name);
+
+		printf("seen: %s", (options[i].was_seen ? "yes" : "no"));
+
+		if (options[i].arg_is_stored) {
+			switch (options[i].type) {
+			case SIMPLE_OPT_INT:
+				printf(", val: %d", options[i].val_int);
+				break;
+
+			case SIMPLE_OPT_UNSIGNED:
+				printf(", val: %u", options[i].val_unsigned);
+				break;
+
+			case SIMPLE_OPT_STRING:
+				printf(", val: %s", options[i].val_string);
+				break;
+
+			case SIMPLE_OPT_BOOL:
+				printf(", val: %s", options[i].val_bool ? "true" : "false");
+				break;
+				
+			default:
+				break;
+			}
+		}
+
+		puts("");
+	}
+
+	/* if any non-option arguments were passed, print them */
+	if (result.argc > 0) {
+		printf("\nnon-options:", result.argc);
+
+		for (i = 0; i < result.argc; i++)
+			printf(" %s", result.argv[i]);
+
+		puts("");
+	}
+
+	return 0;
+}
diff --git a/doc/interface.md b/doc/interface.md
new file mode 100644
index 0000000..53838c2
--- /dev/null
+++ b/doc/interface.md
@@ -0,0 +1,186 @@
+simple-opt
+==========
+
+data types
+----------
+
+### struct simple_opt
+
+an array of `struct simple_opt`, terminating in an element with a `type` field
+equal to `SIMPLE_OPT_END`, must be passed when parsing or usage printing. the
+fields which should be defined in these elements are:
+
+```
+	enum simple_opt_type type;
+	const char short_name;
+	const char *long_name;
+	bool arg_is_required;
+
+	/* optional, used for usage printing */
+	const char *description;
+
+	/* optional, a custom string describing the arg, used for usage printing */
+	const char *custom_arg_string;
+```
+
+if `type` is `SIMPLE_OPT_FLAG`, this option may not accept arguments. if `type`
+is `SIMPLE_OPT_END`, parsing and usage printing will return at this point when
+iterating through the array and will not see any elements which may follow.
+
+`short_name` is optional, and may be undefined for this option by passing '\0'.
+`long_name` is also optional, and may be left undefined for this option by
+passing `NULL`. however, at fewest one of these two must be defined for every
+option.
+
+the fields which are set by `simple_opt_parse` are:
+
+```
+	bool was_seen;
+	bool arg_is_stored;
+
+	union {
+		bool val_bool;
+		int val_int;
+		unsigned val_unsigned;
+		char val_string[SIMPLE_OPT_ARG_MAX_WIDTH];
+	};
+```
+
+`was_seen` indicates if this option was encountered during parsing,
+`arg_is_stored` if an argument was passed to the option, and the `val_<type>`
+fields contain the value passed (with the correct field to set being determined
+by the `type` field shown above).
+
+
+### struct simple_opt_result
+
+```
+struct simple_opt_result {
+	enum simple_opt_result_type result_type;
+	enum simple_opt_type option_type;
+	char option_string[SIMPLE_OPT_OPT_MAX_WIDTH];
+	char argument_string[SIMPLE_OPT_OPT_ARG_MAX_WIDTH];
+	int argc;
+	char *argv[SIMPLE_OPT_MAX_ARGC];
+};
+```
+
+`simple_opt_parse` returns a `struct simple_opt_result`. upon successful
+parsing, its `result_type` field will contain `SIMPLE_OPT_RESULT_SUCCESS`.
+otherwise, it will contain an error which should be handled by the caller. the
+first three are user-caused errors:
+
+```
+	SIMPLE_OPT_RESULT_UNRECOGNISED_OPTION,
+	SIMPLE_OPT_RESULT_BAD_ARG,
+	SIMPLE_OPT_RESULT_MISSING_ARG,
+```
+
+in the case of `SIMPLE_OPT_RESULT_UNRECOGNISED_OPTION`, `option_string` will
+contain the unrecognised option which was passed.
+
+if the type is `SIMPLE_OPT_BAD_ARG`, then `option_string` will be set,
+`option_type` will be set to the type of that option (`SIMPLE_OPT_BOOL` etc),
+and the bad argument will be stored in `argument_string`.
+
+if the type is `SIMPLE_OPT_MISSING_ARG`, `option_string` and `option_type` will
+be set.
+
+the remaining result types are internal errors:
+
+```
+	SIMPLE_OPT_RESULT_ARG_TOO_LONG,
+	SIMPLE_OPT_RESULT_TOO_MANY_ARGS,
+	SIMPLE_OPT_RESULT_MALFORMED_OPTION_STRUCT,
+```
+
+`SIMPLE_OPT_RESULT_OPT_ARG_TOO_LONG` will be returned if an option argument,
+passed on the command line by a user, was too long for the internal buffer. the
+internal buffer can be resized by defining `SIMPLE_OPT_OPT_MAX_WIDTH` at some
+point before `simple-opt.h` is included.
+
+`SIMPLE_OPT_RESULT_TOO_MANY_ARGS` is returned if the user passed too many
+non-option arguments to the command for its internal argv filter buffer. this
+limit can also be resized by defining `SIMPLE_OPT_MAX_ARGC`
+
+finally, `SIMPLE_OPT_RESULT_MALFORMED_OPTION_STRUCT` is returned if the
+programmer has passed a `struct simple_opt` array which contains disallowed
+option configurations (that is, two options share a `short_name` or
+`long_name`, an option has neither a `short_name` nor a `long_name`, or an
+option of type `SIMPLE_OPT_FLAG` is marked as requiring an argument)
+
+
+functions
+---------
+
+`simple-opt.h` defines two functions for external use, `simple_opt_parse` and
+`simple_opt_print_usage`. any other functions are prefixed `sub_simple_opt` and
+should not be called directly (their visibility is a by-product of simple-opt's
+single header file nature)
+
+
+### simple_opt_parse
+
+`simple_opt_parse` takes three arguments and returns a `struct
+simple_opt_result`:
+
+```
+struct simple_opt_result simple_opt_parse(int argc, char **argv, struct
+		simple_opt *options);
+```
+
+`argc` is the number of arguments contained in `argv`, and `argv` is an array
+of character string pointers. normally here the programmer would just pass on
+the `argc` and `argv` received as arguments from the `main` function.
+
+`struct simple_opt` is an array of the options available to be parsed
+(described above) and `struct simple_opt_result` contains a set of results
+about that parsing (also described above).
+
+
+### simple_opt_print_usage
+
+`simple_opt_print_usage` takes six arguments and prints a neatly-formatted
+usage message, similar to those typical of GNU cli commands:
+
+```
+void simple_opt_print_usage(FILE *f, unsigned width, char *usage_name,
+		char *usage_options, char *usage_summary, struct simple_opt *options)
+```
+
+`f` is a file pointer to which the message should be printed
+
+`width` is the column width to which the output should be word-wrapped (passing
+0 disables wrapping). a reasonable value here would be 80, but this could also
+be used to allow more dynamic behaviour (e.g. using something like `ncurses` or
+`ioctl` to get the users's current terminal width)
+
+`usage_name` is the name of the command as it will be printed in the usage
+statement. easiest is just to pass `argv[0]` here.
+
+`usage_options` is a summary of what options the command takes (e.g. something
+like `[OPTION]...`)
+
+together, these two result in something that looks like:
+
+```
+Usage: ./a.out [OPTION]...
+```
+
+if both `usage_name` and `usage_options` are `NULL`, this initial line will not
+be printed, allowing more flexibility to the programmer (if you wanted to, for
+example, print multiple such lines on your own in order to represent different
+use-cases)
+
+`usage_summary` is usually a one or two sentence overview summary of how the
+command behaves. if this is left as `NULL`, no summary will be printed.
+
+the final argument, `struct simple_opt *options`, is an array of options as
+defined above.
+
+*note:* usage printing's word wrap operates on the assumptions that your
+language used delimits words with spaces (i.e. "when i was a child..." vs.
+"子供時代に..."), that the font used is fixed-width, and that every character
+occupies one column (that is, there are no ｗｉｄｅ characters, combining
+diacritics, etc). if these assumptions do not apply to your use case, you
+should use an alternative method for usage printing.