Configuration

args.zig provides flexible configuration options to customize parser behavior.

TIP

Use preset configs like args.Config.default(), args.Config.minimal(), or args.Config.ci() for quick setup. Override individual fields as needed.

Config Struct

const args = @import("args");

const Config = struct {
    // Display options
    use_colors: bool = true,
    colors: ?args.ColorTheme = null,
    help_line_width: usize = 80,
    help_indent: usize = 24,
    show_defaults: bool = true,
    show_env_vars: bool = true,
    program_name: ?[]const u8 = null,
    
    // Parsing behavior
    exit_on_error: bool = true,
    parsing_mode: ParsingMode = .strict,
    allow_short_clusters: bool = true,
    allow_inline_values: bool = true,
    allow_interspersed: bool = true,
    allow_negated_flags: bool = true,
    allow_brackets: bool = true,
    case_sensitive: bool = true,
    env_prefix: ?[]const u8 = null,
    silent_errors: bool = false, // Suppress error output (for tests)
    suggest_closest: bool = true,
    suggestion_max_distance: usize = 3,
    suggest_builtin_commands: bool = true,
    suggest_subcommands: bool = true,
    error_prefix: []const u8 = "Error",
    warning_prefix: []const u8 = "Warning",
    unknown_option_hint: ?[]const u8 = null,
    unknown_subcommand_hint: ?[]const u8 = null,
    unknown_option_message: ?[]const u8 = null,
    unknown_subcommand_message: ?[]const u8 = null,
    
    // Global Application Metadata (centralized defaults)
    app_name: ?[]const u8 = null,
    app_version: ?[]const u8 = null,
    app_description: ?[]const u8 = null,
    app_epilog: ?[]const u8 = null,
    app_author: ?[]const u8 = null,
};

Configuration Options

Display Options

Option	Default	Description
use_colors	true	Use ANSI colors in help output
colors	null	Optional theme override for colored output
help_line_width	80	Maximum line width for help text
help_indent	24	Indentation for option descriptions
show_defaults	true	Show default values in help
show_env_vars	true	Show environment variable fallbacks
program_name	null	Override program name displayed in help

Parsing Behavior

Option	Default	Description
exit_on_error	true	Exit on parse errors
parsing_mode	.strict	How to handle unknown arguments
allow_short_clusters	true	Allow -abc as -a -b -c
allow_inline_values	true	Allow --opt=value format
allow_interspersed	true	Allow options after positionals
allow_negated_flags	true	Allow --no-flag for boolean long options
allow_brackets	true	Allow bracket-delimited list values {a,b}, [a,b], <a,b>
case_sensitive	true	Case-sensitive option matching
env_prefix	null	Prefix for environment variables
silent_errors	false	Suppress error/warning prints (for tests)
suggest_closest	true	Show spelling suggestions for close matches
suggestion_max_distance	3	Max edit distance for suggestion matching
suggest_builtin_commands	true	Include --help and --version in unknown-option suggestions
suggest_subcommands	true	Enable closest-match suggestions for unknown subcommands
error_prefix	"Error"	Prefix used for parse error output
warning_prefix	"Warning"	Prefix used for warning output
unknown_option_hint	null	Custom hint text printed for unknown options
unknown_subcommand_hint	null	Custom hint text printed for unknown subcommands
unknown_option_message	null	Override default unknown-option error text
unknown_subcommand_message	null	Override default unknown-subcommand error text

Application Metadata (Global Defaults)

Option	Default	Description
app_name	null	Default application name for all parsers
app_version	null	Default application version
app_description	null	Default application description
app_epilog	null	Default epilog text (shown after help)
app_author	null	Application author information

Help Formatting Notes

• program_name overrides the executable name displayed in generated help usage lines.
• help_indent controls the alignment column used for option descriptions.
• help_line_width is used to wrap long option descriptions and metadata blocks.
• app_author is printed in help output when set.

Color Themes

args.zig ships with a standard palette and a brighter preset. You can override colors globally:

const args = @import("args");

args.initConfig(.{
    .use_colors = true,
    .colors = args.ColorTheme.bright(),
});

To fully disable color codes, set use_colors = false (all theme fields are ignored).

Configuration Presets

Default Configuration

All features enabled, strict parsing, and standard theme:

var parser = try args.ArgumentParser.init(allocator, .{
    .name = "myapp",
    .config = args.Config.default(),
});

Minimal Configuration

No colors, no exit on error, and silent:

var parser = try args.ArgumentParser.init(allocator, .{
    .name = "myapp",
    .config = args.Config.minimal(),
});

Verbose Configuration

Extra debugging information showing all defaults and env vars:

var parser = try args.ArgumentParser.init(allocator, .{
    .name = "myapp",
    .config = args.Config.verbose(),
});

Colorful Configuration

Forces colorful output with a bright preconfigured color theme:

var parser = try args.ArgumentParser.init(allocator, .{
    .name = "myapp",
    .config = args.Config.colorful(),
});

