### Automatic Help Generation Example (Bash)

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/quickstart.md

Illustrates the automatic help message generated by Argus for a CLI tool, showing usage, arguments, and options with their descriptions and defaults.

```bash
$ ./my_tool --help
my_tool v1.0.0

A simple file processing tool

Usage: my_tool [OPTIONS] <input>

Arguments:
  <input>                - Input file to process

Options:
  -h, --help             - Display this help message (exit)
  -V, --version          - Display version information (exit)
  -v, --verbose          - Enable verbose output
  -o, --output <STR>     - Output file (default: "result.txt")
  -c, --count <1-100>    - Number of iterations (default: 1)

```

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

### Flexible Input Formats Example (Bash)

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/quickstart.md

Shows different ways to provide arguments to an Argus-based CLI tool, including using long options, short options, and combined short options with values.

```bash
./my_tool --output=file.txt --count=5 input.txt
./my_tool -o file.txt -c 5 input.txt  
./my_tool -ofile.txt -c5 input.txt

```

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

### Verify Argus Installation with C Example

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/installation.md

This C code snippet demonstrates how to initialize and parse arguments using the Argus library. It checks for successful parsing and prints a confirmation message. Compile and run this to ensure Argus is functional.

```c
#include <argus.h>
#include <stdio.h>

ARGUS_OPTIONS(
    options,
    HELP_OPTION(),
)

int main(int argc, char **argv)
{
    argus_t argus = argus_init(options, "test", "0.1.0");
    int status = argus_parse(&argus, argc, argv);
    
    if (status == ARGUS_SUCCESS)
        printf("✅ Argus is working!\n");
    
    return 0;
}
```

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

### Compile and Test Argus C Example

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/installation.md

These bash commands compile the verification C code using GCC, linking against the Argus library, and then execute the compiled program with the --help flag to test Argus functionality.

```bash
# Compile and test
gcc test.c -o test -largus
./test --help
```

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

### Build Argus from Source (Windows MinGW/MSYS2)

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/installation.md

Builds and installs Argus from source on Windows using MinGW/MSYS2, including installing Meson and Ninja via pacman.

```bash
# Install dependencies
pacman -S mingw-w64-x86_64-meson mingw-w64-x86_64-ninja

# Build
git clone https://github.com/lucocozz/argus.git
cd argus
meson setup builddir # -Dregex=false
meson compile -C builddir
meson install -C builddir
```

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

### Build Argus from Source (Linux/macOS)

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/installation.md

Builds and installs Argus from source code using Git and the Meson build system. Dependencies like Meson and Ninja are recommended.

```bash
git clone https://github.com/lucocozz/argus.git
cd argus
meson setup builddir # -Dregex=false
meson compile -C builddir
sudo meson install -C builddir
```

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

### Build and Test Argus CLI Tool (Bash)

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/quickstart.md

Shows how to compile a C application using Argus with GCC, including a development build and a production build with ARGUS_RELEASE for faster startup.

```bash
# Development build (recommended during development)
gcc my_tool.c -o my_tool -largus
./my_tool --help    # See auto-generated help
./my_tool input.txt # Run your tool

# Production build (skip validation for better performance)
gcc -DARGUS_RELEASE my_tool.c -o my_tool-prod -largus

```

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

### Server Tool CLI Pattern

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/quickstart.md

A pattern for network services and servers, including options for bind address, port with validation, configuration file, and running as a daemon.

```c
ARGUS_OPTIONS(options,
    HELP_OPTION(),
    VERSION_OPTION(),
    OPTION_STRING('H', "host", HELP("Bind address"), DEFAULT("0.0.0.0")),
    OPTION_INT('p', "port", HELP("Port"), DEFAULT(8080), 
               VALIDATOR(V_RANGE(1, 65535))),
    OPTION_STRING('c', "config", HELP("Config file")),
    OPTION_FLAG('d', "daemon", HELP("Run as daemon")),
)
```

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

### Install Argus with Meson

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/installation.md

Installs Argus using the Meson build system. The regex support can be disabled during installation by setting the appropriate flag.

```bash
meson install argus
# Without Regex support (removes PCRE2 dependency)
meson install argus -Dregex=false
```

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

### Input Validation Example (Bash)

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/quickstart.md

Demonstrates Argus's input validation by showing an error message when a value for the '--count' option falls outside the defined range.

```bash
$ ./my_tool --count 150 input.txt
my_tool: Value 150 is out of range [1, 100]

```

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

### Integrate Argus with Meson

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/installation.md

This meson.build file demonstrates how to use Meson's subproject feature to find and include the Argus library, retrieve its dependencies, and link them to your executable.

```meson
argus_project = subproject('argus', version: '>=0.1.0')
# Without Regex support
# argus_project = subproject('argus', version: '>=0.1.0', default_options: ['regex=false'])

argus_dep = argus_project.get_variable('argus_dep')

executable('myapp', 'main.c', 
          dependencies: [argus_dep])
```

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

