# CLI Helpers

```c
#define FIO_CLI
#include "fio-stl.h"
```

A small command-line parser with auto-generated help, typed flags, and unnamed-argument support. It is easier to set up than `getopt` and stays out of the way once you have your values.

Defining `FIO_CLI` also pulls in `FIO_ATOL`, `FIO_RAND`, and `FIO_IMAP` because the parser needs them internally.

**Note:** the module keeps a global data table. Parsing and setting values is **not** thread-safe. Reading values is safe after parsing is complete.

---

## Types

#### `fio_cli_arg_e`

```c
typedef enum {
  FIO_CLI_ARG_STRING,
  FIO_CLI_ARG_BOOL,
  FIO_CLI_ARG_INT,
  FIO_CLI_ARG_PRINT,
  FIO_CLI_ARG_PRINT_LINE,
  FIO_CLI_ARG_PRINT_HEADER,
} fio_cli_arg_e;
```

Argument type tags used internally and returned by `fio_cli_type`.

**Values:**
- `FIO_CLI_ARG_STRING` — accepts any string value.
- `FIO_CLI_ARG_BOOL` — a flag; presence means true.
- `FIO_CLI_ARG_INT` — validates the value as an integer.
- `FIO_CLI_ARG_PRINT` — indented help text line.
- `FIO_CLI_ARG_PRINT_LINE` — unindented help text line.
- `FIO_CLI_ARG_PRINT_HEADER` — section header in help output.

---

## Argument Definition Macros

Use these inside the `fio_cli_start` macro to describe each flag and help line.

#### `FIO_CLI_STRING`

```c
#define FIO_CLI_STRING(line) /* ... */
```

Declares a string argument.

```c
FIO_CLI_STRING("-o -output (stdout) output file path")
```

#### `FIO_CLI_INT`

```c
#define FIO_CLI_INT(line) /* ... */
```

Declares an integer argument. The parser validates the value with `fio_atol`.

```c
FIO_CLI_INT("-p -port (8080) the port number to use")
```

#### `FIO_CLI_BOOL`

```c
#define FIO_CLI_BOOL(line) /* ... */
```

Declares a boolean flag. Boolean flags cannot have default values. They can be chained, e.g. `-abc` is treated as `-a -b -c`.

```c
FIO_CLI_BOOL("-v -verbose enable verbose logging")
```

#### `FIO_CLI_PRINT`

```c
#define FIO_CLI_PRINT(line) /* ... */
```

Prints an extra indented help line after the previous argument.

```c
FIO_CLI_INT("-p -port (8080) the port number"),
FIO_CLI_PRINT("Set to 0 for Unix socket mode.")
```

#### `FIO_CLI_PRINT_LINE`

```c
#define FIO_CLI_PRINT_LINE(line) /* ... */
```

Prints a help line without indentation.

#### `FIO_CLI_PRINT_HEADER`

```c
#define FIO_CLI_PRINT_HEADER(line) /* ... */
```

Prints a section header in the help output.

```c
FIO_CLI_PRINT_HEADER("Network Options:")
```

---

## Initialization and Cleanup

#### `fio_cli_start`

```c
#define fio_cli_start(argc, argv, unnamed_min, unnamed_max, description, ...)  \
  fio_cli_start((argc),                                                        \
                (argv),                                                        \
                (unnamed_min),                                                 \
                (unnamed_max),                                                 \
                (description),                                                 \
                (fio___cli_line_s[]){__VA_ARGS__, {0}})

SFUNC void fio_cli_start FIO_NOOP(int argc,
                                  char const *argv[],
                                  int unnamed_min,
                                  int unnamed_max,
                                  char const *description,
                                  fio___cli_line_s *arguments);
```

Parses `argv` into a dictionary of named and unnamed arguments, then prints help and exits on `-h`, `-?`, `-help`, or `--help`.

**Named Arguments:**
- `argc`, `argv` — values passed to `main`.
- `unnamed_min` — minimum required unnamed arguments. `-1` means no limit on unnamed arguments.
- `unnamed_max` — maximum allowed unnamed arguments. `-1` means unlimited.
- `description` — program description shown in help. The text `NAME` is replaced with `argv[0]`.
- `...` — argument description lines using the macros above.

Argument names must start with `-`. The first non-`-` word begins the description. Optional defaults go in parentheses: `(default)` or `("literal default")`.

Accepted input formats:

```text
app -t=1 -p3000 -a localhost
app -t 1 -p 3000 -a localhost
app --threads=1 --port=3000 --address=localhost
```

**Note:** this function is **not** thread-safe.

```c
#define FIO_CLI
#include "fio-stl.h"

int main(int argc, char const *argv[]) {
  fio_cli_start(argc, argv, 0, -1,
                "NAME - a small CLI example.\n",
                FIO_CLI_PRINT_HEADER("Options:"),
                FIO_CLI_STRING("-s -str (hello) a string"),
                FIO_CLI_INT("-i -int (42) an integer"),
                FIO_CLI_BOOL("-b -bool a boolean flag"),
                FIO_CLI_PRINT("Boolean flags do not take values."));

  fprintf(stderr, "string: %s\n", fio_cli_get("-s"));
  fprintf(stderr, "int: %" PRId64 "\n", fio_cli_get_i("-i"));
  fprintf(stderr, "bool: %d\n", (int)fio_cli_get_bool("-b"));

  fio_cli_end();
  return 0;
}
```

#### `fio_cli_end`

```c
SFUNC void fio_cli_end(void);
```

Frees the parsed CLI dictionary.

A destructor runs this automatically at program exit, but calling it earlier lets the memory be reused.

**Note:** this function is **not** thread-safe.

---

## Getting Values

#### `fio_cli_get`

```c
SFUNC char const *fio_cli_get(char const *name);
```

Returns the argument value as a NUL-terminated C string, or `NULL` if the argument was not provided. If `name` is `NULL`, returns the first unnamed argument.

#### `fio_cli_get_str`

```c
SFUNC fio_buf_info_s fio_cli_get_str(char const *name);
```

Returns the argument value as a `fio_buf_info_s` with length. If `name` is `NULL`, returns the first unnamed argument.

#### `fio_cli_get_i`

```c
SFUNC int64_t fio_cli_get_i(char const *name);
```

Returns the argument value parsed as an integer, or `0` if it was not provided. Integer parsing accepts decimal, hex, octal, and binary prefixes.

#### `fio_cli_get_bool`

```c
#define fio_cli_get_bool(name) (fio_cli_get((name)) != NULL)
```

Returns non-zero if the argument was provided, including by default.

#### `fio_cli_type`

```c
SFUNC fio_cli_arg_e fio_cli_type(char const *name);
```

Returns the declared argument type, or `FIO_CLI_ARG_NONE` if the name is unknown.

---

## Unnamed Arguments

#### `fio_cli_unnamed_count`

```c
SFUNC unsigned int fio_cli_unnamed_count(void);
```

Returns the number of unnamed arguments collected.

#### `fio_cli_unnamed`

```c
SFUNC char const *fio_cli_unnamed(unsigned int index);
```

Returns the unnamed argument at `index` as a NUL-terminated string, or `NULL` if `index` is out of bounds.

#### `fio_cli_unnamed_str`

```c
SFUNC fio_buf_info_s fio_cli_unnamed_str(unsigned int index);
```

Returns the unnamed argument at `index` as a `fio_buf_info_s`, or an empty `fio_buf_info_s` if out of bounds.

---

## Setting Values

#### `fio_cli_set`

```c
SFUNC void fio_cli_set(char const *name, char const *value);
```

Sets or overwrites a named argument's value. If `name` is `NULL`, appends `value` as a new unnamed argument.

**Note:** this function is **not** thread-safe.

#### `fio_cli_set_i`

```c
SFUNC void fio_cli_set_i(char const *name, int64_t i);
```

Sets a named argument to a base-10 string representation of `i`.

**Note:** this function is **not** thread-safe.

#### `fio_cli_set_unnamed`

```c
SFUNC unsigned int fio_cli_set_unnamed(unsigned int index, const char *value);
```

Sets or appends an unnamed argument. If `index` is past the end, the value is appended. Returns the stored index, or `(unsigned int)-1` if `value` is `NULL` or empty.

**Note:** this function is **not** thread-safe.

---

## Iteration

#### `fio_cli_each`

```c
SFUNC size_t fio_cli_each(int (*task)(fio_buf_info_s name,
                                      fio_buf_info_s value,
                                      fio_cli_arg_e arg_type,
                                      void *udata),
                          void *udata);
```

Calls `task` for every argument that has a value, returning the number of calls made. If `task` returns non-zero, iteration stops. For unnamed arguments, `name.buf` is `NULL` and `name.len` is `0`.

------------------------------------------------------------