Convenient Command line options parser. More...

Collaboration diagram for Command line options parser:

Modules
	Argument parsers for clopts

Classes
struct	csnip_clopts_optinfo_s
	Descriptor for a single command line option. More...

struct	csnip_clopts_s
	Set of descriptors for all command line options. More...

Macros
#define	csnip_clopts_Addvar(opts, short_name, long_name, description, ptr_target, err)
	Add an option, generic variant. More...

#define	csnip_clopts_Addflag(opts, short_name, long_name, description, ptr_target, err)
	Add a flag, generic variant. More...

Typedefs
typedef struct csnip_clopts_optinfo_s	csnip_clopts_optinfo
	Short typedef for struct csnip_clopts_optinfo_s.

typedef struct csnip_clopts_s	csnip_clopts
	Short typedef for struct csnip_clopts_s.

typedef int(*	csnip_clopts_parser) (const csnip_clopts opts, const csnip_clopts_optinfo optinfo, const char *argval)
	Argument parser function pointer type. More...

Functions
int	csnip_clopts_add_defaults (csnip_clopts *opts)
	Add handlers for default options. More...

int	csnip_clopts_add (csnip_clopts opts, int n_optinfo, const csnip_clopts_optinfo optinfo)
	Add processable options. More...

int	csnip_clopts_process (csnip_clopts opts, int argc, char argv, int ret_pos_args, bool do_clear)
	Process command line arguments. More...

void	csnip_clopts_clear (csnip_clopts *opts)
	Clear clopts assignments, freeing memory. More...

Detailed Description

This parser automates many of the tedious and repetitive tasks that arise when using getopts and libraries based on similar APIs:

It supports assigning to variables. Values are converted to the appropriate form (e.g. argument values mapped to integers are parsed as integers by the library).
It supports documentation of the command line flags and has a premade implementation of the –help flag.
Errors are automatically handled.

Generally, clopts-based parsers are much simpler and shorter to write than getopt() based ones. An example program using the main features of clopts is examples/clopts.c.

An example on how to perform command line option parsing with the clopts library is as follows:

#include <stdio.h>
 
#define CSNIP_SHORT_NAMES
#include <csnip/err.h>
#include <csnip/clopts.h>
 
int main(int argc, char** argv)
{
    clopts opts = {
      .description = "Testing tool for clopts library."
    };
    clopts_add_defaults(&opts);
 
    /* Do the command line parsing */
    int i = 0;
    long l = 1;
    unsigned long ul = 2;
    const char* str = "unset";
    _Bool flag = 0;
    clopts_Addvar(&opts, 'i', "int", "int argument", &i, _);
    clopts_Addvar(&opts, 'l', "long", "long int argument", &l, _);
    clopts_Addvar(&opts, 'u', "ulong", "unsigned long argument", &ul, _);
    clopts_Addvar(&opts, 's', "string", "string argument", &str, _);
    clopts_Addflag(&opts, 'f', "flag", "flag", &flag, _);
    int err = clopts_process(&opts, argc - 1, argv + 1, NULL, true);
    if (err != 0) {
        char buf[128];
        err_str(err, buf, sizeof(buf));
        printf("Error from clopts_process: %s\n", buf);
        return 1;
    }
 
    /* Display result */
    printf("Done with argument processing.\n");
    printf("Got i = %d, l = %ld, ul = %lu, str = \"%s\", flag = %s\n",
      i, l, ul, str, (flag ? "true" : "false"));
 
    return 0;
}

This example can be found in examples/clopts.c. For contrast, that same directory also contains examples/getopt.c which implements a similar program using the familiar getopt interface that POSIX provides. Users familiar with getopt() should be able to get the hang of clopts fairly easily by studying these examples. Note that the getopt.c example, despite missing quite a few things such as input validation on the numbers provided, or long options, is far longer than the clopts example.

Macro Definition Documentation

◆ csnip_clopts_Addflag

#define csnip_clopts_Addflag	(	opts,
		short_name,
		long_name,
		description,
		ptr_target,
		err
	)

Value:

    csnip_clopts__Addflag((opts), (short_name), (long_name), \
                    (description), (ptr_target), (err), \
            csnip__O, csnip__errval)

This macro adds a flag (i.e., an option without value) to the array of options, deducing the parser to use from the type of the variable to be assigned.

Parameters

