# barabol/argset architecture

> Architecture diagram of the GitHub repository barabol/argset, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/barabol/argset
- Repository: https://github.com/barabol/argset

## Overview

Argset is a lightweight C command-line argument parsing library. An application initializes an Argset with argc/argv, registers named bool, callback, iterator, and variable arguments (plus aliases), then calls argsetCall to validate and dispatch parsed arguments; it can query bool call counts and free the parser afterward. The README also documents generated help and a default iterator for unclaimed arguments. Excerpts from arg.c are partial, so uncertain internal wiring is omitted.

Main entry points: [`src/argset/arg.c`](https://github.com/barabol/argset/blob/main/src/argset/arg.c) (Validation and Parse), [`src/argset/arg.h`](https://github.com/barabol/argset/blob/main/src/argset/arg.h) (Argset API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Application API"]
  node_argset_api["Argset API<br/>[arg.h]"]
  node_lifecycle["Init and Free<br/>[arg.c]"]
end

subgraph group_registry["Argument Registry"]
  node_registration["Argument Registration<br/>[arg.c]"]
  node_trie["Name Trie<br/>[arg.c]"]
  node_help_list["Help Listing<br/>[arg.c]"]
end

subgraph group_runtime["Parse and Dispatch"]
  node_call_parser["Validation and Parse<br/>[arg.c]"]
  node_bool_state["Bool Call Counts<br/>[arg.c]"]
  node_var_write["Typed Variable Write<br/>[arg.c]"]
  node_callbacks["User Callbacks<br/>[arg.c]"]
end

node_application(("Application"))
node_argv["Command-line Args"]
node_terminal(("Terminal Output"))
node_app_state["Application State"]

node_application -->|"uses API"| node_argset_api
node_application -->|"initializes and frees"| node_lifecycle
node_argv -->|"initializes with"| node_lifecycle
node_application -->|"registers arguments"| node_registration
node_registration -->|"inserts names"| node_trie
node_registration -->|"adds descriptions"| node_help_list
node_application -->|"invokes parse"| node_call_parser
node_call_parser -->|"reads arguments"| node_argv
node_call_parser -->|"looks up names"| node_trie
node_call_parser -->|"increments count"| node_bool_state
node_application -->|"queries count"| node_bool_state
node_call_parser -->|"converts and writes"| node_var_write
node_var_write -->|"updates value"| node_app_state
node_call_parser -->|"dispatches callbacks"| node_callbacks
node_callbacks -->|"may update"| node_app_state
node_call_parser -->|"reports errors"| node_terminal
node_application -.->|"requests help"| node_terminal
node_help_list -->|"prints descriptions"| node_terminal

click node_argset_api "https://github.com/barabol/argset/blob/main/src/argset/arg.h"
click node_lifecycle "https://github.com/barabol/argset/blob/main/src/argset/arg.c"
click node_registration "https://github.com/barabol/argset/blob/main/src/argset/arg.c"
click node_trie "https://github.com/barabol/argset/blob/main/src/argset/arg.c"
click node_help_list "https://github.com/barabol/argset/blob/main/src/argset/arg.c"
click node_call_parser "https://github.com/barabol/argset/blob/main/src/argset/arg.c"
click node_bool_state "https://github.com/barabol/argset/blob/main/src/argset/arg.c"
click node_var_write "https://github.com/barabol/argset/blob/main/src/argset/arg.c"
click node_callbacks "https://github.com/barabol/argset/blob/main/src/argset/arg.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_argset_api,node_lifecycle toneBlue
class node_registration,node_trie,node_help_list toneAmber
class node_call_parser,node_bool_state,node_var_write,node_callbacks toneMint
class node_application,node_argv,node_terminal,node_app_state toneIndigo
```

## Components

### Application API

- [Argset API](https://github.com/barabol/argset/blob/main/src/argset/arg.h): `src/argset/arg.h`
- [Init and Free](https://github.com/barabol/argset/blob/main/src/argset/arg.c): `src/argset/arg.c`

### Argument Registry

- [Argument Registration](https://github.com/barabol/argset/blob/main/src/argset/arg.c): `src/argset/arg.c`
- [Name Trie](https://github.com/barabol/argset/blob/main/src/argset/arg.c): `src/argset/arg.c`
- [Help Listing](https://github.com/barabol/argset/blob/main/src/argset/arg.c): `src/argset/arg.c`

### Parse and Dispatch

- [Validation and Parse](https://github.com/barabol/argset/blob/main/src/argset/arg.c): `src/argset/arg.c`
- [Bool Call Counts](https://github.com/barabol/argset/blob/main/src/argset/arg.c): `src/argset/arg.c`
- [Typed Variable Write](https://github.com/barabol/argset/blob/main/src/argset/arg.c): `src/argset/arg.c`
- [User Callbacks](https://github.com/barabol/argset/blob/main/src/argset/arg.c): `src/argset/arg.c`

### Other components

- **Application**
- **Command-line Args**
- **Terminal Output**
- **Application State**

## Connections

- Application → Argset API: uses API
- Application → Init and Free: initializes and frees
- Command-line Args → Init and Free: initializes with
- Application → Argument Registration: registers arguments
- Argument Registration → Name Trie: inserts names
- Argument Registration → Help Listing: adds descriptions
- Application → Validation and Parse: invokes parse
- Validation and Parse → Command-line Args: reads arguments
- Validation and Parse → Name Trie: looks up names
- Validation and Parse → Bool Call Counts: increments count
- Application → Bool Call Counts: queries count
- Validation and Parse → Typed Variable Write: converts and writes
- Typed Variable Write → Application State: updates value
- Validation and Parse → User Callbacks: dispatches callbacks
- User Callbacks → Application State: may update
- Validation and Parse → Terminal Output: reports errors
- Application → Terminal Output: requests help
- Help Listing → Terminal Output: prints descriptions