### Define CLI Interface with Argus (C)

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/quickstart.md

Demonstrates defining command-line interface options declaratively using the Argus C library. Includes help, version, verbose, output, count, and positional arguments with default values and validation.

```c
#include <argus.h>
#include <stdio.h>

// Define your CLI interface declaratively
ARGUS_OPTIONS(
    options,
    HELP_OPTION(),                    // Automatic --help/-h
    VERSION_OPTION(),                 // Automatic --version/-V
    
    OPTION_FLAG('v', "verbose", 
        HELP("Enable verbose output")),
    
    OPTION_STRING('o', "output", 
        HELP("Output file"), 
        DEFAULT("result.txt")),
    
    OPTION_INT('c', "count", 
        HELP("Number of iterations"), 
        DEFAULT(1),
        VALIDATOR(V_RANGE(1, 100))),
    
    POSITIONAL_STRING("input", 
        HELP("Input file to process")),
)

int main(int argc, char **argv)
{
    // Initialize with program info
    argus_t argus = argus_init(options, "my_tool", "1.0.0");
    argus.description = "A simple file processing tool";
    
    // Parse arguments - handles errors automatically
    if (argus_parse(&argus, argc, argv) != ARGUS_SUCCESS) {
        return 1;
    }
    
    // Access parsed values with type safety
    const char *input = argus_get(&argus, "input").as_string;
    const char *output = argus_get(&argus, "output").as_string;
    int count = argus_get(&argus, "count").as_int;
    bool verbose = argus_get(&argus, "verbose").as_bool;
    
    // Your application logic
    if (verbose) {
        printf("Processing %s -> %s (%d times)\n", input, output, count);
    }
    
    printf("File processed successfully!\n");
    
    // Cleanup
    argus_free(&argus);
    return 0;
}

```

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

### Simple Utility CLI Pattern

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/quickstart.md

A common pattern for creating simple utility tools that process a single input file and produce output, featuring verbose flags and output file options.

```c
ARGUS_OPTIONS(options,
    HELP_OPTION(),
    VERSION_OPTION(),
    OPTION_FLAG('v', "verbose", HELP("Verbose output")),
    OPTION_STRING('o', "output", HELP("Output file")),
    POSITIONAL_STRING("input", HELP("Input file")),
)
```

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

### Argus Option Definitions (C)

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/quickstart.md

Illustrates defining various types of command-line options using the Argus C library, including flags, strings with defaults, and integers with validators.

```c
// Flag (boolean, no value needed)
OPTION_FLAG('v', "verbose", HELP("Enable verbose mode"))

// String option with default value
OPTION_STRING('o', "output", HELP("Output file"), DEFAULT("out.txt"))

// Integer with validation
OPTION_INT('p', "port", HELP("Port number"), 
           VALIDATOR(V_RANGE(1, 65535)))

```

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

### Build Argus from Source (macOS with Homebrew)

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/installation.md

Builds and installs Argus from source on macOS, including installing dependencies like Meson, Ninja, and PCRE2 via Homebrew.

```bash
# Install dependencies
brew install meson ninja pcre2

# Build and install
git clone https://github.com/lucocozz/argus.git
cd argus
meson setup builddir # -Dregex=false
meson compile -C builddir
sudo meson install -C builddir
```

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

### Argus Build Configuration Options

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/installation.md

Customizes the Argus build process when compiling from source. Options include disabling regex support, setting build types, and specifying installation prefixes.

```bash
# Disable regex support (removes PCRE2 dependency)
meson setup builddir -Dregex=false

# Release build for production
meson setup builddir

# Install to custom location
meson setup builddir --prefix=/opt/argus

# Enable tests and examples
meson setup builddir -Dtests=true -Dexamples=true

# Debug build with coverage
meson setup builddir --buildtype=debug -Db_coverage=true
```

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

### Add Subcommands to CLI

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/quickstart.md

Demonstrates how to define subcommands for a multi-command interface using the Argus library. It shows the structure for defining subcommand-specific options and linking them to actions.

```c
ARGUS_OPTIONS(process_options,
    HELP_OPTION(),
    OPTION_FLAG('f', "force", HELP("Force processing")),
    POSITIONAL_STRING("file", HELP("File to process")),
)

ARGUS_OPTIONS(options,
    HELP_OPTION(),
    VERSION_OPTION(),
    SUBCOMMAND("process", process_options, 
               HELP("Process files"), 
               ACTION(process_command)),
)
```

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

### Handle String Arrays and Maps

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/quickstart.md

Illustrates how to define options that accept collections of values, specifically arrays of strings and key-value maps, using the Argus library's collection handling macros.

```c
// Array of strings: --tags=web,api,backend
OPTION_ARRAY_STRING('t', "tags", HELP("Tags"))

// Key-value map: --env=DEBUG=1,LOG_LEVEL=info  
OPTION_MAP_STRING('e', "env", HELP("Environment variables"))
```

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

### Build Tool CLI Pattern

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/quickstart.md

