Detailed Description

Author: hacatu

Version: 0.3.0 Command line options parsing utilities

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.

Definition in file opts.h.

Go to the source code of this file.

Data Structures
struct	cr8r_opt
	Description of a command line option A list of these, terminated with a certain sentinel value, must be passed to cr8r_opt_parse. More...

struct	cr8r_opt_cfg
	General configuration settings for parsing options. More...

Macros
#define	_CR8R_OPT_GENERIC_OPTFIELDS(_dest, _short_name, _long_name, _description)

#define	CR8R_OPT_GENERIC_OPTIONAL(_dest, _short_name, _long_name, _description)
	Represents a description for an optional scalar option. More...

#define	CR8R_OPT_GENERIC_REQUIRED(_dest, _short_name, _long_name, _description)
	Represents a description for a required scalar option. More...

#define	CR8R_OPT_ENUM_CASE(_dest, _num, _short_name, _long_name, _description)
	Represents a description for an option which takes no argument and sets *_dest to a fixed int value. More...

#define	CR8R_OPT_HELP(_opts, _description) ((cr8r_opt){.dest=(_opts), .short_name="h", .long_name="help", .description=(_description), .on_opt=cr8r_opt_print_help, .on_missing=cr8r_opt_missing_optional})
	Represents a description for a default help option (short name "h", long name "help") More...

#define	CR8R_OPT_END() ((cr8r_opt){.short_name=NULL, .long_name=NULL})
	Required sentinel for option description list.

Enumerations
enum	cr8r_opt_argmode { CR8R_OPT_ARGMODE_NONE = 0 , CR8R_OPT_ARGMODE_REQUIRED = 1 , CR8R_OPT_ARGMODE_OPTIONAL = 2 }
	Constants to set how required an option is.

enum	cr8r_opts_flags { CR8R_OPTS_FATAL_ERRS = 1ull , CR8R_OPTS_ALLOW_STRAY_DASH = 2ull , CR8R_OPTS_CB_ON_DD = 4ull }
	Flag constants to modify option parsing behavior.

Functions
bool	cr8r_opt_missing_optional (cr8r_opt *self)
	"Default" implementation of on_missing that returns true to indicate it is ok for the option to be missing CR8R_OPT_GENERIC_OPTIONAL is a convenient way to create simple optional arguments.

bool	cr8r_opt_print_help (cr8r_opt self, char opt)
	"Default" implementation of on_opt that prints help and exits Should NOT be called or used directly except by CR8R_OPT_HELP. More...

bool	cr8r_opt_set_enum_0 (cr8r_opt self, char opt)
	Implementation of on_opt that sets (int)self->dest to 0.

bool	cr8r_opt_set_enum_1 (cr8r_opt self, char opt)
	Implementation of on_opt that sets (int)self->dest to 1.

bool	cr8r_opt_ignore_arg (void data, int argc, char *argv, int i)
	"Default" implementation of on_arg that returns true and ignores a positional argument See cr8r_opt_cfg.

bool	cr8r_opt_parse (cr8r_opt opts, cr8r_opt_cfg cfg, int argc, char **argv)
	Parse command line options and arguments. More...

bool	cr8r_opt_parse_ull (cr8r_opt self, char opt)

bool	cr8r_opt_parse_ll (cr8r_opt self, char opt)

bool	cr8r_opt_parse_ul (cr8r_opt self, char opt)

bool	cr8r_opt_parse_l (cr8r_opt self, char opt)

bool	cr8r_opt_parse_u (cr8r_opt self, char opt)

bool	cr8r_opt_parse_i (cr8r_opt self, char opt)

bool	cr8r_opt_parse_us (cr8r_opt self, char opt)

bool	cr8r_opt_parse_s (cr8r_opt self, char opt)

bool	cr8r_opt_parse_uc (cr8r_opt self, char opt)
	Note that parse_uc will read single digit numbers as characters This can be sidestepped by writing them as +1, using a different type, or using a custom function.

bool	cr8r_opt_parse_sc (cr8r_opt self, char opt)
	Note that parse_sc will read single digit numbers as characters This can be sidestepped by writing them as +1, using a different type, or using a custom function.

bool	cr8r_opt_parse_c (cr8r_opt self, char opt)
	Note that parse_c will read single digit numbers as characters This can be sidestepped by writing them as +1, using a different type, or using a custom function.

bool	cr8r_opt_parse_f (cr8r_opt self, char opt)

bool	cr8r_opt_parse_d (cr8r_opt self, char opt)

bool	cr8r_opt_parse_ld (cr8r_opt self, char opt)

bool	cr8r_opt_parse_cstr (cr8r_opt self, char opt)

bool	cr8r_opt_parse_b (cr8r_opt self, char opt)

bool	cr8r_opt_parse_i128 (cr8r_opt self, char opt)

bool	cr8r_opt_parse_u128 (cr8r_opt self, char opt)