Testing Configuration

Specifically configured for unit tests. Suppresses errors and disables exit behavior:

var parser = try args.ArgumentParser.init(allocator, .{
    .name = "myapp",
    .config = args.Config.testing(),
});

CI Configuration

Strict mode, exit on error, and spelling suggestions, but disables all color codes (pipe-safe):

var parser = try args.ArgumentParser.init(allocator, .{
    .name = "myapp",
    .config = args.Config.ci(),
});

Production Configuration

Enforces color themes, spelling suggestions, and exit on error:

var parser = try args.ArgumentParser.init(allocator, .{
    .name = "myapp",
    .config = args.Config.production(),
});

Custom Configuration

var parser = try args.ArgumentParser.init(allocator, .{
    .name = "myapp",
    .config = .{
        .use_colors = true,
        .show_defaults = true,
        .exit_on_error = false,
    },
});

Global Configuration

Set configuration globally before creating parsers. This is ideal for centralizing application metadata:

// Initialize global config with app metadata
args.initConfig(.{
    .app_name = "myapp",
    .app_version = "1.0.0",
    .app_description = "My amazing application",
    .app_author = "Your Name",
    .use_colors = true,
});

// Parsers automatically inherit these values
var parser = try args.ArgumentParser.init(allocator, .{
    .name = "", // Uses app_name from global config
});

// Or use parseInto which also respects global config
const Config = struct { verbose: bool };
var parsed = try args.parseInto(allocator, Config, .{
    .name = "", // Uses app_name from global config
}, null, init);

Benefits of Global Configuration

• Centralized metadata: Define app name, version, description once
• Consistent behavior: All parsers share the same settings
• Override when needed: Per-parser config takes precedence

Parsing Modes

Strict Mode (default)

Errors on unknown options:

.config = .{ .parsing_mode = .strict }

Permissive Mode

Collects unknown options without error:

.config = .{ .parsing_mode = .permissive }

Ignore Unknown Mode

Silently ignores unknown options:

.config = .{ .parsing_mode = .ignore_unknown }

Advanced Behavior Flags

Disable Short Clusters

When disabled, -abc is treated as a positional value instead of -a -b -c.

.config = .{ .allow_short_clusters = false }

Disable Inline Values

When disabled, --output=file.txt and -o=file.txt are rejected as invalid format.

.config = .{ .allow_inline_values = false }

Disable Interspersed Options

When disabled, all values after the first positional are treated as positional.

.config = .{ .allow_interspersed = false }

Case-Insensitive Matching

When disabled, long option lookup and choices / expect value checks become ASCII case-insensitive.

.config = .{ .case_sensitive = false }
// --VERBOSE matches --verbose
// --level DEBUG matches choices = { "debug", ... }

Disable Negated Long Flags

When disabled, --no-<name> is treated as unknown.

.config = .{ .allow_negated_flags = false }

Configuration Validation & Auto-Resolution

NOTE

args.zig includes a built-in static analysis engine for configuration to detect conflicting or redundant flags at runtime and auto-resolve them safely.

Config Warnings & Severity

pub const ConfigWarningSeverity = enum {
    note,
    warning,
    @"error",
};

pub const ConfigWarning = struct {
    field: []const u8,
    message: []const u8,
    severity: ConfigWarningSeverity = .warning,
    auto_resolved: bool = false,
};

Validate Config Combinations

Call validate to check a configuration struct for inconsistent options:

var warn_buf: [16]args.config.ConfigWarning = undefined;
const count = config.validate(&warn_buf);

Auto-Resolve Conflicts

You can obtain a safe, auto-resolved copy of any configuration by calling autoResolve():

const conflicting_config = args.Config{
    .parsing_mode = .permissive,
    .exit_on_error = true, // Conflict: exit_on_error has no effect in permissive
};

const clean_config = conflicting_config.autoResolve();
// clean_config.exit_on_error is now false

Configuration Utility Methods

Config Merging

You can shallow-merge two configurations using .merge(). Fields from the patch override default fields of the base:

const base = args.Config.default();
const patch = args.Config{ .use_colors = false };

const merged = base.merge(patch);
// merged.use_colors is now false, while other fields remain default

Config Snapshots

Generate a perfect duplicate snapshot of the current configuration:

const copy = cfg.snapshot();

Global Auto-Resolution & Utilities

Use these global functions to manage shared behavior across multiple parsers:

Auto-Resolving Initialization

Initialize the global configuration, print colored warning messages to stderr for any conflicts, and apply resolved changes:

args.initConfigAutoResolve(.{
    .parsing_mode = .permissive,
    .exit_on_error = true,
});

Set Config Field Globally

Directly mutate a single global configuration value:

args.setConfigValue("use_colors", false);

Validate Global Config

Validate the currently active global configuration at runtime:

var buf: [16]args.config.ConfigWarning = undefined;
const count = args.validateConfig(&buf);