A pattern suitable for build systems and compilers, featuring options for verbosity, build targets, parallel job execution, and forcing rebuilds.

```c
ARGUS_OPTIONS(options,
    HELP_OPTION(),
    VERSION_OPTION(),
    OPTION_FLAG('v', "verbose", HELP("Verbose output")),
    OPTION_STRING('t', "target", HELP("Build target"), DEFAULT("all")),
    OPTION_INT('j', "jobs", HELP("Parallel jobs"), DEFAULT(1)),
    OPTION_FLAG('f', "force", HELP("Force rebuild")),
)
```

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

### Integrate Argus with XMake

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/installation.md

This xmake.lua script adds Argus as a required dependency for your project, sets up your target executable, and links the Argus packages to your application.

```lua
add_requires("argus >=0.1.0")
target("myapp")
    set_kind("binary")
    add_files("main.c")
    add_packages("argus")
```

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

### Argus Quick Start: Basic CLI Example (C)

Source: https://github.com/lucocozz/argus/blob/main/README.md

A minimal example demonstrating how to create a simple command-line interface using Argus. It shows the initialization of Argus options, parsing arguments, accessing parsed values in a type-safe manner, and freeing Argus resources.

```c
#include <argus.h>

ARGUS_OPTIONS(
    options,
    HELP_OPTION(),
    OPTION_FLAG('v', "verbose", HELP("Verbose output")),
    OPTION_STRING('o', "output", HELP("Output file"), DEFAULT("result.txt")),
    POSITIONAL_STRING("input", HELP("Input file"))
)

int main(int argc, char **argv)
{
    argus_t argus = argus_init(options, "my_tool", "1.0.0");
    
    if (argus_parse(&argus, argc, argv) != ARGUS_SUCCESS)
        return 1;
    
    // Type-safe access
    bool verbose = argus_get(argus, "verbose").as_bool;
    const char *input = argus_get(argus, "input").as_string;
    
    printf("Processing %s\n", input);
    
    argus_free(&argus);
    return 0;
}
```

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

### Generated Help Output Example

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/fundamentals/help-and-errors.md

Example of the help text automatically generated by Argus for the basic setup, showing program name, version, description, usage, arguments, and options.

```bash
$ ./my_tool --help
my_tool v1.0.0

A simple file processing tool

Usage: my_tool [OPTIONS] <input>

Arguments:
  <input>                - Input file to process

Options:
  -h, --help             - Display this help message (exit)
  -V, --version          - Display version information (exit)
  -v, --verbose          - Enable verbose output
  -o, --output <STR>     - Output file (default: "result.txt")
  -p, --port <1-65535>   - Port number (default: 8080)
```

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

### Install Argus System Packages

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/installation.md

Installs Argus using native system package managers for Ubuntu/Debian, Fedora/CentOS/RHEL, and Arch Linux.

```bash
# Ubuntu/Debian
sudo apt update
sudo apt install libargus-dev

# Fedora/CentOS/RHEL
sudo dnf install argus-devel

# Arch Linux
sudo pacman -S argus
```

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

### Install Argus with vcpkg

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/installation.md

Installs Argus using the vcpkg package manager. An option is provided to exclude regex support, which removes the PCRE2 dependency.

```bash
vcpkg install argus
# Without Regex support (removes PCRE2 dependency)
vcpkg install argus[core]
```

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

### Install Argus with Conan

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/installation.md

Installs Argus using the Conan package manager. Users can specify the version and disable regex support to omit the PCRE2 dependency.

```bash
conan install argus/0.1.0
# Without Regex support (removes PCRE2 dependency)
conan install argus/0.1.0 -o argus:regex=False
```

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

### Argus Positional Argument Definitions (C)

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/quickstart.md

Demonstrates defining positional (non-prefixed) arguments in Argus, including required strings and optional integers with defaults.

```c
// Required positional (must be provided)
POSITIONAL_STRING("input", HELP("Input file"))

// Optional positional with default
POSITIONAL_INT("buffer_size", HELP("Buffer size"), 
               FLAGS(FLAG_OPTIONAL), DEFAULT(1024))

```

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

### Install Argus with XRepo

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/installation.md

Installs Argus using the XRepo package manager. It's possible to disable regex support by passing a specific argument.

```bash
xrepo install argus
# Without Regex support (removes PCRE2 dependency)
xrepo install "regex=false" argus
```

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

### Deployment Tool Usage Example (Bash)

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/features/collections.md

Example command-line usage for the C deployment tool program, showing how to specify target environments, service configurations, resource limits, and feature rollout percentages.

```bash
./deploy --environments=staging,production \
         --services=web=nginx:1.20,api=myapp:v2.1 \
         --resources=staging_cpu=2,production_cpu=8 \
         --rollout=feature_x=50.0,feature_y=100.0
```

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

### Integrate Argus with CMake

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/installation.md

This CMakeLists.txt file shows how to find the Argus library using PkgConfig, add your application executable, and link it with the necessary Argus libraries and include directories.