char *	cr8r_sprint_i128 (char buf[static 41], __int128 i)
	Print a signed 128 bit integer into a buffer log_10(2**127) is between 38 and 39 so the decimal representation will have at most 39 digits, plus the sign and null terminator. More...

char *	cr8r_sprint_u128 (char buf[static 40], unsigned __int128 i)
	Print a signed 128 bit integer into a buffer log_10(2**128-1) is between 38 and 39 so the decimal representation will have at most 39 digits, plus the null terminator. More...

Macro Definition Documentation

◆ _CR8R_OPT_GENERIC_OPTFIELDS

#define _CR8R_OPT_GENERIC_OPTFIELDS	(	_dest,
		_short_name,
		_long_name,
		_description
	)

Value:

    .dest = (_dest),\
    .arg_mode = CR8R_OPT_ARGMODE_REQUIRED,                                     \
    .short_name = (_short_name),                                               \
    .long_name = (_long_name),                                                 \
    .description = (_description),                                             \
    .on_opt = _Generic(*(_dest),                                               \
    unsigned long long: cr8r_opt_parse_ull,                                    \
    long long: cr8r_opt_parse_ll,                                              \
    unsigned long: cr8r_opt_parse_ul,                                          \
    long: cr8r_opt_parse_l,                                                    \
    unsigned: cr8r_opt_parse_u,                                                \
    int: cr8r_opt_parse_i,                                                     \
    unsigned short: cr8r_opt_parse_us,                                         \
    short: cr8r_opt_parse_s,                                                   \
    unsigned char: cr8r_opt_parse_uc,                                          \
    signed char: cr8r_opt_parse_sc,                                            \
    char: cr8r_opt_parse_c,                                                    \
    float: cr8r_opt_parse_f,                                                   \
    double: cr8r_opt_parse_d,                                                  \
    long double: cr8r_opt_parse_ld,                                            \
    char*: cr8r_opt_parse_cstr,                                                \
    _Bool: cr8r_opt_parse_b,                                                   \
    __int128: cr8r_opt_parse_i128,                                             \
    unsigned __int128: cr8r_opt_parse_u128),

Definition at line 226 of file opts.h.

◆ CR8R_OPT_GENERIC_OPTIONAL

#define CR8R_OPT_GENERIC_OPTIONAL	(	_dest,
		_short_name,
		_long_name,
		_description
	)

Value:

    ((cr8r_opt){\
    _CR8R_OPT_GENERIC_OPTFIELDS((_dest),(_short_name), (_long_name), (_description))\
    .on_missing = cr8r_opt_missing_optional,})

Represents a description for an optional scalar option.

Parameters

[in,out]	_dest	a pointer to a scalar type (char, _Bool, signed/unsigned char/short/int/long/long long, float/double/long double) where the result of parsing the argument to this option should be stored. Note that _Imaginary and _Complex types currently require a custom on_opt callback and aren't compatible with this macro.
[in]	_short_name	short name for the option. Must be a single (possibly multibyte) character besides ' ', '-', or '='
[in]	_long_name	long name for the option. May not contain ' ' or '='. At least one of _long_name and _short_name must be nonnull
[in]	_description	description of the option to print in help text.

Definition at line 260 of file opts.h.

◆ CR8R_OPT_GENERIC_REQUIRED

#define CR8R_OPT_GENERIC_REQUIRED	(	_dest,
		_short_name,
		_long_name,
		_description
	)

Value:

((cr8r_opt){\

_CR8R_OPT_GENERIC_OPTFIELDS((_dest), (_short_name), (_long_name), (_description))})

Represents a description for a required scalar option.

Parameters

[in,out]	_dest	a pointer to a scalar type (char, _Bool, signed/unsigned char/short/int/long/long long, float/double/long double) where the result of parsing the argument to this option should be stored. Note that _Imaginary and _Complex types currently require a custom on_opt callback and aren't compatible with this macro.
[in]	_short_name	short name for the option. Must be a single (possibly multibyte) character besides ' ', '-', or '='
[in]	_long_name	long name for the option. May not contain ' ' or '='. At least one of _long_name and _short_name must be nonnull
[in]	_description	description of the option to print in help text.

Definition at line 273 of file opts.h.

◆ CR8R_OPT_ENUM_CASE

#define CR8R_OPT_ENUM_CASE	(	_dest,
		_num,
		_short_name,
		_long_name,
		_description
	)

Value:

((cr8r_opt){\

.dest=(_dest), .arg_mode=CR8R_OPT_ARGMODE_NONE, .short_name=(_short_name), .long_name=(_long_name), .description=(_description), .on_opt=cr8r_opt_set_enum_##_num, .on_missing=cr8r_opt_missing_optional})

Represents a description for an option which takes no argument and sets *_dest to a fixed int value.

Parameters

[out]	_dest	a pointer to an int (or enum) which should be modified
[in]	_num	the value *_dest should be set to if this option is found. currently, this must be 0 or 1.
[in]	_short_name	short name for the option. Must be a single (possibly multibyte) character besides ' ', '-', or '='
[in]	_long_name	long name for the option. May not contain ' ' or '='. At least one of _long_name and _short_name must be nonnull
[in]	_description	description of the option to print in help text.

Definition at line 283 of file opts.h.

◆ CR8R_OPT_HELP

#define CR8R_OPT_HELP	(	_opts,
		_description
	)	((cr8r_opt){.dest=(_opts), .short_name="h", .long_name="help", .description=(_description), .on_opt=cr8r_opt_print_help, .on_missing=cr8r_opt_missing_optional})

Represents a description for a default help option (short name "h", long name "help")

The help option also prints all other options and their descriptions

Parameters

[in]	_opts	the array of option descriptions containing this option description, to print help for
[in]	_description	description of the option to print in help text.

Definition at line 291 of file opts.h.

Function Documentation

◆ cr8r_opt_print_help()

bool cr8r_opt_print_help	(	cr8r_opt *	self,
		char *	opt
	)

"Default" implementation of on_opt that prints help and exits Should NOT be called or used directly except by CR8R_OPT_HELP.

Requires self->dest to point to the options list.

◆ cr8r_opt_parse()

bool cr8r_opt_parse	(	cr8r_opt *	opts,
		cr8r_opt_cfg *	cfg,
		int	argc,
		char **	argv
	)

Parse command line options and arguments.

opts is a list of option descriptions, terminated by one whose short_name and long_name are both NULL. The command line arguments are then parsed according to these options in the following way:

Command line arguments are read from increasing indicies starting at 1.

If an argument is "--", it indicates the end of option parsing and the remaining arguments are all treated as positional arguments.

Otherwise, if an argument starts with "--", it is considered a long name option. If the command line argument containing a long name option contains an '=', the portion after the '=' is considered the argument to the option. Otherwise, if the next command line argument does not start with a '-', it is considered the argument to the option. Otherwise, the option is considered to not have an argument.

If an argument starts with "-" followed by one or more valid short option names, it is considered a short option group. The group ends when '\0', '=', or an invalid short option name is encountered. All short options until the last one are considered to not have an argument. The rules for determining the argument to the last option are the same as for long name options.

If an argument is "-", it is an error.

Any other command line argument, one which is not a long name option, short name option group, "--", "-", or an argument to an option, is a positional argument.

If a short/long option name is encountered which is not in opts, this is an error. If an option that requires an argument but does not have one, this is considered an error. Otherwise, the option's on_opt callback is called if it is not NULL and then it is set to found. If on_opt return false it is an error. After parsing is done, any options which were not found have on_missing called. If an option is missing and on_missing is NULL or returns false for it, this is an error. If on_missing returns true, this is ok.

If a positional argument is encountered, cfg->on_arg is called. If it is NULL or returns false, this is an error.

If opts is invalid, this function prints an error and returns false. Otherwise, it parses the arguments as described above. If an error is encountered, false is returned, immediately if cfg->stop_on_first_err is true and after all arguments have been read otherwise.

Parameters

[in,out]	opts	pointer to a list of option descriptions, terminated by an option description with both short_name and long_name NULL. `found` is set on each option according to whether it was seen.
[in]	cfg	general parsing options
[in]	argc,argv	parameters to `main`

◆ cr8r_sprint_i128()

char* cr8r_sprint_i128	(	char	buf[static 41],
		__int128	i
	)

Print a signed 128 bit integer into a buffer log_10(2**127) is between 38 and 39 so the decimal representation will have at most 39 digits, plus the sign and null terminator.

Parameters

[out]	buf	buffer to hold the result, must be able to hold at least 41 chars
[in]	i	number to print

Returns: pointer to beginning of result (will be 0-39 bytes into buf)

◆ cr8r_sprint_u128()

char* cr8r_sprint_u128	(	char	buf[static 40],
		unsigned __int128	i
	)

Print a signed 128 bit integer into a buffer log_10(2**128-1) is between 38 and 39 so the decimal representation will have at most 39 digits, plus the null terminator.

Parameters

[out]	buf	buffer to hold the result, must be able to hold at least 40 chars
[in]	i	number to print

Returns: pointer to beginning of result (will be 0-39 bytes into buf)

Detailed Description

Data Structures

Macros

Enumerations

Functions

Macro Definition Documentation

◆ _CR8R_OPT_GENERIC_OPTFIELDS

◆ CR8R_OPT_GENERIC_OPTIONAL

◆ CR8R_OPT_GENERIC_REQUIRED

◆ CR8R_OPT_ENUM_CASE

◆ CR8R_OPT_HELP

Function Documentation

◆ cr8r_opt_print_help()

◆ cr8r_opt_parse()

◆ cr8r_sprint_i128()

◆ cr8r_sprint_u128()