gists/kyaa/kyaa.md

161 lines
4.3 KiB
Markdown
Raw Normal View History

2016-08-18 19:46:44 -07:00
# kyaa
super hacky macro hacks for parsing arguments in C.
## prerequisites
C99 or greater.
standard library headers:
2016-08-18 19:55:00 -07:00
* `stdbool.h`
* `stdio.h`
2016-08-18 20:04:48 -07:00
* `string.h`
2016-08-18 19:46:44 -07:00
2017-04-01 19:23:01 -07:00
in addition, `kyaa_extra.h` requires `limits.h`,
or at least `LONG_MIN` to be defined.
2017-03-30 23:29:13 -07:00
## tutorial
2016-08-18 19:46:44 -07:00
2016-08-18 19:55:00 -07:00
ensure `argc` and `argv` are defined.
kyaa doesn't actually care if it's in `main` or not.
2016-08-18 19:46:44 -07:00
2016-08-18 19:50:10 -07:00
iterate over the arguments with `KYAA_LOOP`:
2016-08-18 19:46:44 -07:00
```c
int main(int argc, char *argv[]) {
KYAA_LOOP {
2017-03-30 23:29:13 -07:00
// KYAA_ITER, kyaa_name, kyaa_read_stdin, and kyaa_flag are exposed here.
2016-08-18 19:46:44 -07:00
// [other code goes here]
}
return 0;
}
```
2016-08-18 19:50:10 -07:00
use `KYAA_BEGIN` and `KYAA_END` to begin parsing arguments.
put unrelated code above `KYAA_BEGIN` or below `KYAA_END`, but not within:
2016-08-18 19:46:44 -07:00
```c
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]
}
```
2016-08-18 19:50:10 -07:00
use `KYAA_FLAG` for defining flags that don't take an argument,
and `KYAA_FLAG_ARG` or `KYAA_FLAG_LONG` for flags that do:
2016-08-18 19:46:44 -07:00
```c
bool use_feature = false;
char *log_fn = "logs.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_flag_arg is also set.
KYAA_FLAG_LONG("-v", "--var",
" set an integer variable\n"
" default: 0")
my_var = kyaa_flag_arg;
KYAA_END
// [other code goes here]
}
```
kyaa secretly wraps flag handling in if/else statements with {} blocks.
do not confuse it for a switch/case method.
2016-08-18 19:50:10 -07:00
kyaa handles `-h` and `--help` for printing help text.
additional help text may be defined using `KYAA_HELP`:
2016-08-18 19:46:44 -07:00
```c
KYAA_LOOP {
KYAA_BEGIN
KYAA_HELP(
" {files...}\n"
" do things with files.")
KYAA_END
do_stuff(kyaa_arg);
}
```
2016-08-18 19:50:10 -07:00
kyaa interprets an argument of `-` as a request to enable reading from stdin:
`kyaa_read_stdin` is set to true.
2016-08-18 19:46:44 -07:00
arguments may be passed in three ways, consider:
* `-v42`
* `-v 42`
* `--var 42`
2016-08-18 19:50:10 -07:00
kyaa returns `KYAA_OKAY` when `-h` or `--help` is given,
and `KYAA_ERROR` in the event of invalid flags, missing arguments,
or invalid numbers (`KYAA_FLAG_LONG`).
2016-08-19 02:11:10 -07:00
kyaa uses `continue` for handling arguments.
2016-08-18 19:46:44 -07:00
2016-08-18 19:50:10 -07:00
kyaa prints error messages to `stderr`, and help text to `stdout`.
2016-08-18 19:46:44 -07:00
2016-08-18 19:50:10 -07:00
`KYAA_ITER` may be redefined to avoid name collisions.
2016-08-18 19:46:44 -07:00
## TODO
* support `--var=42` argument style
2016-08-19 02:11:10 -07:00
* fix overlapping names, e.g. `KYAA_FLAG` vs `kyaa_flag`, `KYAA_FLAG_ARG` vs `kyaa_flag_arg`, etc.
2017-03-30 23:29:13 -07:00
* maybe pass `argc`/`argv` manually?
## API
### kyaa.h
2017-04-01 19:23:01 -07:00
return type or type | name | arguments or default value
--- | --- | ---
define | KYAA\_OKAY | 0
define | KYAA\_ERROR | 1
define | KYAA\_ITER | i
||
macro | KYAA\_SETUP | *none*
macro | KYAA\_LOOP | *none*
macro | KYAA\_BEGIN | *none*
macro | KYAA\_END | *none*
macro | KYAA\_DESCRIBE | c, name, description
macro | KYAA\_FLAG | c, name, description
macro | KYAA\_FLAG\_ARG | c, name, description
macro | KYAA\_HELP | description
||
`char *` | kyaa\_name | *n/a*
`bool` | kyaa\_read\_stdin | *n/a*
`char *` | kyaa\_arg | *n/a*
|| **internal use** ||
`char` | kyaa\_flag | *n/a*
`bool` | kyaa\_keep\_parsing | *n/a*
`bool` | kyaa\_parse\_next | *n/a*
`bool` | kyaa\_no\_more | *n/a*
`bool` | kyaa\_helping | *n/a*
`bool` | kyaa\_any | *n/a*
2017-03-30 23:29:13 -07:00
### kyaa\_extra.h
2017-04-01 19:23:01 -07:00
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