```cmake
find_package(PkgConfig REQUIRED)
pkg_check_modules(ARGUS REQUIRED argus)

add_executable(myapp main.c)
target_link_libraries(myapp ${ARGUS_LIBRARIES})
target_include_directories(myapp PRIVATE ${ARGUS_INCLUDE_DIRS})
```

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

### Container Management CLI Usage Examples

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/features/subcommands.md

Provides bash command examples for interacting with the container management CLI built with Argus. It demonstrates how to run, list, and stop containers, as well as pull, build, and list images, including how to access help at different levels.

```bash
# Container commands
./container-tool container run --name web -p 8080:80 nginx
./container-tool container list
./container-tool container stop web

# Image commands  
./container-tool image pull nginx:latest
./container-tool image build -t myapp .
./container-tool image list

# Help at each level
./container-tool --help
./container-tool container --help
./container-tool container run --help

```

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

### Build Tool Usage Example (Bash)

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/features/collections.md

Example command-line usage for the C build tool program, demonstrating how to pass build targets, preprocessor definitions, and feature flags using the Argus-parsed options.

```bash
./builder --targets=lib,bin,tests \
          --define=DEBUG=1,VERSION=2.0 \
          --features=optimization=true,debug=false
```

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

### Argus Input Validation Macros (C)

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/quickstart.md

Shows how to use Argus's built-in validator macros to enforce constraints on input arguments, such as ranges, lengths, regular expressions, and choices.

```c
// Range validation
OPTION_INT('p', "port", HELP("Port"), VALIDATOR(V_RANGE(1, 65535)))

// String length
OPTION_STRING('u', "user", HELP("Username"), VALIDATOR(V_LENGTH(3, 20)))

// Regex patterns (requires PCRE2)
OPTION_STRING('e', "email", HELP("Email"), VALIDATOR(V_REGEX(ARGUS_RE_EMAIL)))

// Multiple choices
OPTION_STRING('l', "level", HELP("Log level"), 
              VALIDATOR(V_CHOICE_STR("debug", "info", "warn", "error")))

```

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

### Configure Examples Option

Source: https://github.com/lucocozz/argus/blob/main/meson_options.txt

Enables or disables the building of example programs. This option is a boolean flag.

```config
option('examples', type: 'boolean', value: false, description: 'Build example programs')
```

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

### CLI Usage Examples

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/examples/simple-cli.md

Provides examples of how to compile and run the C CLI tool. It covers building the executable using GCC, basic execution with an input file, running with various command-line options, and displaying the help message.

```bash
# Build
gcc simple_cli.c -o simple_cli -largus

# Basic usage
echo "Hello World" > input.txt
./simple_cli input.txt

# With options
./simple_cli --verbose --format json --count 3 input.txt

# Help
./simple_cli --help
```

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

### Building Argus from Source with Meson

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/appendices/contributing.md

Instructions for building Argus from source using Meson, covering basic builds, development builds with tests and examples, and debug builds with coverage.

```bash
# Basic build
meson setup build
meson compile -C build

# Development build with tests
meson setup build -Dtests=true -Dexamples=true
meson compile -C build

# Debug build
meson setup build --buildtype=debug -Db_coverage=true
```

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

### Argus Installation Methods (Bash)

Source: https://github.com/lucocozz/argus/blob/main/README.md

Outlines different methods for installing the Argus library, including using package managers like vcpkg and Conan, as well as building from source using Meson.

```bash
# Package managers
vcpkg install argus
conan install argus/0.1.0

# From source
git clone https://github.com/lucocozz/argus.git && cd argus
meson setup build && meson compile -C build && sudo meson install -C build
```

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

### Argus CLI Option Parsing Example

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/appendices/contributing.md

A C code example demonstrating how to initialize Argus with options, parse command-line arguments, retrieve parsed values, and free the Argus instance.

```c
// Example test structure
void test_option_parsing(void)
{
    ARGUS_OPTIONS(options,
        OPTION_STRING('o', "output", HELP("Output"))
    );
    
    argus_t argus = argus_init(options, "test", "1.0.0");
    
    char *argv[] = {"test", "--output", "file.txt"};
    assert(argus_parse(&argus, 3, argv) == ARGUS_SUCCESS);
    
    const char *output = argus_get(&argus, "output").as_string;
    assert(strcmp(output, "file.txt") == 0);
    
    argus_free(&argus);
}
```

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

### Argus Configuration Tool - C Example

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/examples/configuration-tool.md

This C code demonstrates how to use the Argus library to define, parse, and utilize command-line arguments and environment variables. It showcases various option types including strings, integers, arrays, and maps, along with validation, default values, and environment variable integration. The example also includes logic for printing parsed values and generating a JSON configuration file.

