From 068d67978e49300c66d6e29514475d6731e1259c Mon Sep 17 00:00:00 2001 From: "Michael D. Lowis" Date: Tue, 17 Mar 2015 20:55:31 -0400 Subject: [PATCH] Added doxygen file header with description of the library design and behavior --- source/opts.h | 43 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/source/opts.h b/source/opts.h index 7519481..18a0e54 100755 --- a/source/opts.h +++ b/source/opts.h @@ -1,3 +1,44 @@ +/** + * @file + * @author Mike D. Lowis + * + * This project is an implementation of a very lightweight command-line options + * parser. It is capable of interpreting the Unix/GNU style command line + * argument flags. It is designed to be platform independent and can be used as + * a static library or directly as source. + * + * The library is designed to work like something of a database for your + * command line. At initialization time you feed in the arguments vector (your + * data records) and a list of option definitions (your schema). The library + * then parses the options and stores them internally for querying later. + * Several querying functions are provided that cover the most common use cases + * for options handling. + * + * All of the query functions take an option name and an option tag as + * parameters. These two arguments will be used to search the list of parsed + * options for any that match both parameters. In some cases only one of the + * parameters is needed for a query. To facilitate this, the query functions + * will interpret a NULL pointer to match everything. An example of this would + * be selecting all parsed options with the tag "foo": + * + * const char** foo_lst = opts_select(NULL,"foo"); + * + * In the example above, the NULL would match *all* parsed options and from that + * group only those having the tag "foo" would be returned. Another common + * scenario would be searching by parameter name: + * + * const char** includes = opts_select("I", NULL); + * + * In this scenario all of the options that were parsed having the name 'I' + * would be returned regardless of their tag value. This would equate to all of + * the instances of '-I' that would occur on the command line for an invocation + * of gcc. + * + * With this design you should be able to let the library handle your options + * parsing while you focus on your application logic using appropriate queries + * to change behavior where necessary. + * + */ #ifndef OPTS_H #define OPTS_H @@ -11,7 +52,7 @@ extern "C" { /** Structure representing an option to be parsed */ typedef struct { - /** The name of the option as it will appear on the commandline */ + /** The name of the option as it will appear on the command line */ char* name; /** Flag indicating whether the option expects an argument or not */ bool has_arg; -- 2.54.0