[in,out]	opts	the csnip_clopts to add the option to
[in]	short_name	Short-form name of the flag. This is a char.
[in]	long_name	Long-form name of the flag. This is a C string. The passed string is not copied and must therefore exist for the lifetime of the call. Use NULL if no long name should be set.
[in]	description	Description of the option. This is shown to the user when –help is used, for example.
[in]	ptr_target	The address of the target value. This is where the parser option value will be placed.
[in,out]	err	l-value for error return.

◆ csnip_clopts_Addvar

#define csnip_clopts_Addvar	(	opts,
		short_name,
		long_name,
		description,
		ptr_target,
		err
	)

Value:

    csnip_clopts__Addvar((opts), (short_name), (long_name), \
                    (description), (ptr_target), (err), \
            csnip__parser, csnip__O, csnip__errval)

This macro adds an option to the array of options, deducing the parser to use from the type of the variable to be assigned.

Parameters

[in,out]	opts	the csnip_clopts to add the option to
[in]	short_name	Short-form name of the option. This is a char.
[in]	long_name	Long-form name of the option. This is a C string. The passed string is not copied and must therefore exist for the lifetime of the call. Use NULL if no long name should be set.
[in]	description	Description of the option. This is shown to the user when –help is used, for example.
[in]	ptr_target	The address of the target value. This is where the parser option value will be placed.
[in,out]	err	l-value for error return.

Typedef Documentation

◆ csnip_clopts_parser

typedef int(* csnip_clopts_parser) (const csnip_clopts *opts, const csnip_clopts_optinfo *optinfo, const char *argval)

csnip_clopts_process() calls argument parsers for each argument that it encounters. Csnip's built-in argument parsers, as used in particular by csnup_clopts_Addvar() convert the arguments to the desired type and store in the supplied memory location. Custom argument parsers provide the flexibility to do other processing.

Parameters

opts	The csnip_clopts being processed
optinfo	The csnip_clopts_optinfo that matched this argument. In particular, that structure's usr pointer may be useful. The builtin parsers use this to store the target pointer, but custom parser may use it as a pointer to arbitrary information instead.
argval	The argument value string.

Returns: 0 on success, < 0 if there was a failure. In the failure case, csnip_clopts_process() will stop processing and report the error code back to the caller.

Function Documentation

◆ csnip_clopts_add()

int csnip_clopts_add	(	csnip_clopts *	opts,
		int	n_optinfo,
		const csnip_clopts_optinfo *	optinfo
	)

Adds a set of command line options to the clopts. Since the optinfos are copied, adding options causes memory to be allocated. To free that memory after use, call csnip_clopts_clear().

Parameters

opts	the clopts to add the options to.
n_optinfo	the number of arguments to add.
optinfo	the array of options to add. Must be of size at least n_optinfo.

Returns: 0 on success < 0 csnip error code.

◆ csnip_clopts_add_defaults()

int csnip_clopts_add_defaults ( csnip_clopts * opts )

This adds in particular a useful handler for the -h / –help command line flag.

◆ csnip_clopts_clear()

void csnip_clopts_clear ( csnip_clopts * opts )

Remove any added options from the clopts, freeing the memory they occupied in the process.

Parameters

opts	the clopts to add.

◆ csnip_clopts_process()

int csnip_clopts_process	(	csnip_clopts *	opts,
		int	argc,
		char **	argv,
		int *	ret_pos_args,
		bool	do_clear
	)

The command line options passed in the vector (argc, argv) are processed. The program name argument argv[0] that is typically passed to main() is assumed not to be present, therefore an offset to the main args should be applied.

This library function prints messages about any parsing errors to stderr, thus it is usually sufficient to simply terminate the program if an error number is returned.

Parameters

opts	the options to process.
argc	the size of the argv vector.
argv	the array of command line arguments; as mentioned above, unlike the argv[] seen in main() this command should remove the initial argument.
ret_pos_args	return pointer to assign the index of trailing non-option arguments to. If set to NULL, no non-option arguments are expected, and thus an error is flagged in this case when non-option arguments are found.
do_clear	flag indicating whether opts should be cleared after processing. This is a convenience flag for the most common case where csnip_clopts_process() is invoked exactly once.

See also: csnip_clopts_clear().

Returns: 0 on success < 0 csnip error code. In the typical case of an error in the format sequence, an error message will have been printed to stderr.

Modules

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ csnip_clopts_Addflag

◆ csnip_clopts_Addvar

Typedef Documentation

◆ csnip_clopts_parser

Function Documentation

◆ csnip_clopts_add()

◆ csnip_clopts_add_defaults()

◆ csnip_clopts_clear()

◆ csnip_clopts_process()