```c
#include <argus.h>
#include <stdio.h>

ARGUS_OPTIONS(
    options,
    HELP_OPTION(),
    VERSION_OPTION(),
    
    // Arrays
    OPTION_ARRAY_STRING('t', "tags", HELP("Resource tags"),
                        FLAGS(FLAG_UNIQUE | FLAG_SORTED),
                        VALIDATOR(V_COUNT(1, 10))),
    
    OPTION_ARRAY_INT('p', "ports", HELP("Port numbers (supports ranges)"),
                     VALIDATOR(V_COUNT(1, 5))),
    
    // Maps  
    OPTION_MAP_STRING('e', "env", HELP("Environment variables"),
                      ENV_VAR("CONFIG_ENV"), FLAGS(FLAG_SORTED_KEY)),
    
    OPTION_MAP_BOOL('f', "features", HELP("Feature toggles"),
                    FLAGS(FLAG_SORTED_KEY)),
    
    // Environment integration
    OPTION_STRING('n', "name", HELP("Service name"),
                  ENV_VAR("SERVICE_NAME"), FLAGS(FLAG_REQUIRED)),
    
    OPTION_STRING('h', "host", HELP("Host address"),
                  ENV_VAR("HOST"), DEFAULT("localhost")),
    
    OPTION_INT('P', "port", HELP("Main port"),
               ENV_VAR("PORT"), VALIDATOR(V_RANGE(1, 65535)), DEFAULT(8080)),
    
    // Email validation
    OPTION_STRING('c', "contact", HELP("Contact email"),
                  VALIDATOR(V_REGEX(ARGUS_RE_EMAIL))),
    
    // Optional output
    POSITIONAL_STRING("output", HELP("Output file"), FLAGS(FLAG_OPTIONAL)),
)

void print_array_strings(argus_t argus, const char *name)
{
    if (!argus_is_set(&argus, name)) return; 
    
    printf("%s:\n", name);
    argus_array_it_t it = argus_array_it(&argus, name);
    while (argus_array_next(&it))
        printf("  - %s\n", it.value.as_string);
}

void print_array_ints(argus_t argus, const char *name)
{
    if (!argus_is_set(&argus, name)) return; 
    
    printf("%s:\n", name);
    argus_array_it_t it = argus_array_it(&argus, name);
    while (argus_array_next(&it))
        printf("  - %d\n", it.value.as_int);
}

void print_map_strings(argus_t argus, const char *name)
{
    if (!argus_is_set(&argus, name)) return; 
    
    printf("%s:\n", name);
    argus_map_it_t it = argus_map_it(&argus, name);
    while (argus_map_next(&it))
        printf("  %s = %s\n", it.key, it.value.as_string);
}

void print_map_bools(argus_t argus, const char *name)
{
    if (!argus_is_set(&argus, name)) return; 
    
    printf("%s:\n", name);
    argus_map_it_t it = argus_map_it(&argus, name);
    while (argus_map_next(&it))
        printf("  %s = %s\n", it.key, it.value.as_bool ? "true" : "false");
}

int main(int argc, char **argv)
{
    argus_t argus = argus_init(options, "config_tool", "2.0.0");
    argus.description = "Configuration management with collections and environment support";
    argus.env_prefix = "CONFIG";
    
    if (argus_parse(&argus, argc, argv) != ARGUS_SUCCESS)
        return 1;
    
    // Basic values
    const char *name = argus_get(&argus, "name").as_string;
    const char *host = argus_get(&argus, "host").as_string;
    int port = argus_get(&argus, "port").as_int;
    
    printf("=== Service Configuration ===\n");
    printf("Name: %s\n", name);
    printf("Host: %s:%d\n", host, port);
    
    if (argus_is_set(&argus, "contact"))
        printf("Contact: %s\n", argus_get(&argus, "contact").as_string);
    printf("\n");
    
    // Collections
    print_array_strings(argus, "tags");
    print_array_ints(argus, "ports");
    print_map_strings(argus, "env");
    print_map_bools(argus, "features");
    
    // Generate config file
    const char *output = "config.json";
    if (argus_is_set(&argus, "output")) {
        output = argus_get(&argus, "output").as_string;
    }
    
    FILE *config = fopen(output, "w");
    if (!config) {
        fprintf(stderr, "Error: Cannot create config file '%s'\n", output);
        return 1;
    }
    
    fprintf(config, "{\n");
    fprintf(config, "  \"name\": \"%s\",\n", name);
    fprintf(config, "  \"host\": \"%s\",\n", host);
    fprintf(config, "  \"port\": %d", port);
    
    if (argus_is_set(&argus, "contact")) {
        fprintf(config, ",\n  \"contact\": \"%s\"", argus_get(&argus, "contact").as_string);
    }
    
    // Add arrays
    if (argus_is_set(&argus, "tags")) {
        fprintf(config, ",\n  \"tags\": [");
        argus_array_it_t it = argus_array_it(&argus, "tags");
        bool first = true;
        while (argus_array_next(&it)) {
            if (!first) fprintf(config, ", ");
            fprintf(config, \"%s\", it.value.as_string);
            first = false;
        }
        fprintf(config, "]");
    }
    
    if (argus_is_set(&argus, "ports")) {
        fprintf(config, ",\n  \"ports\": [");
        argus_array_it_t it = argus_array_it(&argus, "ports");
        bool first = true;
        while (argus_array_next(&it)) {
            if (!first) fprintf(config, ", ");
            fprintf(config, \"%d\", it.value.as_int);
            first = false;
        }
        fprintf(config, "]");
    }
    
    // Add maps
    if (argus_is_set(&argus, "env")) {

```

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

