getopt

Typedefs
typedef struct M_getopt	M_getopt_t
typedef M_bool(*	M_getopt_nonopt_cb) (size_t idx, const char *option, void *thunk)
typedef M_bool(*	M_getopt_integer_cb) (char short_opt, const char *long_opt, M_int64 *integer, void *thunk)
typedef M_bool(*	M_getopt_decimal_cb) (char short_opt, const char *long_opt, M_decimal_t *decimal, void *thunk)
typedef M_bool(*	M_getopt_string_cb) (char short_opt, const char *long_opt, const char *string, void *thunk)
typedef M_bool(*	M_getopt_boolean_cb) (char short_opt, const char *long_opt, M_bool boolean, void *thunk)

Enumerations
enum	M_getopt_error_t {   M_GETOPT_ERROR_SUCCESS = 0 ,   M_GETOPT_ERROR_INVALIDOPT ,   M_GETOPT_ERROR_INVALIDDATATYPE ,   M_GETOPT_ERROR_INVALIDORDER ,   M_GETOPT_ERROR_MISSINGVALUE ,   M_GETOPT_ERROR_NONOPTION }

Functions
M_getopt_t *	M_getopt_create (M_getopt_nonopt_cb cb)
void	M_getopt_destroy (M_getopt_t *g)
char *	M_getopt_help (const M_getopt_t *g)
M_bool	M_getopt_addinteger (M_getopt_t *g, char short_opt, const char *long_opt, M_bool val_required, const char *description, M_getopt_integer_cb cb)
M_bool	M_getopt_adddecimal (M_getopt_t *g, char short_opt, const char *long_opt, M_bool val_required, const char *description, M_getopt_decimal_cb cb)
M_bool	M_getopt_addstring (M_getopt_t *g, char short_opt, const char *long_opt, M_bool val_required, const char *description, M_getopt_string_cb cb)
M_bool	M_getopt_addboolean (M_getopt_t *g, char short_opt, const char *long_opt, M_bool val_required, const char *description, M_getopt_boolean_cb cb)
M_getopt_error_t	M_getopt_parse (const M_getopt_t *g, const char *const *argv, int argc, const char **opt_fail, void *thunk)

Detailed Description

Command line argument parsing.

Handles parsing using a series of provided callbacks for each type. Auto conversion of the argument for the option type will take place. Callbacks are allowed to reject the option or argument. This will stop parsing.

If auto conversion is unwanted use the string option type. String options will alway shave their arguments passed unmodified.

Options can be marked as having required or optional arguments.

The boolean type is somewhat special. If marked as not having a required argument it is treated as a flag. For example -b would call the boolean callback with a value of M_TRUE. If a boolean is marked as val required then a value is required and the result of conversion (using M_str_istrue) will be passed to the callback.

For options that should not have an argument use the boolean type with val not required.

Option callbacks are only called when an option is specified. Meaning for boolean options a value of M_FALSE will only be sent if the option was explcitly used and set to false.

Supports auto generation of help message.

Valid characters for options (short/long) is all ASCII printable [!-~] except:

• space
• '-' (short or start/end long)
• '='
• '"'
• '''

To stop option processing and treat all following values as nonoptions use – as an option.

An optional thunk can be passed in during parsing which will be passed to all callbacks. This can be used to collect all options into an object instead of stored in global variables.

Option callbacks will receive the short and long options associated with the option. If no short option was set the short_opt callback value will be 0. If no long option was set the long_opt callback value will be NULL.

Example:

static M_bool nonopt_cb(size_t idx, const char *option, void *thunk)
{
    M_printf("option='%s'\n", option);
}
 
static M_bool int_cb(char short_opt, const char *long_opt, M_int64 *integer, void *thunk)
{
    M_printf("short_opt='%d', long_opt='%s', integer='%lld'\n", short_opt, long_opt, integer!=NULL?*integer:-1);
}
 
int main(int argc, char **argv) {
    M_getopt_t *g; 
    char       *help;
    const char *fail;
 
    g = M_getopt_create(nonopt_cb);
    M_getopt_addinteger(g, 'i', "i1", M_TRUE, "DESCR 1", int_cb);
 
    help = M_getopt_help(g);
    M_printf("help=\n%s\n", help);
    M_free(help);
 
    if (M_getopt_parse(g, argv, argc, &fail, NULL) == M_GETOPT_ERROR_SUCCESS) {
        M_printf("Options parsed successfully\n");
    } else {
        M_printf("Options parse error: %s\n", fail);
    }
 
    M_getopt_destroy(g);
    return 0;
} 

Typedef Documentation

M_getopt_t

typedef struct M_getopt M_getopt_t

M_getopt_nonopt_cb

typedef M_bool(* M_getopt_nonopt_cb) (size_t idx, const char *option, void *thunk)

Callback for non-option parameters

M_getopt_integer_cb

typedef M_bool(* M_getopt_integer_cb) (char short_opt, const char *long_opt, M_int64 *integer, void *thunk)

Callback for integer data type

M_getopt_decimal_cb

typedef M_bool(* M_getopt_decimal_cb) (char short_opt, const char *long_opt, M_decimal_t *decimal, void *thunk)

Callback for decimal data type

M_getopt_string_cb

typedef M_bool(* M_getopt_string_cb) (char short_opt, const char *long_opt, const char *string, void *thunk)

Callback for string data type

M_getopt_boolean_cb

typedef M_bool(* M_getopt_boolean_cb) (char short_opt, const char *long_opt, M_bool boolean, void *thunk)

Callback for boolean data type

Enumeration Type Documentation

M_getopt_error_t

enum M_getopt_error_t

Error codes.

Enumerator
M_GETOPT_ERROR_SUCCESS
M_GETOPT_ERROR_INVALIDOPT
M_GETOPT_ERROR_INVALIDDATATYPE
M_GETOPT_ERROR_INVALIDORDER
M_GETOPT_ERROR_MISSINGVALUE
M_GETOPT_ERROR_NONOPTION

Function Documentation

M_getopt_create()

M_getopt_t * M_getopt_create

(

M_getopt_nonopt_cb

cb

)

Create a new getopt object.

Parameters

cb	Callback to be called with non-option parameters. NULL if non-option parameters are not allowed.

Returns

Getopt object.

M_getopt_destroy()

void M_getopt_destroy

(

M_getopt_t *

g

)

Destroy a getopt object

Parameters

[in]

g

Getopt object to destroy.

M_getopt_help()

char * M_getopt_help

(

const M_getopt_t *

g

)

Output help text for command line options.

Components: <val> value is required [val] value is optional -s short option –long long option (type) Type such as integer, decimal ... Type will not be printed for boolean options. Description Text description about the option

Example:

-s \<val\> (type) Description 

--long [val] (type) 

-s, --long [val] (type) Description 

-s Description 

Parameters

[in]

g

Getopt object.

M_getopt_addinteger()

M_bool M_getopt_addinteger	(	M_getopt_t *	g,
		char	short_opt,
		const char *	long_opt,
		M_bool	val_required,
		const char *	description,
		M_getopt_integer_cb	cb
	)

Add an integer parameter.

Parameters

[in]	g	Getopt object
[in]	short_opt	Short option, must be alpha-numeric, case-sensitive. Pass 0 if not used
[in]	long_opt	Long option name, must be alpha-numeric or hyphens, case-insensitive. Can not start or end with hyphens. Pass NULL if not used.
[in]	val_required	Whether or not the option requires a value.
[in]	description	Field description. Used with output putting help message.
[in]	cb	Callback to call with value. NULL will be passed if no value provided

Returns

M_TRUE on success, M_FALSE on failure.

M_getopt_adddecimal()

M_bool M_getopt_adddecimal	(	M_getopt_t *	g,
		char	short_opt,
		const char *	long_opt,
		M_bool	val_required,
		const char *	description,
		M_getopt_decimal_cb	cb
	)

Add a decimal parameter.

Parameters

[in]	g	Getopt object
[in]	short_opt	Short option, must be alpha-numeric, case-sensitive. Pass 0 if not used
[in]	long_opt	Long option name, must be alpha-numeric or hyphens, case-insensitive. Can not start or end with hyphens. Pass NULL if not used.
[in]	val_required	Whether or not the option requires a value.
[in]	description	Field description. Used with output putting help message.
[in]	cb	Callback to call with value. NULL will be passed if no value provided

Returns

M_TRUE on success, M_FALSE on failure.

M_getopt_addstring()

M_bool M_getopt_addstring	(	M_getopt_t *	g,
		char	short_opt,
		const char *	long_opt,
		M_bool	val_required,
		const char *	description,
		M_getopt_string_cb	cb
	)

Add a string parameter.

Parameters

[in]	g	Getopt object
[in]	short_opt	Short option, must be alpha-numeric, case-sensitive. Pass 0 if not used
[in]	long_opt	Long option name, must be alpha-numeric or hyphens, case-insensitive. Can not start or end with hyphens. Pass NULL if not used.
[in]	val_required	Whether or not the option requires a value.
[in]	description	Field description. Used with output putting help message.
[in]	cb	Callback to call with value. NULL will be passed if no value provided

Returns

M_TRUE on success, M_FALSE on failure.

M_getopt_addboolean()

M_bool M_getopt_addboolean	(	M_getopt_t *	g,
		char	short_opt,
		const char *	long_opt,
		M_bool	val_required,
		const char *	description,
		M_getopt_boolean_cb	cb
	)

Add a boolean parameter.

Parameters

[in]	g	Getopt object
[in]	short_opt	Short option, must be alpha-numeric, case-sensitive. Pass 0 if not used
[in]	long_opt	Long option name, must be alpha-numeric or hyphens, case-insensitive. Can not start or end with hyphens. Pass NULL if not used.
[in]	val_required	Whether or not the option requires a value. If M_FALSE this is treated as a flag and will be treated as M_TRUE in the value of the callback. If M_FALSE a value cannot be provided.
[in]	description	Field description. Used with output putting help message.
[in]	cb	Callback to call with value. Value will be M_TRUE if no value provided. Considered a flag enabling in this case.

Returns

M_TRUE on success, M_FALSE on failure.

M_getopt_parse()

M_getopt_error_t M_getopt_parse	(	const M_getopt_t *	g,
		const char *const *	argv,
		int	argc,
		const char **	opt_fail,
		void *	thunk
	)

Parse command line arguments.

Parameters

[in]	g	Getopt object
[in]	argv	Array of arguments. Will not be modified.
[in]	argc	Number of arguments.
[in]	opt_fail	On failure will have the argument that caused the failure.
[in]	thunk	Thunk that will be passed to callbacks.

Returns

Result.