kyaa/kyaa.md

kyaa

super hacky macro hacks for parsing arguments in C.

prerequisites

C99 or greater.

standard library headers:

• stdbool.h
• stdio.h
• string.h

in addition, kyaa_extra.h requires limits.h, or at least LONG_MIN to be defined.

tutorial

ensure argc and argv are defined. kyaa doesn't actually care if it's in main or not.

iterate over the arguments with KYAA_LOOP:

int main(int argc, char **argv) {
    KYAA_LOOP {
        // kyaa_iter, kyaa_name, kyaa_read_stdin, and kyaa_flag are exposed here.
        // [other code goes here]
    }
    return 0;
}

use KYAA_BEGIN and KYAA_END to begin parsing arguments. put unrelated code above KYAA_BEGIN or below KYAA_END, but not within:

    KYAA_LOOP {
        // [other code goes here]
        KYAA_BEGIN
        // kyaa_arg and kyaa_etc are exposed here.
        // [kyaa code goes here]
        KYAA_END
        // [other code goes here]
    }

use KYAA_FLAG for defining flags that don't take an argument, and KYAA_FLAG_ARG or KYAA_FLAG_LONG for flags that do:

    bool use_feature = false;
    const char *log_fn = "log.txt";
    long my_var = 0;
    KYAA_LOOP {
        // [other code goes here]
        KYAA_BEGIN

        // arguments: short flag, long flag, help description
        KYAA_FLAG('x', "enable-feature",
"        enable some feature")
            use_feature = true;

        // same arguments, but kyaa_etc contains the relevant string.
        KYAA_FLAG_ARG('l', "log-file",
"        use a given filename for the log file")
            log_fn = kyaa_etc;

        // same arguments, kyaa_etc is set, but kyaa_long_value is also set.
        KYAA_FLAG_LONG('v', "var",
"        set an integer variable\n"
"        default: 0")
            my_var = kyaa_long_value;

        KYAA_END
        // [other code goes here]
    }
    return 0;

kyaa secretly wraps flag handling in if/else statements with {} blocks. do not confuse it for a switch/case method.

kyaa handles -h and --help for printing help text. additional help text may be defined using KYAA_HELP:

    KYAA_LOOP {
        KYAA_BEGIN
        KYAA_HELP(
"  {files...}\n"
"        do things with files.")
        KYAA_END

        do_stuff(kyaa_arg);
    }

kyaa interprets an argument of - as a request to enable reading from stdin: kyaa_read_stdin is set to true.

flag values may be specified in four ways; the following are equivalent:

• -v42
• -v 42
• --var 42
• --var=42

kyaa returns KYAA_OKAY when -h or --help is given, or KYAA_FAIL in the event of invalid flags, missing arguments, or invalid numbers (KYAA_FLAG_LONG). kyaa uses continue for handling arguments.

kyaa prints help text to stdout and error messages to stderr. this can be overridden by specifying KYAA_OUT and KYAA_ERR respectively.

API

kyaa.h

return type or type	name	arguments or default value	description
define	KYAA_OKAY	0	value to return upon a successful early exit
define	KYAA_FAIL	1	value to return upon encountering an error
define	KYAA_OUT	printf(VA_ARGS)	printf-like function for help text
define	KYAA_ERR	fprintf(stderr, VA_ARGS)	printf-like function for error text
macro	KYAA_SETUP	none	performs a sanity check and initializes variables
macro	KYAA_LOOP	none	begins iterating over arguments
macro	KYAA_BEGIN	none	begins parsing arguments
macro	KYAA_END	none	finishes parsing arguments
macro	KYAA_DESCRIBE	c, name, description	describes a flag for help text
macro	KYAA_FLAG	c, name, description	handles a flag that takes no arguments
macro	KYAA_FLAG_ARG	c, name, description	handles a flag that takes a string argument
macro	KYAA_HELP	description	prints additional text for help text
const char *	kyaa_name	n/a	the name of the program (usually argv[0])
int	kyaa_iter	n/a	the index of the argument being parsed
const char *	kyaa_arg	n/a	the whole argument being parsed
const char *	kyaa_etc	n/a	an argument to a flag, or NULL
bool	kyaa_read_stdin	n/a	set when an argument is - (remains set unless reset by user)
		the following entries are for internal use and may be changed without notice
macro	KYAA_IS_LONG	arg, name	tests whether arg describes a long flag called name
char	kyaa_char	n/a	the character assigned to the current flag being parsed
bool	kyaa_parsing	n/a	whether parsing occurs (-- cancels parsing)
bool	kyaa_skip	n/a	set when a flag needs another argument
bool	kyaa_helping	n/a	set when -h or --help is encountered
bool	kyaa_any	n/a	set when any flag has been matched
const char *	kyaa_equals	n/a	a pointer to the first = character in a long flag, or NULL

kyaa_extra.h

return value or type	name	arguments or default value
macro	KYAA_FLAG_LONG	c, name, description
char *	kyaa_flag_arg	n/a
char *	kyaa_skip_spaces	char * str
const char *	kyaa_str_to_long	char * str, long * p_out