### Deployment Tool Example with Argus (C)

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/features/collections.md

A C code example for a deployment tool using the Argus library. It parses options for target environments, service configurations, resource limits, and feature rollout percentages, then iterates through environments to deploy services.

```c
ARGUS_OPTIONS(
    options,
    HELP_OPTION(),
    
    // Deployment environments
    OPTION_ARRAY_STRING('e', "environments", HELP("Target environments"),
                        FLAGS(FLAG_UNIQUE | FLAG_SORTED),
                        VALIDATOR(V_COUNT(1, 5))),
    
    // Service configuration
    OPTION_MAP_STRING('s', "services", HELP("Service configurations")),
    
    // Resource limits
    OPTION_MAP_INT('r', "resources", HELP("Resource limits")),
    
    // Feature rollout percentages
    OPTION_MAP_FLOAT('f', "rollout", HELP("Feature rollout percentages"))
)

int main(int argc, char **argv)
{
    argus_t argus = argus_init(options, "deploy", "1.0.0");
    argus_parse(&argus, argc, argv);
    
    // Deploy to each environment
    argus_array_it_t env_it = argus_array_it(&argus, "environments");
    while (argus_array_next(&env_it)) {
        const char *env = env_it.value.as_string;
        printf("Deploying to %s...\n", env);
        
        // Apply resource limits for this environment
        char key_buffer[64];
        snprintf(key_buffer, sizeof(key_buffer), "%s_cpu", env);
        int cpu_limit = argus_map_get(&argus, "resources", key_buffer).as_int;
        if (cpu_limit) {
            printf("  CPU limit: %d\n", cpu_limit);
        }
        
        deploy_to_environment(env);
    }
    
    argus_free(&argus);
    return 0;
}
```

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

### Using pkg-config for Argus Flags

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/installation.md

These bash commands show how to use pkg-config to retrieve compiler and linker flags for the Argus library. This is useful for manual compilation or for integrating with build systems that support pkg-config.

```bash
# Get compiler flags
pkg-config --cflags argus

# Get linker flags  
pkg-config --libs argus

# Compile directly
gcc main.c $(pkg-config --cflags --libs argus) -o myapp
```

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

### Manual Build and Test Commands

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/appendices/contributing.md

Manual commands for configuring the Meson build, compiling, running tests with verbose output, and installing the project locally.

```bash
# Configure build
meson setup build -Dtests=true

# Compile
meson compile -C build

# Test with verbose output
meson test -C build -v

# Install locally
meson install -C build --destdir /tmp/argus-install
```

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

### Argus Basic Setup and Parsing

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/appendices/cheat-sheet.md

Demonstrates the fundamental structure for initializing, parsing arguments, and accessing values using the Argus library. Includes necessary headers and cleanup.

```c
#include <argus.h>

ARGUS_OPTIONS(options,
    HELP_OPTION(),
    VERSION_OPTION(),
    // Your options here
)

int main(int argc, char **argv)
{
    argus_t argus = argus_init(options, "program", "1.0.0");
    if (argus_parse(&argus, argc, argv) != ARGUS_SUCCESS)
        return 1;
    
    // Access values
    bool flag = argus_get(&argus, "flag").as_bool;
    
    argus_free(&argus);
    return 0;
}
```

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

### Build Tool Example with Argus (C)

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/features/collections.md

A C code example demonstrating the use of the Argus library for a build tool. It parses command-line options for build targets, compiler flags, environment overrides, and feature toggles, then iterates through them to perform build actions.

```c
ARGUS_OPTIONS(
    options,
    HELP_OPTION(),
    
    // Build targets
    OPTION_ARRAY_STRING('t', "targets", HELP("Build targets"),
                        FLAGS(FLAG_UNIQUE),
                        VALIDATOR(V_COUNT(1, 10))),
    
    // Compiler flags
    OPTION_ARRAY_STRING('f', "flags", HELP("Compiler flags")),
    
    // Environment overrides
    OPTION_MAP_STRING('D', "define", HELP("Preprocessor definitions")),
    
    // Feature toggles
    OPTION_MAP_BOOL('\0', "features", HELP("Feature flags"),
                    FLAGS(FLAG_SORTED_KEY))
)

int main(int argc, char **argv)
{
    argus_t argus = argus_init(options, "builder", "1.0.0");
    argus_parse(&argus, argc, argv);
    
    // Process build targets
    argus_array_it_t targets_it = argus_array_it(&argus, "targets");
    while (argus_array_next(&targets_it)) {
        printf("Building target: %s\n", targets_it.value.as_string);
        build_target(targets_it.value.as_string);
    }
    
    // Apply feature flags
    argus_map_it_t features_it = argus_map_it(&argus, "features");
    while (argus_map_next(&features_it)) {
        set_feature(features_it.key, features_it.value.as_bool);
    }
    
    argus_free(&argus);
    return 0;
}
```

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

