AxlArgs – Argument Parser

Declarative command-line argument parser. Supports short flags (-v), long flags (--verbose), value options (-o file, --port=8080), repeated options (-H hdr1 -H hdr2), and positional arguments. -- stops option parsing.

Header: <axl/axl-args.h>

Overview

Define an option table, call axl_args_parse, then query results:

#include <axl.h>

static const AxlOpt opts[] = {
    { 'v', "--verbose", AXL_OPT_FLAG,  NULL,   "Verbose output" },
    { 'o', "--output",  AXL_OPT_VALUE, "FILE", "Output file" },
    { 'H', NULL,        AXL_OPT_MULTI, "HDR",  "HTTP header (repeatable)" },
    { 'h', "--help",    AXL_OPT_FLAG,  NULL,   "Show help" },
    { 0 }  // terminator
};

int main(int argc, char **argv) {
    AXL_AUTOPTR(AxlArgs) args = axl_args_parse(argc, argv, opts);
    if (args == NULL) {
        axl_args_usage("myapp", "[options] <file>", opts);
        return 1;
    }

    if (axl_args_flag(args, 'h')) {
        axl_args_usage("myapp", "[options] <file>", opts);
        return 0;
    }

    bool verbose = axl_args_flag(args, 'v');
    const char *output = axl_args_value(args, 'o');  // NULL if not given
    const char *file = axl_args_pos(args, 0);        // first positional

    // Repeated options
    size_t hdr_count = axl_args_multi_count(args, 'H');
    for (size_t i = 0; i < hdr_count; i++) {
        axl_printf("Header: %s\n", axl_args_multi(args, 'H', i));
    }

    return 0;
}

Option Types

Type	Description
AXL_OPT_FLAG	Boolean flag (`-v`, `--verbose`)
AXL_OPT_VALUE	Takes a value (`-o file`, `--port=8080`)
AXL_OPT_MULTI	Repeatable value (`-H hdr1 -H hdr2`)

API Reference

Typedefs

typedef struct AxlArgs AxlArgs

Enums

enum AxlOptType

Values:

enumerator AXL_OPT_FLAG

enumerator AXL_OPT_VALUE

enumerator AXL_OPT_MULTI

Functions

AxlArgs *axl_args_parse(int argc, char **argv, const AxlOpt *opts)

Parse command-line arguments against the given option definitions.

Unknown options cause an error.

Parameters:

argc – argument count (from main or AXL_APP)
argv – argument vector (argv[0] is skipped)
opts – NULL-terminated array of option definitions

Returns:

parsed arguments, or NULL on error (unknown option, missing value, overflow). Free with axl_args_free().

bool axl_args_flag(AxlArgs *a, char short_opt)

Check if a flag was present.

Parameters:

a – parsed arguments
short_opt – short option character

Returns:

true if the flag was given, false otherwise.

bool axl_args_flag_long(AxlArgs *a, const char *long_opt)

Check if a flag was present by long name.

Parameters:

a – parsed arguments
long_opt – long option name (e.g. “–verbose”)

Returns:

true if the flag was given, false otherwise.

const char *axl_args_value(AxlArgs *a, char short_opt)

Get the value of a VALUE option.

Parameters:

a – parsed arguments
short_opt – short option character

Returns:

option value (borrowed from argv), or NULL if absent.

const char *axl_args_value_long(AxlArgs *a, const char *long_opt)

Get the value of a VALUE option by long name.

Parameters:

a – parsed arguments
long_opt – long option name (e.g. “–output”)

Returns:

option value (borrowed from argv), or NULL if absent.

size_t axl_args_multi_count(AxlArgs *a, char short_opt)

Get the number of values for a MULTI option.

Parameters:

a – parsed arguments
short_opt – short option character

Returns:

count of values, or 0 if absent.

const char *axl_args_multi(AxlArgs *a, char short_opt, size_t index)

Get one value from a MULTI option.

Parameters:

a – parsed arguments
short_opt – short option character
index – value index (0-based)

Returns:

value at @index (borrowed from argv), or NULL if out of range.

size_t axl_args_pos_count(AxlArgs *a)

Get the number of positional (non-option) arguments.

Parameters:

a – parsed arguments

Returns:

positional argument count.

const char *axl_args_pos(AxlArgs *a, size_t index)

Get a positional argument.

Parameters:

a – parsed arguments
index – positional index (0-based)

Returns:

argument string (borrowed from argv), or NULL if out of range.

void axl_args_usage(const char *app, const char *synopsis, const AxlOpt *opts)

Print a formatted usage/help message to stdout via axl_print().

Parameters:

app – application name (e.g. argv[0])
synopsis – brief usage pattern (e.g. “[OPTIONS] FILE…”)
opts – NULL-terminated array of option definitions

void axl_args_free(AxlArgs *a)

Free parsed arguments. NULL-safe.

Parameters:

a – parsed arguments, or NULL

struct AxlOpt

#include <axl-args.h>

AxlOpt:

Option definition. Terminate the array with a zero entry: { 0, NULL, 0, NULL, NULL }.

Public Members

char short_opt: single-character flag (e.g. ‘v’), or 0 for none

const char *long_opt: long name including “–” prefix (e.g. “–verbose”), or NULL

AxlOptType type: AXL_OPT_FLAG, AXL_OPT_VALUE, or AXL_OPT_MULTI.

const char *arg_name: placeholder for usage (e.g. “FILE”), or NULL for flags

const char *help: help text for usage output, or NULL