### Git-Style Tool Examples

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/fundamentals/option-formats.md

Demonstrates command-line patterns for a Git-like tool, including subcommands and mixed option formats.

```bash
# Subcommands with options
./tool add --force file.txt
./tool commit --message="Fix bug" --author="John Doe"
./tool push --tags --dry-run origin main

# Mixed formats
./tool add -f file.txt
./tool commit -m "Fix bug" --author="John Doe"
```

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

### vcs CLI Add Command Help

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/examples/git-like.md

Provides help for the 'vcs add' subcommand, detailing its arguments and options for adding files to staging.

```APIDOC
vcs v1.0.0

Usage: vcs add [OPTIONS] [files]

Add files to staging

Arguments:
  [files]                - Files to add (optional)

Options:
  -h, --help             - Display this help message (exit)
  -A, --all              - Add all modified files
  -f, --force            - Force add ignored files
  -i, --include <STR,...> - Include specific patterns
```

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

### vcs CLI Main Help

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/examples/git-like.md

Displays the main help message for the vcs CLI tool, outlining global options and available commands.

```APIDOC
vcs v1.0.0

A simple version control system

Usage: vcs [OPTIONS] COMMAND

Options:
  -h, --help             - Display this help message (exit)
  -V, --version          - Display version information (exit)
  -v, --verbose          - Verbose output
  -C, --directory <DIR>  - Run in directory (default: ".")

Commands:
  add                    - Add files to staging
  commit                 - Record changes
  push                   - Push to remote
  status                 - Show working tree status

Run 'vcs COMMAND --help' for more information on a command.
```

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

### Argus Command Abbreviation Rules and Examples

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/features/subcommands.md

Explains Argus's support for Git-style command abbreviation, allowing users to type unique prefixes of command names. It details the rules for unambiguous matching and provides examples.

```c
ARGUS_OPTIONS(
    options,
    HELP_OPTION(),
    SUBCOMMAND("install", install_options, HELP("Install packages")),
    SUBCOMMAND("init", init_options, HELP("Initialize project")),
    SUBCOMMAND("status", status_options, HELP("Show status"))
)
```

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

### Argus Subcommand Program Structure Example

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/api-reference/overview.md

Illustrates how to build applications with subcommands using the Argus library. This example shows defining options for a subcommand, associating a handler function, and executing the appropriate subcommand logic.

```c
int add_command(argus_t *argus, void *data)
{
    const char *file = argus_get(argus, "file").as_string;
    bool force = argus_get(argus, "force").as_bool;
    // Command logic here
    return 0;
}

ARGUS_OPTIONS(add_options,
    HELP_OPTION(),
    OPTION_FLAG('f', "force", HELP("Force operation")),
    POSITIONAL_STRING("file", HELP("File to add"))
)

ARGUS_OPTIONS(options,
    HELP_OPTION(),
    OPTION_FLAG('v', "verbose", HELP("Verbose output")),
    SUBCOMMAND("add", add_options, HELP("Add files"), ACTION(add_command))
)

int main(int argc, char **argv)
{
    argus_t argus = argus_init(options, "tool", "1.0.0");
    
    if (argus_parse(&argus, argc, argv) != ARGUS_SUCCESS)
        return 1;
    
    if (argus_has_command(&argus))
        return argus_exec(&argus, NULL);

    argus_free(&argus);
    return 0;
}
```

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

### Build Tool Examples

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/fundamentals/option-formats.md

Shows advanced command-line usage for a build tool, incorporating array and map options, and option terminators.

```bash
# Array and map options
./builder --targets=lib,bin,tests --env=DEBUG=1,OPT=2
./builder -t lib,bin -t tests -e DEBUG=1 -e OPT=2

# With option terminator
./builder --verbose -- --enable-debug --target=all
```

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

### Argus Option Definition Example (C)

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/fundamentals/basic-options.md

This C code snippet demonstrates how to define various command-line option types using the Argus library's `ARGUS_OPTIONS` macro. It covers flags, string options with hints and validators, numeric options with ranges, boolean options, and positional arguments. The example also shows basic initialization, parsing, and cleanup of the Argus context.

```c
#include <argus.h>

ARGUS_OPTIONS(
    options,
    // Standard options (auto-generated help/version)
    HELP_OPTION(),
    VERSION_OPTION(),
    
    // Flags (boolean toggles - always false by default)
    OPTION_FLAG('v', "verbose", HELP("Enable verbose output")),
    OPTION_FLAG('f', "force", HELP("Force overwrite existing files")),
    OPTION_FLAG('\0', "dry-run", HELP("Show what would be done")),
    
    // String options
    OPTION_STRING('o', "output", HELP("Output directory"), 
                 DEFAULT("./output"), HINT("DIR")),
    OPTION_STRING('\0', "format", HELP("Output format"), 
                 DEFAULT("json"), VALIDATOR(V_CHOICE_STR("json", "xml", "csv"))),

    // Numeric options  
    OPTION_INT('t', "threads", HELP("Number of worker threads"), 
              DEFAULT(1), VALIDATOR(V_RANGE(1, 16))),
    OPTION_FLOAT('q', "quality", HELP("Compression quality"), 
                DEFAULT(0.8), VALIDATOR(V_RANGE(0.0, 1.0)), HINT("0.0-1.0")),
    
    // Boolean option (explicit value)
    OPTION_BOOL('b', "backup", HELP("Create backup before processing"), 
               DEFAULT(false)),
    
    // Positional arguments (required first, then optional)
    POSITIONAL_STRING("input", HELP("Input file to process")),
    POSITIONAL_INT("iterations", HELP("Number of processing iterations"), 
                  FLAGS(FLAG_OPTIONAL), DEFAULT(1)),
)

int main(int argc, char **argv)
{
    argus_t argus = argus_init(options, "comprehensive_tool", "1.0.0");
    argus.description = "A comprehensive example showing all option types";
    
    if (argus_parse(&argus, argc, argv) != ARGUS_SUCCESS)
        return 1;
    
    // Options are now parsed and ready to use
    // See "Accessing Values" guide for retrieval details
    
    printf("Tool configured successfully!\n");
    
    argus_free(&argus);
    return 0;
}

```

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

### Common Tasks with Justfile

Source: https://github.com/lucocozz/argus/blob/main/CONTRIBUTING.md

Examples of using the Justfile for common development tasks like building, testing, formatting, and quality checks.

```shell
# Build and compile
just build

# Run tests
just test

# Format code
just format

# Check code quality
just check
```

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

### Argus Library Context Sharing

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/examples/git-like.md

Illustrates defining and passing an application context structure to the `argus_exec` function for shared state.

```C
typedef struct {
    bool verbose;
    const char *repo_path;
} app_context_t;

// Pass to argus_exec()
argus_exec(&argus, &context);
```

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

### Quick Start: Clone, Build, and Test Argus

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/appendices/contributing.md

Initial steps to clone the Argus repository, set up the build environment using Meson, compile the project, and run the test suite.

```bash
git clone https://github.com/lucocozz/argus.git
cd argus
meson setup build
meson compile -C build
meson test -C build
```

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

### Basic Help Setup with Argus

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/fundamentals/help-and-errors.md

Demonstrates how to set up automatic `--help` and `-h` support in Argus by including `HELP_OPTION()` in option definitions. Shows initialization, parsing, and cleanup.

```c
ARGUS_OPTIONS(
    options,
    HELP_OPTION(),                    // Automatic --help/-h
    VERSION_OPTION(),                 // Automatic --version/-V
    
    OPTION_FLAG('v', "verbose", HELP("Enable verbose output")),
    OPTION_STRING('o', "output", HELP("Output file"), DEFAULT("result.txt")),
    OPTION_INT('p', "port", HELP("Port number"), DEFAULT(8080),
               VALIDATOR(V_RANGE(1, 65535))),
    
    POSITIONAL_STRING("input", HELP("Input file to process")),
)

int main(int argc, char **argv)
{
    argus_t argus = argus_init(options, "my_tool", "1.0.0");
    argus.description = "A simple file processing tool";
    
    if (argus_parse(&argus, argc, argv) != ARGUS_SUCCESS)
        return 1;
    
    // Your app logic here
    
    argus_free(&argus);
    return 0;
}
```

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

### Build Argus Project

Source: https://github.com/lucocozz/argus/blob/main/CONTRIBUTING.md

Instructions to set up the build environment and compile the argus project using Meson.

```bash
meson setup .build
meson compile -C .build
```

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

### Argus Environment Setup for Web App

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/features/environment.md

Shows how to set environment variables for the web application to override default configurations. Includes examples for production settings and running the application.

```bash
# Production environment
export WEBAPP_HOST=0.0.0.0
export WEBAPP_PORT=443
export DATABASE_URL=postgres://prod-db/webapp
export WEBAPP_LOG_LEVEL=warn
export WEBAPP_WORKER_THREADS=8
export WEBAPP_SSL_VERIFY=true

./webapp
```

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

### Troubleshoot Library Not Found Errors

Source: https://github.com/lucocozz/argus/blob/main/docs/docs/getting-started/installation.md

If your linker cannot find the Argus library, you might need to specify the library path. These bash commands show how to add the library directory to LD_LIBRARY_PATH or specify it directly during compilation.

```bash
# Add library path
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
sudo ldconfig

# Or specify path explicitly
gcc main.c -L/usr/local/lib -largus -o myapp
```