Options builder API for flexible command-line option configuration. More...

Data Structures
struct	option_metadata_t
	Metadata for shell completion generation. More...

struct	option_descriptor_t
	Option descriptor. More...

struct	usage_descriptor_t
	Usage line descriptor for programmatic USAGE generation. More...

struct	example_descriptor_t
	Example descriptor for programmatic EXAMPLES generation. More...

struct	help_mode_descriptor_t
	Mode descriptor for programmatic MODES generation (for help output) More...

struct	option_dependency_t
	Option dependency. More...

struct	positional_arg_descriptor_t
	Positional argument descriptor. More...

struct	custom_section_descriptor_t
	Custom help section descriptor. More...

struct	options_config_t
	Options configuration. More...

struct	options_builder_t
	Options builder. More...

Enumerations
enum	option_type_t { OPTION_TYPE_BOOL , OPTION_TYPE_INT , OPTION_TYPE_STRING , OPTION_TYPE_DOUBLE , OPTION_TYPE_CALLBACK , OPTION_TYPE_ACTION }
	Option value types. More...

enum	option_input_type_t { OPTION_INPUT_NONE , OPTION_INPUT_ENUM , OPTION_INPUT_NUMERIC , OPTION_INPUT_STRING , OPTION_INPUT_FILEPATH , OPTION_INPUT_CHOICE }
	Completion input type for smart shell completions. More...

enum	dependency_type_t { DEPENDENCY_REQUIRES , DEPENDENCY_CONFLICTS , DEPENDENCY_IMPLIES }
	Option dependency types. More...

Functions
options_builder_t *	options_builder_create (size_t struct_size)
	Create empty options builder.

options_builder_t *	options_builder_from_preset (const options_config_t *preset)
	Create builder from preset config.

void	options_builder_destroy (options_builder_t *builder)
	Free options builder.

options_config_t *	options_builder_build (options_builder_t *builder)
	Build immutable options config.

void	options_config_destroy (options_config_t *config)
	Free options config.

void	options_builder_add_bool (options_builder_t builder, const char long_name, char short_name, size_t offset, bool default_value, const char help_text, const char group, bool required, const char *env_var_name)
	Add boolean flag option.

void	options_builder_add_int (options_builder_t builder, const char long_name, char short_name, size_t offset, int default_value, const char help_text, const char group, bool required, const char env_var_name, bool(validate)(const void options_struct, char *error_msg))
	Add integer option.

void	options_builder_add_int_with_metadata (options_builder_t builder, const char long_name, char short_name, size_t offset, int default_value, const char help_text, const char group, bool required, const char env_var_name, bool(validate)(const void options_struct, char error_msg), const option_metadata_t metadata)
	Add integer option with metadata (for numeric ranges and examples)

void	options_builder_add_string (options_builder_t builder, const char long_name, char short_name, size_t offset, const char default_value, const char help_text, const char group, bool required, const char env_var_name, bool(validate)(const void options_struct, char **error_msg))
	Add string option.

void	options_builder_add_double (options_builder_t builder, const char long_name, char short_name, size_t offset, double default_value, const char help_text, const char group, bool required, const char env_var_name, bool(validate)(const void options_struct, char *error_msg), bool optional_arg)
	Add double/float option.

void	options_builder_add_double_with_metadata (options_builder_t builder, const char long_name, char short_name, size_t offset, double default_value, const char help_text, const char group, bool required, const char env_var_name, bool(validate)(const void options_struct, char error_msg), const option_metadata_t metadata, bool optional_arg)

void	options_builder_add_callback (options_builder_t builder, const char long_name, char short_name, size_t offset, const void default_value, size_t value_size, bool(parse_fn)(const char arg, void dest, char *error_msg), const char help_text, const char group, bool required, const char env_var_name)
	Add option with custom callback parser.

void	options_builder_add_callback_optional (options_builder_t builder, const char long_name, char short_name, size_t offset, const void default_value, size_t value_size, bool(parse_fn)(const char arg, void dest, char *error_msg), const char help_text, const char group, bool required, const char env_var_name, bool optional_arg)
	Add option with custom callback parser that supports optional arguments.

void	options_builder_add_callback_with_metadata (options_builder_t builder, const char long_name, char short_name, size_t offset, const void default_value, size_t value_size, bool(parse_fn)(const char arg, void dest, char *error_msg), const char help_text, const char group, bool required, const char env_var_name, bool optional_arg, const option_metadata_t *metadata)
	Add callback option with full metadata (for enums, ranges, examples, etc.)

void	options_builder_add_action (options_builder_t builder, const char long_name, char short_name, void(action_fn)(void), const char help_text, const char *group)
	Add action option (executes action and may exit)

void	options_builder_set_mode_bitmask (options_builder_t *builder, option_mode_bitmask_t mode_bitmask)
	Set mode bitmask on the last added option descriptor.

void	options_builder_set_arg_placeholder (options_builder_t builder, const char arg_placeholder)
	Set custom argument placeholder on the last added option descriptor.

void	options_builder_set_enum_values (options_builder_t builder, const char option_name, const char values, const char descriptions)
	Set enum values with descriptions for an option.

void	options_builder_set_numeric_range (options_builder_t builder, const char option_name, int min, int max, int step)
	Set numeric range for an option.

void	options_builder_set_examples (options_builder_t builder, const char option_name, const char **examples)
	Set example values for an option.

void	options_builder_set_input_type (options_builder_t builder, const char option_name, option_input_type_t input_type)
	Set input type for an option.

void	options_builder_mark_as_list (options_builder_t builder, const char option_name)
	Mark option as accepting multiple values.

void	options_builder_set_default_value_display (options_builder_t builder, const char option_name, const char *default_value)
	Set default value string in metadata.

void	options_builder_add_descriptor (options_builder_t builder, const option_descriptor_t descriptor)
	Add full option descriptor (advanced)

void	options_builder_add_dependency_requires (options_builder_t builder, const char option_name, const char depends_on, const char error_message)
	Add dependency: if option_name is set, depends_on must be set.

void	options_builder_add_dependency_conflicts (options_builder_t builder, const char option_name, const char conflicts_with, const char error_message)
	Add anti-dependency: if option_name is set, conflicts_with must NOT be set.

void	options_builder_add_dependency_implies (options_builder_t builder, const char option_name, const char implies, const char error_message)
	Add implication: if option_name is set, implies defaults to true.

void	options_builder_add_dependency (options_builder_t builder, const option_dependency_t dependency)
	Add full dependency (advanced)

void	options_builder_mark_binary_only (options_builder_t builder, const char option_name)
	Mark an option as binary-level only (hide from mode-specific help)

void	options_builder_add_positional (options_builder_t builder, const char name, const char help_text, bool required, const char section_heading, const char *examples, size_t num_examples, option_mode_bitmask_t mode_bitmask, int(parse_fn)(const char arg, void config, char remaining, int num_remaining, char error_msg))
	Add positional argument descriptor.

asciichat_error_t	options_config_parse_positional (const options_config_t config, int remaining_argc, char remaining_argv, void options_struct)
	Parse positional arguments.

void	options_builder_add_usage (options_builder_t builder, const char mode, const char positional, bool show_options, const char description)
	Add usage line descriptor.

void	options_builder_add_example (options_builder_t builder, uint32_t mode_bitmask, const char args, const char *description, bool owns_args)
	Add example descriptor.

void	options_builder_add_example_utility (options_builder_t builder, uint32_t mode_bitmask, const char args, const char *description, bool is_utility_command)
	Add an example with utility command support.

void	options_builder_add_mode (options_builder_t builder, const char name, const char *description)
	Add mode descriptor.

void	options_builder_add_custom_section (options_builder_t builder, const char heading, const char *content, option_mode_bitmask_t mode_bitmask)
	Add a custom help section.

options_config_t *	options_preset_unified (const char program_name, const char description)
	Get binary-level options preset.

asciichat_error_t	options_config_set_defaults (const options_config_t config, void options_struct)
	Set default values in options struct.

asciichat_error_t	options_config_parse (const options_config_t config, int argc, char argv, void options_struct, option_mode_bitmask_t detected_mode, int remaining_argc, char **remaining_argv)
	Parse command-line arguments.

asciichat_error_t	options_config_validate (const options_config_t config, const void options_struct, char **error_message)
	Validate options struct.

int	options_config_calculate_max_col_width (const options_config_t *config)
	Calculate global max column width for help output alignment.

void	options_config_print_usage (const options_config_t config, FILE stream)
	Print usage/help text.

void	options_config_print_usage_section (const options_config_t config, FILE stream)
	Print only the USAGE section.

void	options_config_print_options_sections_with_width (const options_config_t config, FILE stream, int max_col_width, asciichat_mode_t mode)
	Print everything except the USAGE section.

void	options_config_print_options_sections (const options_config_t config, FILE stream, asciichat_mode_t mode)
	Print everything except the USAGE section (backward compatibility)

void	options_print_help_for_mode (const options_config_t config, asciichat_mode_t mode, const char program_name, const char description, FILE desc)
	Print help for a specific mode or binary level (unified function)

void	options_struct_destroy (const options_config_t config, void options_struct)
	Clean up memory owned by options struct.

const char *	options_get_type_placeholder (option_type_t type)
	Get placeholder string for option type.

int	options_format_default_value (option_type_t type, const void default_value, char buf, size_t bufsize)
	Format option default value to string.

const char *	find_similar_option_with_mode (const char unknown_opt, const options_config_t config, option_mode_bitmask_t current_mode_bitmask)
	Find similar option across all modes and suggest with mode information.

Detailed Description

Options builder API for flexible command-line option configuration.

This module provides a builder pattern for constructing option configurations that can be used by library consumers to create custom tools based on ascii-chat modes or build entirely custom option sets from scratch.

Integration with Registry and RCU

The builder pattern works together with:

Registry (registry.h): Centralized option definitions. Use options_registry_add_all_to_builder() to populate builder with registered options.
RCU Thread-Safety (rcu.h): Lock-free access to parsed options. Built configs are used by options_init() to parse and publish to RCU.
Mode Bitmasks: Each option includes a mode_bitmask indicating which modes it applies to (SERVER, CLIENT, MIRROR, DISCOVERY_SVC, BINARY, etc.).

Features:

Three-tier parsing (binary → mode → mode-specific)
Required fields with environment variable fallbacks
Option dependencies (REQUIRES, CONFLICTS, IMPLIES)
Cross-field validation (validators receive full options struct)
Automatic string memory management (auto-strdup, cleanup)
Grouped help output with semantic coloring
Mode-aware option filtering and applicability
Smart shell completion metadata (enums, ranges, examples, filepath hints)
Preset configs for server/client/mirror/acds modes

Builder Pattern Workflow

CREATE BUILDER
   ↓
ADD OPTIONS (with mode bitmasks)
   ↓
ADD DEPENDENCIES (REQUIRES, CONFLICTS, IMPLIES)
   ↓
BUILD IMMUTABLE CONFIG
   ↓
PARSE COMMAND LINE (options are mode-filtered)
   ↓
VALIDATE (required, dependencies, custom validators)
   ↓
PUBLISH TO RCU (lock-free thread-safe access)

Builder Usage Patterns

Pattern 1: Start from Registry

// Use registered options as base
options_builder_t *builder = options_builder_create(sizeof(options_t));
options_registry_add_all_to_builder(builder);  // Add all registered options
options_config_t *config = options_builder_build(builder);

Pattern 2: Start from Preset

// Start with unified preset (standard multi-mode setup)
options_config_t *preset = options_preset_unified("ascii-chat", "Terminal video chat");
options_builder_t *builder = options_builder_from_preset(preset);
// Add custom options or modify
options_config_t *config = options_builder_build(builder);

Pattern 3: Custom Builder from Scratch

// Build entirely custom config
options_builder_t *builder = options_builder_create(sizeof(my_options_t));
options_builder_add_bool(builder, "verbose", 'v', offsetof(my_options_t, verbose), ...);
options_builder_add_int(builder, "port", 'p', offsetof(my_options_t, port), ...);
options_builder_set_mode_bitmask(builder, OPTION_MODE_SERVER);  // For last added option
options_config_t *config = options_builder_build(builder);

Mode Bitmask System

Options are filtered based on mode using bitmasks:

OPTION_MODE_BINARY: Parsed before mode detection (–help, –version, –log-file)
OPTION_MODE_SERVER: Server-only options
OPTION_MODE_CLIENT: Client-only options
OPTION_MODE_MIRROR: Mirror mode options
OPTION_MODE_DISCOVERY_SVC: Discovery service options
OPTION_MODE_ALL: Available in all modes

Each option's mode_bitmask field controls where it appears in:

Help output (mode-specific or binary-level)
Shell completions
Parsing (only options matching detected mode are parsed)

Setting Mode Bitmask:

options_builder_add_int(builder, "max-clients", 'm', ...);

options_builder_set_mode_bitmask(builder, OPTION_MODE_SERVER); // Server-only option

Option Types and Parsing

OPTION_TYPE_BOOL: Boolean flag (–flag, no value)
OPTION_TYPE_INT: Integer with validation and optional range
OPTION_TYPE_STRING: String (auto-duplicated, auto-freed)
OPTION_TYPE_DOUBLE: Floating point with optional range
OPTION_TYPE_CALLBACK: Custom parser for complex types
OPTION_TYPE_ACTION: Action that executes immediately (–version, –help)

Option Dependencies

Enforce relationships between options during validation:

DEPENDENCY_REQUIRES: If A is set, B must be set (e.g., –tls requires –cert)
DEPENDENCY_CONFLICTS: If A is set, B must NOT be set (e.g., –no-crypto conflicts with –key-file)
DEPENDENCY_IMPLIES: If A is set, B defaults to true (e.g., –tls implies –secure)

Adding Dependencies:

options_builder_add_dependency_requires(builder, "tls-cert", "tls-enabled", NULL);
options_builder_add_dependency_conflicts(builder, "no-crypto", "key-file", NULL);
options_builder_add_dependency_implies(builder, "secure", "tls-enabled", NULL);

RCU Integration

After building and parsing, options are published to RCU for thread-safe access:

options_config_t *config = options_builder_build(builder);
options_t opts = options_t_new();
options_config_parse(config, argc, argv, &opts, MODE_DETECTION_RESULT, ...);
options_config_validate(config, &opts, NULL);
 
// Publish to RCU before spawning worker threads
options_state_init();
options_state_set(&opts);
 
// Now worker threads can safely read options lock-free
const options_t *current_opts = options_get();
int port = current_opts->port;  // No locks needed!

See also: registry.h - Central registry of all option definitions; rcu.h - Thread-safe RCU-based access to published Options Module; options.h - Unified Options Module parsing system (uses builder internally)

Author: Zachary Fogg me@zf.nosp@m.o.gg

Date: December 2025

Definition in file builder.h.

Enumeration Type Documentation

◆ dependency_type_t

enum dependency_type_t

Option dependency types.

Defines relationships between options.

Enumerator
DEPENDENCY_REQUIRES	If A is set, B must be set.
DEPENDENCY_CONFLICTS	If A is set, B must NOT be set.
DEPENDENCY_IMPLIES	If A is set, B defaults to true/enabled.

Definition at line 228 of file builder.h.

             {
  DEPENDENCY_REQUIRES,  
  DEPENDENCY_CONFLICTS, 
  DEPENDENCY_IMPLIES    
} dependency_type_t;

◆ option_input_type_t

enum option_input_type_t

Completion input type for smart shell completions.

Specifies the kind of input an option expects, used to generate better completions with value suggestions, ranges, and examples.

Enumerator
OPTION_INPUT_NONE	No input (boolean flag)
OPTION_INPUT_ENUM	Choose from fixed set of enum values.
OPTION_INPUT_NUMERIC	Numeric value with optional min/max/step.
OPTION_INPUT_STRING	Free-form text input.
OPTION_INPUT_FILEPATH	File path completion.
OPTION_INPUT_CHOICE	Dynamic choice (e.g., from system)

Definition at line 176 of file builder.h.

             {
  OPTION_INPUT_NONE,     
  OPTION_INPUT_ENUM,     
  OPTION_INPUT_NUMERIC,  
  OPTION_INPUT_STRING,   
  OPTION_INPUT_FILEPATH, 
  OPTION_INPUT_CHOICE    
} option_input_type_t;

◆ option_type_t

enum option_type_t

Option value types.

Defines the type of value an option accepts.

Enumerator
OPTION_TYPE_BOOL	Boolean flag (–flag, no value)
OPTION_TYPE_INT	Integer value (–count 42)
OPTION_TYPE_STRING	String value (–name foo)
OPTION_TYPE_DOUBLE	Floating point (–ratio 1.5)
OPTION_TYPE_CALLBACK	Custom parser function.
OPTION_TYPE_ACTION	Action that executes and may exit (–list-webcams, etc.)

Definition at line 161 of file builder.h.

             {
  OPTION_TYPE_BOOL,     
  OPTION_TYPE_INT,      
  OPTION_TYPE_STRING,   
  OPTION_TYPE_DOUBLE,   
  OPTION_TYPE_CALLBACK, 
  OPTION_TYPE_ACTION    
} option_type_t;

Function Documentation

◆ find_similar_option_with_mode()

const char * find_similar_option_with_mode	(	const char *	unknown_opt,
		const options_config_t *	config,
		option_mode_bitmask_t	current_mode_bitmask
	)

Find similar option across all modes and suggest with mode information.

Searches for options matching the unknown option using Levenshtein distance. If found and available in a different mode, suggests it with mode information. For discovery mode, displays it as "the default mode (ascii-chat)".

Parameters

unknown_opt	Unknown option name (with – prefix)
config	Options configuration (has all descriptors across modes)
current_mode_bitmask	Current mode bitmask for filtering

Returns: Formatted suggestion with mode info, or NULL if no good match

Example:

const char *suggestion = find_similar_option_with_mode("--prot", config, current_mode);
if (suggestion) {
    log_error("%s", suggestion);  // "Did you mean '--port' (available in server mode)?"
}

Definition at line 108 of file options/common.c.

                                                                                      {
  if (!unknown_opt || !config) {
    return NULL;
  }
 
  // Extract the option name without dashes
  const char *opt_name = unknown_opt;
  if (strncmp(opt_name, "--", 2) == 0) {
    opt_name += 2;
  } else if (strncmp(opt_name, "-", 1) == 0) {
    opt_name += 1;
  } else {
    return NULL; // Not an option format
  }
 
  const option_descriptor_t *best_match = NULL;
  size_t best_distance = SIZE_MAX;
 
  // Search through all descriptors
  for (size_t i = 0; i < config->num_descriptors; i++) {
    const option_descriptor_t *desc = &config->descriptors[i];
    if (!desc->long_name)
      continue;
 
    // Calculate distance to the long name
    size_t dist = levenshtein(opt_name, desc->long_name);
    if (dist < best_distance) {
      best_distance = dist;
      best_match = desc;
    }
  }
 
  // Only suggest if the distance is within our threshold
  if (best_distance > LEVENSHTEIN_SUGGESTION_THRESHOLD || !best_match) {
    return NULL;
  }
 
  // Check if the option is not available in current mode
  bool available_in_current_mode = (best_match->mode_bitmask & current_mode_bitmask) != 0;
 
  static char suggestion[256];
  if (available_in_current_mode) {
    // Option exists but user typed it wrong - just suggest the correct spelling
    safe_snprintf(suggestion, sizeof(suggestion), "Did you mean '--%s'?", best_match->long_name);
  } else {
    // Option exists but in a different mode - show all available modes
    const char *modes_str = format_available_modes(best_match->mode_bitmask);
    safe_snprintf(suggestion, sizeof(suggestion), "Did you mean '--%s' (available in modes: %s)?",
                  best_match->long_name, modes_str);
  }
 
  return suggestion;
}

References options_config_t::descriptors, format_available_modes(), levenshtein(), LEVENSHTEIN_SUGGESTION_THRESHOLD, option_descriptor_t::long_name, option_descriptor_t::mode_bitmask, options_config_t::num_descriptors, and safe_snprintf().

◆ options_builder_add_action()

void options_builder_add_action	(	options_builder_t *	builder,
		const char *	long_name,
		char	short_name,
		void(*)(void)	action_fn,
		const char *	help_text,
		const char *	group
	)

Add action option (executes action and may exit)

Action options execute a callback function when encountered during parsing. The callback may exit the program (e.g., –list-webcams, –version).

Parameters

builder	Builder to add to
long_name	Long option name
short_name	Short option char (or '\0')
action_fn	Action callback to execute
help_text	Help description
group	Group name for help

Definition at line 943 of file builder.c.

                                                                                                   {
  ensure_descriptor_capacity(builder);
 
  option_descriptor_t desc = {.long_name = long_name,
                              .short_name = short_name,
                              .type = OPTION_TYPE_ACTION,
                              .offset = 0, // Actions don't store values
                              .help_text = help_text,
                              .group = group,
                              .default_value = NULL,
                              .required = false, // Actions are never required
                              .env_var_name = NULL,
                              .validate = NULL,
                              .parse_fn = NULL,
                              .action_fn = action_fn,
                              .owns_memory = false,
                              .hide_from_mode_help = false,
                              .hide_from_binary_help = false,
                              .mode_bitmask = OPTION_MODE_NONE};
 
  builder->descriptors[builder->num_descriptors++] = desc;
 
  // Set hide_from_binary_help after adding (so we can check the option name)
  if (strcmp(long_name, "create-man-page") == 0) {
    // Always hide from help and man page (this is a development tool)
    builder->descriptors[builder->num_descriptors - 1].hide_from_binary_help = true;
  }
}

References options_builder_t::descriptors, ensure_descriptor_capacity(), option_descriptor_t::hide_from_binary_help, option_descriptor_t::long_name, options_builder_t::num_descriptors, OPTION_MODE_NONE, and OPTION_TYPE_ACTION.

Referenced by options_registry_add_all_to_builder().

◆ options_builder_add_bool()

void options_builder_add_bool	(	options_builder_t *	builder,
		const char *	long_name,
		char	short_name,
		size_t	offset,
		bool	default_value,
		const char *	help_text,
		const char *	group,
		bool	required,
		const char *	env_var_name
	)

Add boolean flag option.

Parameters

builder	Builder to add to
long_name	Long option name (e.g., "verbose")
short_name	Short option char (e.g., 'v', or '\0' if none)
offset	offsetof(struct, field)
default_value	Default value
help_text	Help description
group	Group name for help (e.g., "OUTPUT OPTIONS")
required	If true, option must be provided
env_var_name	Environment variable fallback (or NULL)

Definition at line 657 of file builder.c.

                                                        {
  ensure_descriptor_capacity(builder);
 
  static bool default_vals[2] = {false, true};
 
  option_descriptor_t desc = {.long_name = long_name,
                              .short_name = short_name,
                              .type = OPTION_TYPE_BOOL,
                              .offset = offset,
                              .help_text = help_text,
                              .group = group,
                              .default_value = &default_vals[default_value ? 1 : 0],
                              .required = required,
                              .env_var_name = env_var_name,
                              .mode_bitmask = OPTION_MODE_NONE,
                              .validate = NULL,
                              .parse_fn = NULL,
                              .owns_memory = false};
 
  builder->descriptors[builder->num_descriptors++] = desc;
}

References options_builder_t::descriptors, ensure_descriptor_capacity(), option_descriptor_t::long_name, options_builder_t::num_descriptors, OPTION_MODE_NONE, and OPTION_TYPE_BOOL.

Referenced by options_registry_add_all_to_builder().

◆ options_builder_add_callback()

void options_builder_add_callback	(	options_builder_t *	builder,
		const char *	long_name,
		char	short_name,
		size_t	offset,
		const void *	default_value,
		size_t	value_size,
		bool()(const char arg, void dest, char *error_msg)	parse_fn,
		const char *	help_text,
		const char *	group,
		bool	required,
		const char *	env_var_name
	)

Add option with custom callback parser.

Parameters

builder	Builder to add to
long_name	Long option name
short_name	Short option char (or '\0')
offset	offsetof(struct, field)
default_value	Pointer to default value (or NULL)
value_size	sizeof(field_type)
parse_fn	Custom parser function
help_text	Help description
group	Group name for help
required	If true, option must be provided
env_var_name	Environment variable fallback (or NULL)

◆ options_builder_add_callback_optional()

void options_builder_add_callback_optional	(	options_builder_t *	builder,
		const char *	long_name,
		char	short_name,
		size_t	offset,
		const void *	default_value,
		size_t	value_size,
		bool()(const char arg, void dest, char *error_msg)	parse_fn,
		const char *	help_text,
		const char *	group,
		bool	required,
		const char *	env_var_name,
		bool	optional_arg
	)

Add option with custom callback parser that supports optional arguments.

Allows the callback to receive NULL if no argument is provided (when next arg is a flag).

Parameters

builder	Builder to add to
long_name	Long option name
short_name	Short option char (or '\0')
offset	offsetof(struct, field)
default_value	Pointer to default value (or NULL)
value_size	sizeof(field_type)
parse_fn	Custom parser function (receives NULL if arg not provided)
help_text	Help description
group	Group name for help
required	If true, option must be provided
env_var_name	Environment variable fallback (or NULL)
optional_arg	If true, argument is optional for this callback

◆ options_builder_add_callback_with_metadata()

void options_builder_add_callback_with_metadata	(	options_builder_t *	builder,
		const char *	long_name,
		char	short_name,
		size_t	offset,
		const void *	default_value,
		size_t	value_size,
		bool()(const char arg, void dest, char *error_msg)	parse_fn,
		const char *	help_text,
		const char *	group,
		bool	required,
		const char *	env_var_name,
		bool	optional_arg,
		const option_metadata_t *	metadata
	)

Add callback option with full metadata (for enums, ranges, examples, etc.)

Adds a callback-based option with complete metadata information for help and shell completions.

Parameters

builder	Builder to add to
long_name	Long option name
short_name	Short option char (or '\0')
offset	offsetof(struct, field)
default_value	Pointer to default value
value_size	sizeof(field_type)
parse_fn	Custom parser function
help_text	Help description
group	Group name for help
required	If true, option must be provided
env_var_name	Environment variable fallback (or NULL)
optional_arg	If true, argument is optional for this callback
metadata	Completion metadata (enums, ranges, examples, etc.)

◆ options_builder_add_custom_section()

void options_builder_add_custom_section	(	options_builder_t *	builder,
		const char *	heading,
		const char *	content,
		option_mode_bitmask_t	mode_bitmask
	)

Add a custom help section.

Adds a custom section to help output that appears after EXAMPLES but before OPTIONS.

Parameters

[in]	builder	Options builder
[in]	heading	Section heading (e.g., "INTERACTIVE CONTROLS")
[in]	content	Section content
[in]	mode_bitmask	Which modes show this section (use MODE_BITMASK_* constants)

Definition at line 1319 of file builder.c.

                                                                            {
  if (!builder || !heading || !content)
    return;
 
  ensure_custom_section_capacity(builder);
 
  custom_section_descriptor_t section = {.heading = heading, .content = content, .mode_bitmask = mode_bitmask};
 
  builder->custom_sections[builder->num_custom_sections++] = section;
}

References options_builder_t::custom_sections, custom_section_descriptor_t::heading, and options_builder_t::num_custom_sections.

Referenced by options_preset_unified().

◆ options_builder_add_dependency()

void options_builder_add_dependency	(	options_builder_t *	builder,
		const option_dependency_t *	dependency
	)

Add full dependency (advanced)

Parameters

builder	Builder to add to
dependency	Dependency to copy

Definition at line 1164 of file builder.c.

                                                                                                       {
  if (!builder || !dependency)
    return;
 
  ensure_dependency_capacity(builder);
  builder->dependencies[builder->num_dependencies++] = *dependency;
}

References options_builder_t::dependencies, ensure_dependency_capacity(), and options_builder_t::num_dependencies.

Referenced by options_builder_from_preset().

◆ options_builder_add_dependency_conflicts()

void options_builder_add_dependency_conflicts	(	options_builder_t *	builder,
		const char *	option_name,
		const char *	conflicts_with,
		const char *	error_message
	)

Add anti-dependency: if option_name is set, conflicts_with must NOT be set.

Parameters

builder	Builder to add to
option_name	Option that has the conflict
conflicts_with	Option it conflicts with
error_message	Custom error message (or NULL for default)

Definition at line 1142 of file builder.c.

                                                                                                     {
  ensure_dependency_capacity(builder);
 
  option_dependency_t dep = {.option_name = option_name,
                             .type = DEPENDENCY_CONFLICTS,
                             .depends_on = conflicts_with,
                             .error_message = error_message};
 
  builder->dependencies[builder->num_dependencies++] = dep;
}

References options_builder_t::dependencies, DEPENDENCY_CONFLICTS, ensure_dependency_capacity(), options_builder_t::num_dependencies, and option_dependency_t::option_name.

Referenced by options_preset_unified().

◆ options_builder_add_dependency_implies()

void options_builder_add_dependency_implies	(	options_builder_t *	builder,
		const char *	option_name,
		const char *	implies,
		const char *	error_message
	)

Add implication: if option_name is set, implies defaults to true.

Parameters

builder	Builder to add to
option_name	Option that implies another
implies	Option that is implied
error_message	Custom message (rarely used, can be NULL)

Definition at line 1154 of file builder.c.

                                                                       {
  ensure_dependency_capacity(builder);
 
  option_dependency_t dep = {
      .option_name = option_name, .type = DEPENDENCY_IMPLIES, .depends_on = implies, .error_message = error_message};
 
  builder->dependencies[builder->num_dependencies++] = dep;
}

References options_builder_t::dependencies, DEPENDENCY_IMPLIES, ensure_dependency_capacity(), options_builder_t::num_dependencies, and option_dependency_t::option_name.

◆ options_builder_add_dependency_requires()

void options_builder_add_dependency_requires	(	options_builder_t *	builder,
		const char *	option_name,
		const char *	depends_on,
		const char *	error_message
	)

Add dependency: if option_name is set, depends_on must be set.

Parameters

builder	Builder to add to
option_name	Option that has the dependency
depends_on	Option it depends on
error_message	Custom error message (or NULL for default)

Definition at line 1130 of file builder.c.

                                                                                                {
  ensure_dependency_capacity(builder);
 
  option_dependency_t dep = {.option_name = option_name,
                             .type = DEPENDENCY_REQUIRES,
                             .depends_on = depends_on,
                             .error_message = error_message};
 
  builder->dependencies[builder->num_dependencies++] = dep;
}

References options_builder_t::dependencies, DEPENDENCY_REQUIRES, ensure_dependency_capacity(), options_builder_t::num_dependencies, and option_dependency_t::option_name.

Referenced by options_preset_unified().

◆ options_builder_add_descriptor()

void options_builder_add_descriptor	(	options_builder_t *	builder,
		const option_descriptor_t *	descriptor
	)

Add full option descriptor (advanced)

Parameters

builder	Builder to add to
descriptor	Descriptor to copy

Definition at line 973 of file builder.c.

                                                                                                       {
  if (!builder || !descriptor) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Builder is NULL or descriptor is NULL");
    return;
  }
  return;
 
  ensure_descriptor_capacity(builder);
  builder->descriptors[builder->num_descriptors++] = *descriptor;
}

References options_builder_t::descriptors, ensure_descriptor_capacity(), ERROR_INVALID_PARAM, options_builder_t::num_descriptors, and SET_ERRNO.

Referenced by options_builder_from_preset().

◆ options_builder_add_double()

void options_builder_add_double	(	options_builder_t *	builder,
		const char *	long_name,
		char	short_name,
		size_t	offset,
		double	default_value,
		const char *	help_text,
		const char *	group,
		bool	required,
		const char *	env_var_name,
		bool()(const void options_struct, char **error_msg)	validate,
		bool	optional_arg
	)

Add double/float option.

Parameters

builder	Builder to add to
long_name	Long option name
short_name	Short option char (or '\0')
offset	offsetof(struct, field)
default_value	Default value
help_text	Help description
group	Group name for help
required	If true, option must be provided
env_var_name	Environment variable fallback (or NULL)
validate	Validator function receiving full struct (or NULL)

◆ options_builder_add_double_with_metadata()

void options_builder_add_double_with_metadata	(	options_builder_t *	builder,
		const char *	long_name,
		char	short_name,
		size_t	offset,
		double	default_value,
		const char *	help_text,
		const char *	group,
		bool	required,
		const char *	env_var_name,
		bool()(const void options_struct, char **error_msg)	validate,
		const option_metadata_t *	metadata,
		bool	optional_arg
	)

◆ options_builder_add_example()

void options_builder_add_example	(	options_builder_t *	builder,
		uint32_t	mode_bitmask,
		const char *	args,
		const char *	description,
		bool	owns_args
	)

Add example descriptor.

Adds an example command to be printed in the EXAMPLES section. Components are colored separately during printing:

mode: magenta
args: green

Parameters

builder	Builder instance
mode	Mode name (NULL or "server", "client", "mirror", etc.)
args	Arguments (NULL or "example.com", "swift-river-mountain", etc.)
description	Help text for this example

Example:

options_builder_add_example(b, NULL, NULL,
                            "Start new session");
 
options_builder_add_example(b, "server", NULL,
                            "Run as dedicated server");
 
options_builder_add_example(b, "client", "example.com",
                            "Connect to specific server");

Add an example to the help output

Parameters

builder	Builder instance
mode_bitmask	Bitmask of modes (OPTION_MODE_SERVER \| OPTION_MODE_CLIENT, etc.) Use OPTION_MODE_BINARY for binary-level examples
args	Arguments (NULL or "example.com", etc.)
description	Help text for this example
owns_args	If true, duplicate and track the args string

Definition at line 1255 of file builder.c.

                                                                          {
  if (!builder || !description)
    return;
 
  ensure_example_capacity(builder);
 
  example_descriptor_t example = {.mode_bitmask = mode_bitmask,
                                  .description = description,
                                  .owns_args_memory = owns_args,
                                  .is_utility_command = false};
 
  if (owns_args) {
    // If owning, duplicate the string and track it
    char *owned_args = platform_strdup(args);
    if (!owned_args) {
      log_fatal("Failed to duplicate example args string");
      return;
    }
    example.args = owned_args;
    track_owned_string_builder(builder, owned_args);
  } else {
    example.args = args;
  }
 
  builder->examples[builder->num_examples++] = example;
}

References example_descriptor_t::args, args, options_builder_t::examples, log_fatal, example_descriptor_t::mode_bitmask, options_builder_t::num_examples, and platform_strdup().

Referenced by options_preset_unified().

◆ options_builder_add_example_utility()

void options_builder_add_example_utility	(	options_builder_t *	builder,
		uint32_t	mode_bitmask,
		const char *	args,
		const char *	description,
		bool	is_utility_command
	)

Add an example with utility command support.

Utility commands (like pbpaste, cat, etc.) that shouldn't be prepended with program name or mode in help output.

Parameters

builder	Builder instance
mode_bitmask	Bitmask of modes (OPTION_MODE_MIRROR, etc.)
args	Arguments (e.g., "pbpaste \| cat -", "cat video.avi \| ascii-chat mirror -f '-'")
description	Help text for this example
is_utility_command	Must be true for utility commands

Allows marking utility commands (like pbpaste, grep, etc.) that shouldn't be prepended with program name in help output.

Definition at line 1289 of file builder.c.

                                                                                           {
  if (!builder || !description)
    return;
 
  ensure_example_capacity(builder);
 
  example_descriptor_t example = {.mode_bitmask = mode_bitmask,
                                  .description = description,
                                  .owns_args_memory = false,
                                  .is_utility_command = is_utility_command};
 
  if (args) {
    example.args = args;
  }
 
  builder->examples[builder->num_examples++] = example;
}

References example_descriptor_t::args, args, options_builder_t::examples, example_descriptor_t::mode_bitmask, and options_builder_t::num_examples.

Referenced by options_preset_unified().

◆ options_builder_add_int()

void options_builder_add_int	(	options_builder_t *	builder,
		const char *	long_name,
		char	short_name,
		size_t	offset,
		int	default_value,
		const char *	help_text,
		const char *	group,
		bool	required,
		const char *	env_var_name,
		bool()(const void options_struct, char **error_msg)	validate
	)

Add integer option.

Parameters

builder	Builder to add to
long_name	Long option name
short_name	Short option char (or '\0')
offset	offsetof(struct, field)
default_value	Default value
help_text	Help description
group	Group name for help
required	If true, option must be provided
env_var_name	Environment variable fallback (or NULL)
validate	Validator function receiving full struct (or NULL)

◆ options_builder_add_int_with_metadata()

void options_builder_add_int_with_metadata	(	options_builder_t *	builder,
		const char *	long_name,
		char	short_name,
		size_t	offset,
		int	default_value,
		const char *	help_text,
		const char *	group,
		bool	required,
		const char *	env_var_name,
		bool()(const void options_struct, char **error_msg)	validate,
		const option_metadata_t *	metadata
	)

Add integer option with metadata (for numeric ranges and examples)

Like options_builder_add_int() but also includes metadata for numeric ranges, examples, and completions.

Parameters

metadata Pointer to option_metadata_t with numeric_range, examples, etc. (can be NULL)

Definition at line 710 of file builder.c.

                                                                              {
  ensure_descriptor_capacity(builder);
 
  if (g_int_defaults_counter >= 256) {
    log_error("Too many int options (max 256)");
    return;
  }
 
  g_int_defaults[g_int_defaults_counter] = default_value;
 
  option_descriptor_t desc = {.long_name = long_name,
                              .short_name = short_name,
                              .type = OPTION_TYPE_INT,
                              .offset = offset,
                              .help_text = help_text,
                              .group = group,
                              .default_value = &g_int_defaults[g_int_defaults_counter++],
                              .required = required,
                              .env_var_name = env_var_name,
                              .validate = validate,
                              .parse_fn = NULL,
                              .owns_memory = false,
                              .mode_bitmask = OPTION_MODE_NONE,
                              .metadata = metadata ? *metadata : (option_metadata_t){0}};
 
  builder->descriptors[builder->num_descriptors++] = desc;
}

References options_builder_t::descriptors, ensure_descriptor_capacity(), log_error, option_descriptor_t::long_name, options_builder_t::num_descriptors, OPTION_MODE_NONE, and OPTION_TYPE_INT.

Referenced by options_registry_add_all_to_builder().

◆ options_builder_add_mode()

void options_builder_add_mode	(	options_builder_t *	builder,
		const char *	name,
		const char *	description
	)

Add mode descriptor.

Adds a mode to be printed in the MODES section. The mode name is colored magenta during printing.

Parameters

builder	Builder instance
name	Mode name (e.g., "server", "client", "mirror")
description	Mode description

Example:

options_builder_add_mode(b, "server", "Run as multi-client video chat server");
options_builder_add_mode(b, "client", "Run as video chat client (connect to server)");
options_builder_add_mode(b, "mirror", "View local webcam as ASCII art (no server)");

Definition at line 1308 of file builder.c.

                                                                                                     {
  if (!builder || !name || !description)
    return;
 
  ensure_mode_capacity(builder);
 
  help_mode_descriptor_t mode = {.name = name, .description = description};
 
  builder->modes[builder->num_modes++] = mode;
}

References options_builder_t::modes, help_mode_descriptor_t::name, and options_builder_t::num_modes.

Referenced by options_preset_unified().

◆ options_builder_add_positional()

void options_builder_add_positional	(	options_builder_t *	builder,
		const char *	name,
		const char *	help_text,
		bool	required,
		const char *	section_heading,
		const char **	examples,
		size_t	num_examples,
		option_mode_bitmask_t	mode_bitmask,
		int()(const char arg, void config, char remaining, int num_remaining, char *error_msg)	parse_fn
	)

Add positional argument descriptor.

Positional arguments are parsed after getopt finishes, from the remaining argv elements that don't start with '-'. They are parsed in the order they are added to the builder.

Example (client mode):

options_builder_add_positional(
    builder,
    "address",
    "[address][:port] - Server address (IPv4, IPv6, or hostname) with optional port",
    false,  // Not required (defaults to localhost)
    parse_client_address_arg
);

Example (server mode):

options_builder_add_positional(
    builder,
    "bind-addr",
    "Bind address (IPv4 or IPv6) - can specify 0-2 addresses",
    false,  // Not required (defaults to localhost dual-stack)
    parse_server_bind_addr
);

Parameters

builder	Builder to add to
name	Name for help text (e.g., "address")
help_text	Description for usage message
required	If true, this positional arg must be provided
section_heading	Optional section heading for examples (e.g., "ADDRESS FORMATS")
examples	Optional array of example strings with descriptions
num_examples	Number of examples in array
mode_bitmask	Which modes this positional arg applies to
parse_fn	Custom parser (receives arg, config, remaining args, error_msg) Returns number of args consumed (usually 1), or -1 on error

Definition at line 1192 of file builder.c.

                                                                       {
  if (!builder || !name || !parse_fn)
    return;
 
  ensure_positional_arg_capacity(builder);
 
  positional_arg_descriptor_t pos_arg = {.name = name,
                                         .help_text = help_text,
                                         .required = required,
                                         .section_heading = section_heading,
                                         .examples = examples,
                                         .num_examples = num_examples,
                                         .mode_bitmask = mode_bitmask,
                                         .parse_fn = parse_fn};
 
  builder->positional_args[builder->num_positional_args++] = pos_arg;
}

References ensure_positional_arg_capacity(), positional_arg_descriptor_t::name, options_builder_t::num_positional_args, and options_builder_t::positional_args.

Referenced by options_builder_from_preset(), and options_preset_unified().

◆ options_builder_add_string()

void options_builder_add_string	(	options_builder_t *	builder,
		const char *	long_name,
		char	short_name,
		size_t	offset,
		const char *	default_value,
		const char *	help_text,
		const char *	group,
		bool	required,
		const char *	env_var_name,
		bool()(const void options_struct, char **error_msg)	validate
	)

Add string option.

Strings are automatically strdup'd during parsing and freed during cleanup.

Parameters

builder	Builder to add to
long_name	Long option name
short_name	Short option char (or '\0')
offset	offsetof(struct, field)
default_value	Default value (will be strdup'd, or NULL)
help_text	Help description
group	Group name for help
required	If true, option must be provided
env_var_name	Environment variable fallback (or NULL)
validate	Validator function receiving full struct (or NULL)

◆ options_builder_add_usage()

void options_builder_add_usage	(	options_builder_t *	builder,
		const char *	mode,
		const char *	positional,
		bool	show_options,
		const char *	description
	)

Add usage line descriptor.

Adds a usage line to be printed in the USAGE section. Components are colored separately during printing:

mode: magenta
positional: green
"[options...]": yellow

Parameters

builder	Builder instance
mode	Mode name (NULL for binary-level, or "server", "<mode>", etc.)
positional	Positional args (NULL or "[bind-addr]", "<session-string>", etc.)
show_options	True to append "[options...]" or "[mode-options...]"
description	Help text for this usage pattern

Example:

options_builder_add_usage(b, NULL, NULL, true,
                          "Start a new session");
 
options_builder_add_usage(b, NULL, "<session-string>", true,
                          "Join an existing session");
 
options_builder_add_usage(b, "<mode>", NULL, true,
                          "Run in a specific mode");

Definition at line 1242 of file builder.c.

                                                        {
  if (!builder || !description)
    return;
 
  ensure_usage_line_capacity(builder);
 
  usage_descriptor_t usage = {
      .mode = mode, .positional = positional, .show_options = show_options, .description = description};
 
  builder->usage_lines[builder->num_usage_lines++] = usage;
}

References usage_descriptor_t::mode, options_builder_t::num_usage_lines, usage(), and options_builder_t::usage_lines.

Referenced by options_preset_unified().

◆ options_builder_build()

options_config_t * options_builder_build ( options_builder_t * builder )

Build immutable options config.

Creates final config from builder. Builder is NOT consumed - you must still call options_builder_destroy().

Parameters

builder Builder with options and dependencies

Returns: Immutable config (must be freed with options_config_destroy)

Definition at line 482 of file builder.c.

                                                                    {
  if (!builder) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Builder is NULL");
    return NULL;
  }
 
  options_config_t *config = SAFE_MALLOC(sizeof(options_config_t), options_config_t *);
  if (!config) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate options config");
    return NULL;
  }
 
  // Allocate and copy descriptors
  config->descriptors = SAFE_MALLOC(builder->num_descriptors * sizeof(option_descriptor_t), option_descriptor_t *);
  if (!config->descriptors && builder->num_descriptors > 0) {
    SAFE_FREE(config);
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate descriptors");
    return NULL;
  }
  memcpy(config->descriptors, builder->descriptors, builder->num_descriptors * sizeof(option_descriptor_t));
  config->num_descriptors = builder->num_descriptors;
 
  // Allocate and copy dependencies
  config->dependencies = SAFE_MALLOC(builder->num_dependencies * sizeof(option_dependency_t), option_dependency_t *);
  if (!config->dependencies && builder->num_dependencies > 0) {
    SAFE_FREE(config->descriptors);
    SAFE_FREE(config);
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate dependencies");
    return NULL;
  }
  memcpy(config->dependencies, builder->dependencies, builder->num_dependencies * sizeof(option_dependency_t));
  config->num_dependencies = builder->num_dependencies;
 
  // Allocate and copy positional args
  if (builder->num_positional_args > 0) {
    config->positional_args =
        SAFE_MALLOC(builder->num_positional_args * sizeof(positional_arg_descriptor_t), positional_arg_descriptor_t *);
    if (!config->positional_args) {
      SAFE_FREE(config->descriptors);
      SAFE_FREE(config->dependencies);
      SAFE_FREE(config);
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate positional args");
      return NULL;
    }
    memcpy(config->positional_args, builder->positional_args,
           builder->num_positional_args * sizeof(positional_arg_descriptor_t));
    config->num_positional_args = builder->num_positional_args;
  } else {
    config->positional_args = NULL;
    config->num_positional_args = 0;
  }
 
  // Allocate and copy usage lines
  if (builder->num_usage_lines > 0) {
    config->usage_lines = SAFE_MALLOC(builder->num_usage_lines * sizeof(usage_descriptor_t), usage_descriptor_t *);
    if (!config->usage_lines) {
      SAFE_FREE(config->descriptors);
      SAFE_FREE(config->dependencies);
      SAFE_FREE(config->positional_args);
      SAFE_FREE(config);
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate usage lines");
      return NULL;
    }
    memcpy(config->usage_lines, builder->usage_lines, builder->num_usage_lines * sizeof(usage_descriptor_t));
    config->num_usage_lines = builder->num_usage_lines;
  } else {
    config->usage_lines = NULL;
    config->num_usage_lines = 0;
  }
 
  // Allocate and copy examples
  if (builder->num_examples > 0) {
    config->examples = SAFE_MALLOC(builder->num_examples * sizeof(example_descriptor_t), example_descriptor_t *);
    if (!config->examples) {
      SAFE_FREE(config->descriptors);
      SAFE_FREE(config->dependencies);
      SAFE_FREE(config->positional_args);
      SAFE_FREE(config->usage_lines);
      SAFE_FREE(config);
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate examples");
      return NULL;
    }
    memcpy(config->examples, builder->examples, builder->num_examples * sizeof(example_descriptor_t));
    config->num_examples = builder->num_examples;
  } else {
    config->examples = NULL;
    config->num_examples = 0;
  }
 
  // Allocate and copy modes
  if (builder->num_modes > 0) {
    config->modes = SAFE_MALLOC(builder->num_modes * sizeof(help_mode_descriptor_t), help_mode_descriptor_t *);
    if (!config->modes) {
      SAFE_FREE(config->descriptors);
      SAFE_FREE(config->dependencies);
      SAFE_FREE(config->positional_args);
      SAFE_FREE(config->usage_lines);
      SAFE_FREE(config->examples);
      SAFE_FREE(config);
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate modes");
      return NULL;
    }
    memcpy(config->modes, builder->modes, builder->num_modes * sizeof(help_mode_descriptor_t));
    config->num_modes = builder->num_modes;
  } else {
    config->modes = NULL;
    config->num_modes = 0;
  }
 
  // Allocate and copy custom sections
  if (builder->num_custom_sections > 0) {
    config->custom_sections =
        SAFE_MALLOC(builder->num_custom_sections * sizeof(custom_section_descriptor_t), custom_section_descriptor_t *);
    if (!config->custom_sections) {
      SAFE_FREE(config->descriptors);
      SAFE_FREE(config->dependencies);
      SAFE_FREE(config->positional_args);
      SAFE_FREE(config->usage_lines);
      SAFE_FREE(config->examples);
      SAFE_FREE(config->modes);
      SAFE_FREE(config);
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate custom sections");
      return NULL;
    }
    memcpy(config->custom_sections, builder->custom_sections,
           builder->num_custom_sections * sizeof(custom_section_descriptor_t));
    config->num_custom_sections = builder->num_custom_sections;
  } else {
    config->custom_sections = NULL;
    config->num_custom_sections = 0;
  }
 
  config->struct_size = builder->struct_size;
  config->program_name = builder->program_name;
  config->description = builder->description;
 
  // Initialize memory management
  config->owned_strings = builder->owned_strings_builder;
  config->num_owned_strings = builder->num_owned_strings_builder;
  config->owned_strings_capacity = builder->owned_strings_builder_capacity;
 
  // Clear builder's ownership so it doesn't free them
  builder->owned_strings_builder = NULL;
  builder->num_owned_strings_builder = 0;
  builder->owned_strings_builder_capacity = 0;
 
  return config;
}

Referenced by options_builder_generate_manpage_template(), and options_preset_unified().

◆ options_builder_create()

options_builder_t * options_builder_create ( size_t struct_size )

Create empty options builder.

Parameters

struct_size sizeof(your_options_t) for the target options struct

Returns: New builder (must be freed with options_builder_destroy)

Definition at line 378 of file builder.c.

                                                              {
  // Reset int defaults counter for new builder
  g_int_defaults_counter = 0;
 
  options_builder_t *builder = SAFE_MALLOC(sizeof(options_builder_t), options_builder_t *);
  if (!builder) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate options builder");
    return NULL;
  }
 
  builder->descriptors = SAFE_MALLOC(INITIAL_DESCRIPTOR_CAPACITY * sizeof(option_descriptor_t), option_descriptor_t *);
  if (!builder->descriptors) {
    free(builder);
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate descriptors array");
    return NULL;
  }
 
  builder->dependencies = SAFE_MALLOC(INITIAL_DEPENDENCY_CAPACITY * sizeof(option_dependency_t), option_dependency_t *);
  if (!builder->dependencies) {
    SAFE_FREE(builder->descriptors);
    SAFE_FREE(builder);
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate dependencies array");
    return NULL;
  }
 
  builder->num_descriptors = 0;
  builder->descriptor_capacity = INITIAL_DESCRIPTOR_CAPACITY;
  builder->num_dependencies = 0;
  builder->dependency_capacity = INITIAL_DEPENDENCY_CAPACITY;
  builder->positional_args = NULL;
  builder->num_positional_args = 0;
  builder->positional_arg_capacity = 0;
  builder->usage_lines = NULL;
  builder->num_usage_lines = 0;
  builder->usage_line_capacity = 0;
  builder->examples = NULL;
  builder->num_examples = 0;
  builder->example_capacity = 0;
  builder->modes = NULL;
  builder->num_modes = 0;
  builder->mode_capacity = 0;
  builder->custom_sections = NULL;
  builder->num_custom_sections = 0;
  builder->custom_section_capacity = 0;
  builder->struct_size = struct_size;
  builder->program_name = NULL;
  builder->description = NULL;
  builder->owned_strings_builder = NULL;
  builder->num_owned_strings_builder = 0;
  builder->owned_strings_builder_capacity = 0;
 
  return builder;
}

Referenced by options_builder_from_preset(), and options_preset_unified().

◆ options_builder_destroy()

void options_builder_destroy ( options_builder_t * builder )

Free options builder.

Parameters

builder Builder to free (can be NULL)

Definition at line 467 of file builder.c.

                                                         {
  if (!builder)
    return;
 
  SAFE_FREE(builder->descriptors);
  SAFE_FREE(builder->dependencies);
  SAFE_FREE(builder->positional_args);
  SAFE_FREE(builder->usage_lines);
  SAFE_FREE(builder->examples);
  SAFE_FREE(builder->modes);
  SAFE_FREE(builder->custom_sections);
  SAFE_FREE(builder->owned_strings_builder); // Free the builder's owned strings
  SAFE_FREE(builder);
}

References options_builder_t::custom_sections, options_builder_t::dependencies, options_builder_t::descriptors, options_builder_t::examples, options_builder_t::modes, options_builder_t::owned_strings_builder, options_builder_t::positional_args, SAFE_FREE, and options_builder_t::usage_lines.

Referenced by options_preset_unified().

◆ options_builder_from_preset()

options_builder_t * options_builder_from_preset ( const options_config_t * preset )

Create builder from preset config.

Copies all descriptors and dependencies from the preset.

Parameters

preset Preset configuration to copy

Returns: New builder (must be freed with options_builder_destroy)

Definition at line 432 of file builder.c.

                                                                               {
  if (!preset) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Preset config is NULL");
    return NULL;
  }
 
  options_builder_t *builder = options_builder_create(preset->struct_size);
  if (!builder) {
    return NULL;
  }
 
  builder->program_name = preset->program_name;
  builder->description = preset->description;
 
  // Copy all descriptors
  for (size_t i = 0; i < preset->num_descriptors; i++) {
    options_builder_add_descriptor(builder, &preset->descriptors[i]);
  }
 
  // Copy all dependencies
  for (size_t i = 0; i < preset->num_dependencies; i++) {
    options_builder_add_dependency(builder, &preset->dependencies[i]);
  }
 
  // Copy all positional arguments
  for (size_t i = 0; i < preset->num_positional_args; i++) {
    const positional_arg_descriptor_t *pos_arg = &preset->positional_args[i];
    options_builder_add_positional(builder, pos_arg->name, pos_arg->help_text, pos_arg->required,
                                   pos_arg->section_heading, pos_arg->examples, pos_arg->num_examples,
                                   pos_arg->mode_bitmask, pos_arg->parse_fn);
  }
 
  return builder;
}

References options_config_t::dependencies, options_config_t::description, options_builder_t::description, options_config_t::descriptors, ERROR_INVALID_PARAM, positional_arg_descriptor_t::examples, positional_arg_descriptor_t::help_text, positional_arg_descriptor_t::mode_bitmask, positional_arg_descriptor_t::name, options_config_t::num_dependencies, options_config_t::num_descriptors, positional_arg_descriptor_t::num_examples, options_config_t::num_positional_args, options_builder_add_dependency(), options_builder_add_descriptor(), options_builder_add_positional(), options_builder_create(), positional_arg_descriptor_t::parse_fn, options_config_t::positional_args, options_config_t::program_name, options_builder_t::program_name, positional_arg_descriptor_t::required, positional_arg_descriptor_t::section_heading, SET_ERRNO, and options_config_t::struct_size.

◆ options_builder_mark_as_list()

void options_builder_mark_as_list	(	options_builder_t *	builder,
		const char *	option_name
	)

Mark option as accepting multiple values.

Indicates the option accepts comma-separated or space-separated values.

Parameters

builder	Options builder
option_name	Long name of option to mark

Example:

options_builder_mark_as_list(builder, "stun-servers"); // Accepts comma-separated URLs

options_builder_mark_as_list

void options_builder_mark_as_list(options_builder_t *builder, const char *option_name)

Mark option as accepting multiple values.

Definition builder.c:1093

Definition at line 1093 of file builder.c.

                                                                                       {
  if (!builder || !option_name) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Builder or option_name is NULL");
    return;
  }
 
  int idx = find_descriptor_in_builder(builder, option_name);
  if (idx < 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Option '%s' not found in builder", option_name);
    return;
  }
 
  option_descriptor_t *desc = &builder->descriptors[idx];
  desc->metadata.is_list = true;
}

References options_builder_t::descriptors, ERROR_INVALID_PARAM, option_metadata_t::is_list, option_descriptor_t::metadata, and SET_ERRNO.

◆ options_builder_mark_binary_only()

void options_builder_mark_binary_only	(	options_builder_t *	builder,
		const char *	option_name
	)

Mark an option as binary-level only (hide from mode-specific help)

Binary-level options are still parsed by mode-specific parsers (so they work anywhere in the command line), but they don't appear in mode-specific –help. They should only be documented in the top-level binary help.

Parameters

builder	Builder containing the option
option_name	Long name of the option to mark

Example:

options_builder_add_string(b, "log-file", 'L', ...);

options_builder_mark_binary_only(b, "log-file");

options_builder_mark_binary_only

void options_builder_mark_binary_only(options_builder_t *builder, const char *option_name)

Mark an option as binary-level only (hide from mode-specific help)

Definition builder.c:1172

options_builder_add_string

void options_builder_add_string(options_builder_t *builder, const char *long_name, char short_name, size_t offset, const char *default_value, const char *help_text, const char *group, bool required, const char *env_var_name, bool(*validate)(const void *, char **))

Definition builder.c:742

Definition at line 1172 of file builder.c.

                                                                                           {
  if (!builder || !option_name)
    return;
 
  // Find the option by name and mark it
  for (size_t i = 0; i < builder->num_descriptors; i++) {
    if (strcmp(builder->descriptors[i].long_name, option_name) == 0) {
      builder->descriptors[i].hide_from_mode_help = true;
      return;
    }
  }
 
  // Option not found - this is a programming error
  log_warn("Attempted to mark non-existent option '%s' as binary-only", option_name);
}

References options_builder_t::descriptors, option_descriptor_t::hide_from_mode_help, log_warn, option_descriptor_t::long_name, and options_builder_t::num_descriptors.

◆ options_builder_set_arg_placeholder()

void options_builder_set_arg_placeholder	(	options_builder_t *	builder,
		const char *	arg_placeholder
	)

Set custom argument placeholder on the last added option descriptor.

Sets the arg_placeholder field on the most recently added option descriptor. This allows customizing the placeholder text shown in help (e.g., "SHELL [FILE]" instead of "STR").

Parameters

builder	Options builder
arg_placeholder	Custom placeholder text (e.g., "SHELL [FILE]"), or NULL to use type-based placeholder

Definition at line 992 of file builder.c.

                                                                                                  {
  if (!builder || builder->num_descriptors == 0) {
    SET_ERRNO(ERROR_INVALID_STATE, "Builder is NULL or has no descriptors");
    return;
  }
  builder->descriptors[builder->num_descriptors - 1].arg_placeholder = arg_placeholder;
}

References option_descriptor_t::arg_placeholder, options_builder_t::descriptors, ERROR_INVALID_STATE, options_builder_t::num_descriptors, and SET_ERRNO.

Referenced by options_registry_add_all_to_builder().

◆ options_builder_set_default_value_display()

void options_builder_set_default_value_display	(	options_builder_t *	builder,
		const char *	option_name,
		const char *	default_value
	)

Set default value string in metadata.

Sets the default value string for display in completions (informational, separate from the descriptor's default_value which is used for parsing).

Parameters

builder	Options builder
option_name	Long name of option to set metadata for
default_value	Default value as string for display

Definition at line 1109 of file builder.c.

                                                                          {
  if (!builder || !option_name) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Builder or option_name is NULL");
    return;
  }
 
  int idx = find_descriptor_in_builder(builder, option_name);
  if (idx < 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Option '%s' not found in builder", option_name);
    return;
  }
 
  option_descriptor_t *desc = &builder->descriptors[idx];
  desc->metadata.default_value = default_value;
}

References option_metadata_t::default_value, options_builder_t::descriptors, ERROR_INVALID_PARAM, option_descriptor_t::metadata, and SET_ERRNO.

◆ options_builder_set_enum_values()

void options_builder_set_enum_values	(	options_builder_t *	builder,
		const char *	option_name,
		const char **	values,
		const char **	descriptions
	)

Set enum values with descriptions for an option.

Populates the metadata with enum values and descriptions for shell completion. Both arrays must have the same length.

Parameters

builder	Options builder
option_name	Long name of option to set metadata for
values	Array of enum value strings (e.g., {"auto", "none", "16", "256", "truecolor"})
descriptions	Array of descriptions parallel to values
count	Number of values/descriptions

Example:

const char *color_values[] = {"auto", "none", "16", "256", "truecolor"};
const char *color_descs[] = {
    "Auto-detect from terminal",
    "Monochrome only",
    "16 colors (ANSI)",
    "256 colors (xterm)",
    "24-bit truecolor (modern terminals)"
};
options_builder_set_enum_values(builder, "color-mode", color_values, color_descs, 5);
options_builder_set_input_type(builder, "color-mode", OPTION_INPUT_ENUM);

Definition at line 1022 of file builder.c.

                                                                {
  if (!builder || !option_name || !values || !descriptions) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Builder or arguments are NULL");
    return;
  }
 
  int idx = find_descriptor_in_builder(builder, option_name);
  if (idx < 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Option '%s' not found in builder", option_name);
    return;
  }
 
  option_descriptor_t *desc = &builder->descriptors[idx];
  desc->metadata.enum_values = values;
  desc->metadata.enum_descriptions = descriptions;
}

References options_builder_t::descriptors, option_metadata_t::enum_descriptions, option_metadata_t::enum_values, ERROR_INVALID_PARAM, option_descriptor_t::metadata, and SET_ERRNO.

◆ options_builder_set_examples()

void options_builder_set_examples	(	options_builder_t *	builder,
		const char *	option_name,
		const char **	examples
	)

Set example values for an option.

Provides example values or command invocations for help display and completion suggestions.

Parameters

builder	Options builder
option_name	Long name of option to set metadata for
examples	Array of example strings (must be null-terminated, may be values or full commands)

Example:

const char *fps_examples[] = {"30", "60", "144", NULL};

options_builder_set_examples(builder, "fps", fps_examples);

options_builder_set_examples

void options_builder_set_examples(options_builder_t *builder, const char *option_name, const char **examples)

Set example values for an option.

Definition builder.c:1059

Definition at line 1059 of file builder.c.

                                                                                                              {
  if (!builder || !option_name || !examples) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Builder or arguments are NULL");
    return;
  }
 
  int idx = find_descriptor_in_builder(builder, option_name);
  if (idx < 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Option '%s' not found in builder", option_name);
    return;
  }
 
  option_descriptor_t *desc = &builder->descriptors[idx];
  desc->metadata.examples = examples;
  // Note: examples array must be null-terminated
}

References options_builder_t::descriptors, ERROR_INVALID_PARAM, option_metadata_t::examples, option_descriptor_t::metadata, and SET_ERRNO.

◆ options_builder_set_input_type()

void options_builder_set_input_type	(	options_builder_t *	builder,
		const char *	option_name,
		option_input_type_t	input_type
	)

Set input type for an option.

Specifies what kind of input the option expects (enum, numeric, filepath, etc.) for generating appropriate shell completions.

Parameters

builder	Options builder
option_name	Long name of option to set metadata for
input_type	The input type (OPTION_INPUT_ENUM, OPTION_INPUT_NUMERIC, etc.)

Example:

options_builder_set_input_type(builder, "color-mode", OPTION_INPUT_ENUM);

options_builder_set_input_type(builder, "log-file", OPTION_INPUT_FILEPATH);

Definition at line 1076 of file builder.c.

                                                                    {
  if (!builder || !option_name) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Builder or option_name is NULL");
    return;
  }
 
  int idx = find_descriptor_in_builder(builder, option_name);
  if (idx < 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Option '%s' not found in builder", option_name);
    return;
  }
 
  option_descriptor_t *desc = &builder->descriptors[idx];
  desc->metadata.input_type = input_type;
}

References options_builder_t::descriptors, ERROR_INVALID_PARAM, option_metadata_t::input_type, option_descriptor_t::metadata, and SET_ERRNO.

◆ options_builder_set_mode_bitmask()

void options_builder_set_mode_bitmask	(	options_builder_t *	builder,
		option_mode_bitmask_t	mode_bitmask
	)

Set mode bitmask on the last added option descriptor.

Sets the mode_bitmask field on the most recently added option descriptor. This allows setting mode applicability after adding an option.

Parameters

builder	Options builder
mode_bitmask	Bitmask indicating which modes this option applies to

Definition at line 984 of file builder.c.

                                                                                                      {
  if (!builder || builder->num_descriptors == 0) {
    SET_ERRNO(ERROR_INVALID_STATE, "Builder is NULL or has no descriptors");
    return;
  }
  builder->descriptors[builder->num_descriptors - 1].mode_bitmask = mode_bitmask;
}

References options_builder_t::descriptors, ERROR_INVALID_STATE, option_descriptor_t::mode_bitmask, options_builder_t::num_descriptors, and SET_ERRNO.

Referenced by options_registry_add_all_to_builder().

◆ options_builder_set_numeric_range()

void options_builder_set_numeric_range	(	options_builder_t *	builder,
		const char *	option_name,
		int	min,
		int	max,
		int	step
	)

Set numeric range for an option.

Specifies minimum, maximum, and optional step for numeric input completions.

Parameters

builder	Options builder
option_name	Long name of option to set metadata for
min	Minimum value (0 = no limit)
max	Maximum value (0 = no limit)
step	Step size (0 = continuous, no step)

Example:

options_builder_set_numeric_range(builder, "compression-level", 1, 9, 1);

options_builder_set_input_type(builder, "compression-level", OPTION_INPUT_NUMERIC);

options_builder_set_numeric_range

void options_builder_set_numeric_range(options_builder_t *builder, const char *option_name, int min, int max, int step)

Set numeric range for an option.

Definition builder.c:1040

Definition at line 1040 of file builder.c.

                                                 {
  if (!builder || !option_name) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Builder or option_name is NULL");
    return;
  }
 
  int idx = find_descriptor_in_builder(builder, option_name);
  if (idx < 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Option '%s' not found in builder", option_name);
    return;
  }
 
  option_descriptor_t *desc = &builder->descriptors[idx];
  desc->metadata.numeric_range.min = min;
  desc->metadata.numeric_range.max = max;
  desc->metadata.numeric_range.step = step;
}

References options_builder_t::descriptors, ERROR_INVALID_PARAM, option_metadata_t::max, option_descriptor_t::metadata, option_metadata_t::min, option_metadata_t::numeric_range, SET_ERRNO, and option_metadata_t::step.

◆ options_config_calculate_max_col_width()

int options_config_calculate_max_col_width ( const options_config_t * config )

Calculate global max column width for help output alignment.

Calculates the maximum width needed for proper alignment across all help sections (USAGE, EXAMPLES, OPTIONS, MODES).

Parameters

config Options configuration

Returns: Maximum column width needed for alignment

Calculate global max column width for help output alignment.

Calculates the maximum width needed for proper alignment across USAGE, EXAMPLES, OPTIONS, and MODES sections.

Definition at line 77 of file help.c.

                                                                           {
  if (!config)
    return 0;
 
  const char *binary_name = PLATFORM_BINARY_NAME;
 
  int max_col_width = 0;
  char temp_buf[BUFFER_SIZE_MEDIUM];
 
  // Check USAGE entries (capped at 45 chars for max first column)
  for (size_t i = 0; i < config->num_usage_lines; i++) {
    const usage_descriptor_t *usage = &config->usage_lines[i];
    int len = 0;
 
    len += safe_snprintf(temp_buf + len, sizeof(temp_buf) - len, "%s", binary_name);
 
    if (usage->mode) {
      const char *colored_mode = colored_string(LOG_COLOR_FATAL, usage->mode);
      len += safe_snprintf(temp_buf + len, sizeof(temp_buf) - len, " %s", colored_mode);
    }
 
    if (usage->positional) {
      const char *colored_pos = colored_string(LOG_COLOR_INFO, usage->positional);
      len += safe_snprintf(temp_buf + len, sizeof(temp_buf) - len, " %s", colored_pos);
    }
 
    if (usage->show_options) {
      const char *options_text =
          (usage->mode && strcmp(usage->mode, "<mode>") == 0) ? "[mode-options...]" : "[options...]";
      const char *colored_opts = colored_string(LOG_COLOR_WARN, options_text);
      len += safe_snprintf(temp_buf + len, sizeof(temp_buf) - len, " %s", colored_opts);
    }
 
    int w = utf8_display_width(temp_buf);
    if (w > LAYOUT_COLUMN_WIDTH) {
      w = LAYOUT_COLUMN_WIDTH;
    }
    if (w > max_col_width)
      max_col_width = w;
  }
 
  // Check EXAMPLES entries
  for (size_t i = 0; i < config->num_examples; i++) {
    const example_descriptor_t *example = &config->examples[i];
    int len = 0;
 
    // Only prepend program name if this is not a utility command
    if (!example->is_utility_command) {
      len += safe_snprintf(temp_buf + len, sizeof(temp_buf) - len, "%s", binary_name);
 
      // Programmatically add mode name based on mode_bitmask
      const char *mode_name = get_mode_name_from_bitmask(example->mode_bitmask);
      if (mode_name) {
        len += safe_snprintf(temp_buf + len, sizeof(temp_buf) - len, " %s", mode_name);
      }
    }
 
    if (example->args) {
      const char *colored_args = colored_string(LOG_COLOR_INFO, example->args);
      len += safe_snprintf(temp_buf + len, sizeof(temp_buf) - len, " %s", colored_args);
    }
 
    int w = utf8_display_width(temp_buf);
    if (w > LAYOUT_COLUMN_WIDTH) {
      w = LAYOUT_COLUMN_WIDTH;
    }
    if (w > max_col_width)
      max_col_width = w;
  }
 
  // Check MODES entries (capped at 45 chars)
  for (size_t i = 0; i < config->num_modes; i++) {
    const char *colored_name = colored_string(LOG_COLOR_FATAL, config->modes[i].name);
    int w = utf8_display_width(colored_name);
    if (w > LAYOUT_COLUMN_WIDTH) {
      w = LAYOUT_COLUMN_WIDTH;
    }
    if (w > max_col_width)
      max_col_width = w;
  }
 
  // Check OPTIONS entries (from descriptors)
  for (size_t i = 0; i < config->num_descriptors; i++) {
    const option_descriptor_t *desc = &config->descriptors[i];
    if (desc->hide_from_mode_help || desc->hide_from_binary_help || !desc->group)
      continue;
 
    // Build option display string with separate coloring for short and long flags
    char opts_buf[BUFFER_SIZE_SMALL];
    if (desc->short_name && desc->short_name != '\0') {
      char short_flag[16];
      safe_snprintf(short_flag, sizeof(short_flag), "-%c", desc->short_name);
      char long_flag[BUFFER_SIZE_SMALL];
      safe_snprintf(long_flag, sizeof(long_flag), "--%s", desc->long_name);
      // Color short flag, add comma, color long flag
      safe_snprintf(opts_buf, sizeof(opts_buf), "%s, %s", colored_string(LOG_COLOR_WARN, short_flag),
                    colored_string(LOG_COLOR_WARN, long_flag));
    } else {
      char long_flag[BUFFER_SIZE_SMALL];
      safe_snprintf(long_flag, sizeof(long_flag), "--%s", desc->long_name);
      safe_snprintf(opts_buf, sizeof(opts_buf), "%s", colored_string(LOG_COLOR_WARN, long_flag));
    }
    const char *colored_opts = opts_buf;
 
    int w = utf8_display_width(colored_opts);
    if (w > LAYOUT_COLUMN_WIDTH) {
      w = LAYOUT_COLUMN_WIDTH;
    }
    if (w > max_col_width)
      max_col_width = w;
  }
 
  // Enforce maximum column width of 45 characters
  if (max_col_width > 45) {
    max_col_width = 45;
  }
 
  return max_col_width;
}

References example_descriptor_t::args, BUFFER_SIZE_MEDIUM, BUFFER_SIZE_SMALL, colored_string(), options_config_t::descriptors, options_config_t::examples, option_descriptor_t::group, option_descriptor_t::hide_from_binary_help, option_descriptor_t::hide_from_mode_help, example_descriptor_t::is_utility_command, LAYOUT_COLUMN_WIDTH, LOG_COLOR_FATAL, LOG_COLOR_INFO, LOG_COLOR_WARN, option_descriptor_t::long_name, example_descriptor_t::mode_bitmask, options_config_t::modes, help_mode_descriptor_t::name, options_config_t::num_descriptors, options_config_t::num_examples, options_config_t::num_modes, options_config_t::num_usage_lines, PLATFORM_BINARY_NAME, safe_snprintf(), option_descriptor_t::short_name, usage(), options_config_t::usage_lines, and utf8_display_width().

Referenced by options_config_print_options_sections_with_width(), and options_config_print_usage_section().

◆ options_config_destroy()

void options_config_destroy ( options_config_t * config )

Free options config.

Frees the config structure. Does NOT free strings in the options struct - use options_config_destroy() for that.

Parameters

config Config to free (can be NULL)

Definition at line 631 of file builder.c.

                                                      {
  if (!config)
    return;
 
  SAFE_FREE(config->descriptors);
  SAFE_FREE(config->dependencies);
  SAFE_FREE(config->positional_args);
  SAFE_FREE(config->usage_lines);
  SAFE_FREE(config->examples);
  SAFE_FREE(config->modes);
  SAFE_FREE(config->custom_sections);
 
  // Free all owned strings before freeing the array
  // Use SAFE_FREE because platform_strdup uses SAFE_MALLOC (mimalloc on Windows)
  for (size_t i = 0; i < config->num_owned_strings; i++) {
    SAFE_FREE(config->owned_strings[i]);
  }
  SAFE_FREE(config->owned_strings);
 
  SAFE_FREE(config);
}

References options_config_t::custom_sections, options_config_t::dependencies, options_config_t::descriptors, options_config_t::examples, options_config_t::modes, options_config_t::num_owned_strings, options_config_t::owned_strings, options_config_t::positional_args, SAFE_FREE, and options_config_t::usage_lines.

Referenced by config_create_default(), options_init(), and usage().

◆ options_config_parse()

asciichat_error_t options_config_parse	(	const options_config_t *	config,
		int	argc,
		char **	argv,
		void *	options_struct,
		option_mode_bitmask_t	detected_mode,
		int *	remaining_argc,
		char ***	remaining_argv
	)

Parse command-line arguments.

Parses argv using the option descriptors. Strings are automatically strdup'd. Environment variables are checked for missing options.

Parameters

config	Options configuration
argc	Argument count
argv	Argument vector
options_struct	Options struct to fill
remaining_argc	Optional: receives count of non-option args
remaining_argv	Optional: receives array of non-option args

Returns: ASCIICHAT_OK on success, ERROR_USAGE on parse errors

Definition at line 1815 of file builder.c.

                                                               {
  if (!config || !options_struct) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Config or options struct is NULL");
  }
 
  // Use the new unified parser that handles mixed positional and flag arguments
  asciichat_error_t result = options_config_parse_unified(config, argc, argv, options_struct, detected_mode);
  if (result != ASCIICHAT_OK) {
    return result;
  }
 
  // Since unified parser handles all arguments, there are no remaining args
  // (backward compatibility: set remaining_argc to 0)
  if (remaining_argc) {
    *remaining_argc = 0;
  }
  if (remaining_argv) {
    *remaining_argv = NULL;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, and SET_ERRNO.

Referenced by options_init().

◆ options_config_parse_positional()

asciichat_error_t options_config_parse_positional	(	const options_config_t *	config,
		int	remaining_argc,
		char **	remaining_argv,
		void *	options_struct
	)

Parse positional arguments.

Parses positional arguments from remaining_argv after getopt processing. Calls each positional arg descriptor's parse_fn in order.

This is called automatically by options_config_parse(), but can also be called separately if you want custom control over the parsing flow.

Parameters

config	Options configuration
remaining_argc	Count of remaining args
remaining_argv	Array of remaining args
options_struct	Options struct to fill

Returns: ASCIICHAT_OK on success, ERROR_USAGE on parse errors

Definition at line 1331 of file builder.c.

                                                                                               {
  if (!config || !options_struct) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Config or options struct is NULL");
  }
 
  if (remaining_argc < 0 || (remaining_argc > 0 && !remaining_argv)) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid remaining args");
  }
 
  // No positional args defined - but we got some positional arguments
  if (config->num_positional_args == 0 && remaining_argc > 0) {
    log_error("Error: Unexpected positional argument '%s'", remaining_argv[0]);
    return ERROR_USAGE;
  }
 
  // Check if required positional args are missing
  for (size_t i = 0; i < config->num_positional_args; i++) {
    const positional_arg_descriptor_t *pos_arg = &config->positional_args[i];
    if (pos_arg->required && remaining_argc == 0) {
      log_error("Error: Missing required positional argument '%s'", pos_arg->name);
      if (pos_arg->help_text) {
        log_error("  %s", pos_arg->help_text);
      }
      return ERROR_USAGE;
    }
  }
 
  // Parse positional arguments
  int arg_index = 0;
  for (size_t i = 0; i < config->num_positional_args && arg_index < remaining_argc; i++) {
    const positional_arg_descriptor_t *pos_arg = &config->positional_args[i];
 
    const char *arg = remaining_argv[arg_index];
    char **remaining = (arg_index + 1 < remaining_argc) ? &remaining_argv[arg_index + 1] : NULL;
    int num_remaining = remaining_argc - arg_index - 1;
    char *error_msg = NULL;
 
    // Call custom parser
    int consumed = pos_arg->parse_fn(arg, options_struct, remaining, num_remaining, &error_msg);
 
    if (consumed < 0) {
      // Parse error
      if (error_msg) {
        log_error("Error parsing positional argument '%s': %s", pos_arg->name, error_msg);
        free(error_msg);
      } else {
        log_error("Error parsing positional argument '%s': %s", pos_arg->name, arg);
      }
      return ERROR_USAGE;
    }
 
    // Advance by consumed args (usually 1, but can be more for multi-arg parsers)
    arg_index += consumed;
  }
 
  // Check for extra unconsumed positional arguments
  if (arg_index < remaining_argc) {
    log_error("Error: Unexpected positional argument '%s'", remaining_argv[arg_index]);
    return ERROR_USAGE;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_USAGE, positional_arg_descriptor_t::help_text, log_error, positional_arg_descriptor_t::name, options_config_t::num_positional_args, positional_arg_descriptor_t::parse_fn, options_config_t::positional_args, positional_arg_descriptor_t::required, and SET_ERRNO.

◆ options_config_print_options_sections()

void options_config_print_options_sections	(	const options_config_t *	config,
		FILE *	stream,
		asciichat_mode_t	mode
	)

Print everything except the USAGE section (backward compatibility)

Wrapper for options_config_print_options_sections_with_width with auto-calculation.

Parameters

config	Options configuration
stream	Output stream (stdout or stderr)
mode	Optional mode to filter by (if provided, filters by mode_bitmask)

Print everything except the USAGE section (backward compatibility)

Calls options_config_print_options_sections_with_width with auto-calculation.

Definition at line 1085 of file help.c.

                                                                                                                {
  options_config_print_options_sections_with_width(config, stream, 0, mode);
}

References options_config_print_options_sections_with_width().

◆ options_config_print_options_sections_with_width()

void options_config_print_options_sections_with_width	(	const options_config_t *	config,
		FILE *	stream,
		int	max_col_width,
		asciichat_mode_t	mode
	)

Print everything except the USAGE section.

Prints MODES, MODE-OPTIONS, EXAMPLES, and OPTIONS sections. Used with options_config_print_usage_section to allow custom content in between.

Parameters

config	Options configuration (should be unified preset with all options)
stream	Output stream (stdout or stderr)
max_col_width	Optional pre-calculated column width (0 = auto-calculate)
mode	Optional mode to filter by (if MODE_SERVER, MODE_CLIENT, etc., filters by mode_bitmask) If NULL or invalid, shows all options (for binary-level help)

Prints MODES, MODE-OPTIONS, EXAMPLES, and OPTIONS sections. Used with options_config_print_usage_section to allow custom content in between.

Definition at line 890 of file help.c.

                                                                             {
  if (!config || !stream) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Config or stream is NULL");
    return;
  }
 
  // Detect terminal width - try actual terminal size first, fallback to COLUMNS env var
  int term_width = 80;
  terminal_size_t term_size;
  if (terminal_get_size(&term_size) == ASCIICHAT_OK && term_size.cols > 40) {
    term_width = term_size.cols;
  } else {
    const char *cols_env = SAFE_GETENV("COLUMNS");
    if (cols_env) {
      char *endptr;
      errno = 0;
      long cols = strtol(cols_env, &endptr, 10);
      if (*endptr == '\0' && errno == 0 && cols > 40 && cols <= INT_MAX)
        term_width = (int)cols;
      else if (*endptr != '\0' || errno != 0 || cols <= 40)
        log_error("options_config_print_*: Invalid COLUMNS value: %s", cols_env);
    }
  }
 
  // Calculate column width if not provided
  if (max_col_width <= 0) {
    max_col_width = options_config_calculate_max_col_width(config);
  }
 
  // CAP max_col_width: 86 if terminal wide, otherwise 45 for narrow first column
  int max_col_cap = (term_width > 170) ? 86 : 45;
  if (max_col_width > max_col_cap) {
    max_col_width = max_col_cap;
  }
 
  // Determine if this is binary-level help
  // Discovery mode IS the binary-level help (shows binary options + discovery options)
  // Other modes show only mode-specific options
  bool for_binary_help = (mode == MODE_DISCOVERY);
  // Build list of unique groups in order of first appearance
  const char **unique_groups = SAFE_MALLOC(config->num_descriptors * sizeof(const char *), const char **);
  size_t num_unique_groups = 0;
 
  // For binary-level help, we now use a two-pass system to order groups,
  // ensuring binary-level option groups appear before discovery-mode groups.
  if (for_binary_help) {
    // Pass 1: Add GENERAL first, then LOGGING if present
    bool general_added = false;
    bool logging_added = false;
    for (size_t i = 0; i < config->num_descriptors; i++) {
      const option_descriptor_t *desc = &config->descriptors[i];
      if (desc->group) {
        if (!general_added && strcmp(desc->group, "GENERAL") == 0) {
          unique_groups[num_unique_groups++] = "GENERAL";
          general_added = true;
        }
        if (!logging_added && strcmp(desc->group, "LOGGING") == 0) {
          unique_groups[num_unique_groups++] = "LOGGING";
          logging_added = true;
        }
        if (general_added && logging_added) {
          break;
        }
      }
    }
 
    // Pass 2: Collect all other groups that apply for binary help (all modes), if not already added.
    for (size_t i = 0; i < config->num_descriptors; i++) {
      const option_descriptor_t *desc = &config->descriptors[i];
      // An option applies if option_applies_to_mode says so for binary help (which checks OPTION_MODE_ALL)
      if (option_applies_to_mode(desc, mode, for_binary_help) && desc->group) {
        // Skip GENERAL and LOGGING groups if we already added them (for binary help)
        if (strcmp(desc->group, "GENERAL") == 0 || strcmp(desc->group, "LOGGING") == 0) {
          continue;
        }
 
        bool group_exists = false;
        for (size_t j = 0; j < num_unique_groups; j++) {
          if (strcmp(unique_groups[j], desc->group) == 0) {
            group_exists = true;
            break;
          }
        }
        if (!group_exists) {
          unique_groups[num_unique_groups++] = desc->group;
        }
      } else if (desc->group) {
      }
    }
  } else {
    // Original logic for other modes
    for (size_t i = 0; i < config->num_descriptors; i++) {
      const option_descriptor_t *desc = &config->descriptors[i];
      if (option_applies_to_mode(desc, mode, for_binary_help) && desc->group) {
        bool group_exists = false;
        for (size_t j = 0; j < num_unique_groups; j++) {
          if (strcmp(unique_groups[j], desc->group) == 0) {
            group_exists = true;
            break;
          }
        }
        if (!group_exists) {
          unique_groups[num_unique_groups++] = desc->group;
        }
      }
    }
  }
 
  // Print options grouped by category
  for (size_t gi = 0; gi < num_unique_groups; gi++) {
    const char *current_group = unique_groups[gi];
    // Add newline before each group except the first
    if (gi > 0) {
      fprintf(stream, "\n");
    }
    fprintf(stream, "%s\n", colored_string(LOG_COLOR_DEBUG, current_group));
 
    for (size_t i = 0; i < config->num_descriptors; i++) {
      const option_descriptor_t *desc = &config->descriptors[i];
      if (!option_applies_to_mode(desc, mode, for_binary_help) || !desc->group ||
          strcmp(desc->group, current_group) != 0) {
        continue;
      }
 
      // Build option string (flag part) with separate coloring for short and long flags
      char colored_option_str[BUFFER_SIZE_MEDIUM] = "";
      int colored_len = 0;
 
      // Short name and long name with separate coloring
      if (desc->short_name) {
        char short_flag[16];
        safe_snprintf(short_flag, sizeof(short_flag), "-%c", desc->short_name);
        char long_flag[BUFFER_SIZE_SMALL];
        safe_snprintf(long_flag, sizeof(long_flag), "--%s", desc->long_name);
        // Color short flag, plain comma-space, color long flag
        colored_len +=
            safe_snprintf(colored_option_str + colored_len, sizeof(colored_option_str) - colored_len, "%s, %s",
                          colored_string(LOG_COLOR_WARN, short_flag), colored_string(LOG_COLOR_WARN, long_flag));
      } else {
        char long_flag[BUFFER_SIZE_SMALL];
        safe_snprintf(long_flag, sizeof(long_flag), "--%s", desc->long_name);
        colored_len += safe_snprintf(colored_option_str + colored_len, sizeof(colored_option_str) - colored_len, "%s",
                                     colored_string(LOG_COLOR_WARN, long_flag));
      }
 
      // Value placeholder (colored green)
      if (desc->type != OPTION_TYPE_BOOL && desc->type != OPTION_TYPE_ACTION) {
        colored_len += safe_snprintf(colored_option_str + colored_len, sizeof(colored_option_str) - colored_len, " ");
        const char *placeholder = get_option_help_placeholder_str(desc);
        if (placeholder[0] != '\0') {
          colored_len += safe_snprintf(colored_option_str + colored_len, sizeof(colored_option_str) - colored_len, "%s",
                                       colored_string(LOG_COLOR_INFO, placeholder));
        }
      }
 
      // Build description with defaults and env vars
      char desc_str[1024] = "";
      int desc_len = 0;
 
      if (desc->help_text) {
        desc_len += safe_snprintf(desc_str + desc_len, sizeof(desc_str) - desc_len, "%s", desc->help_text);
      }
 
      // Skip adding default if the description already mentions it
      bool description_has_default =
          desc->help_text && (strstr(desc->help_text, "(default:") || strstr(desc->help_text, "=default)"));
 
      if (desc->default_value && !description_has_default) {
        char default_buf[256];
        int default_len = format_option_default_value_str(desc, default_buf, sizeof(default_buf));
        if (default_len > 0) {
          desc_len +=
              safe_snprintf(desc_str + desc_len, sizeof(desc_str) - desc_len, " (%s %s)",
                            colored_string(LOG_COLOR_FATAL, "default:"), colored_string(LOG_COLOR_FATAL, default_buf));
        }
      }
 
      if (desc->required) {
        desc_len += safe_snprintf(desc_str + desc_len, sizeof(desc_str) - desc_len, " [REQUIRED]");
      }
 
      layout_print_two_column_row(stream, colored_option_str, desc_str, max_col_width, term_width, 2);
    }
  }
 
  // Cleanup
  SAFE_FREE(unique_groups);
}

References ASCIICHAT_OK, BUFFER_SIZE_MEDIUM, BUFFER_SIZE_SMALL, colored_string(), terminal_size_t::cols, option_descriptor_t::default_value, options_config_t::descriptors, errno, ERROR_INVALID_PARAM, format_option_default_value_str(), get_option_help_placeholder_str(), option_descriptor_t::group, option_descriptor_t::help_text, layout_print_two_column_row(), LOG_COLOR_DEBUG, LOG_COLOR_FATAL, LOG_COLOR_INFO, LOG_COLOR_WARN, log_error, option_descriptor_t::long_name, MODE_DISCOVERY, options_config_t::num_descriptors, option_applies_to_mode(), OPTION_TYPE_ACTION, OPTION_TYPE_BOOL, options_config_calculate_max_col_width(), option_descriptor_t::required, SAFE_FREE, SAFE_GETENV, SAFE_MALLOC, safe_snprintf(), SET_ERRNO, option_descriptor_t::short_name, terminal_get_size(), and option_descriptor_t::type.

Referenced by options_config_print_options_sections(), and options_print_help_for_mode().

◆ options_config_print_usage()

void options_config_print_usage	(	const options_config_t *	config,
		FILE *	stream
	)

Print usage/help text.

Generates formatted help with grouped options.

Parameters

config	Options configuration
stream	Output stream (stdout or stderr)

Definition at line 706 of file help.c.

                                                                              {
  if (!config || !stream)
    return;
 
  // Detect terminal width from COLUMNS env var or use default
  int term_width = 80;
  const char *cols_env = SAFE_GETENV("COLUMNS");
  if (cols_env) {
    char *endptr;
    errno = 0;
    long cols = strtol(cols_env, &endptr, 10);
    if (*endptr == '\0' && errno == 0 && cols > 40 && cols <= INT_MAX)
      term_width = (int)cols;
    else if (*endptr != '\0' || errno != 0 || cols <= 40)
      log_error("options_config_print_binary_help: Invalid COLUMNS value: %s", cols_env);
  }
 
  // Binary-level help uses MODE_DISCOVERY internally
  asciichat_mode_t mode = MODE_DISCOVERY;
  bool for_binary_help = true;
 
  // Calculate per-section column widths (each section is independent, capped at 75)
  int usage_max_col_width = calculate_section_max_col_width(config, "usage", mode, for_binary_help);
  int modes_max_col_width = calculate_section_max_col_width(config, "modes", mode, for_binary_help);
  int examples_max_col_width = calculate_section_max_col_width(config, "examples", mode, for_binary_help);
  int options_max_col_width = calculate_section_max_col_width(config, "options", mode, for_binary_help);
 
  // Print programmatically generated sections (USAGE, MODES, MODE-OPTIONS, EXAMPLES)
  print_usage_section(config, stream, term_width, usage_max_col_width);
  print_modes_section(config, stream, term_width, modes_max_col_width);
  print_mode_options_section(stream, term_width, 40); // Keep reasonable width for mode-options
  print_examples_section(config, stream, term_width, examples_max_col_width, MODE_SERVER, true);
 
  // Build list of unique groups in order of first appearance
 
  const char **unique_groups = SAFE_MALLOC(config->num_descriptors * sizeof(const char *), const char **);
  size_t num_unique_groups = 0;
 
  for (size_t i = 0; i < config->num_descriptors; i++) {
    const option_descriptor_t *desc = &config->descriptors[i];
    // Filter by mode_bitmask - for binary help, show binary options
    if (!option_applies_to_mode(desc, MODE_SERVER, for_binary_help) || !desc->group) {
      continue;
    }
 
    // Check if this group is already in the list
    bool group_exists = false;
    for (size_t j = 0; j < num_unique_groups; j++) {
      if (unique_groups[j] && strcmp(unique_groups[j], desc->group) == 0) {
        group_exists = true;
        break;
      }
    }
 
    // Add new group to list
    if (!group_exists && num_unique_groups < config->num_descriptors) {
      unique_groups[num_unique_groups++] = desc->group;
    }
  }
 
  // Print options grouped by group name
  for (size_t g = 0; g < num_unique_groups; g++) {
    const char *current_group = unique_groups[g];
    // Only add leading newline for groups after the first one
    if (g > 0) {
      fprintf(stream, "\n");
    }
    fprintf(stream, "%s\n", colored_string(LOG_COLOR_DEBUG, current_group));
 
    // Print all options in this group
    for (size_t i = 0; i < config->num_descriptors; i++) {
      const option_descriptor_t *desc = &config->descriptors[i];
 
      // Skip if not in current group or if doesn't apply to mode
      if (!option_applies_to_mode(desc, MODE_SERVER, for_binary_help) || !desc->group ||
          strcmp(desc->group, current_group) != 0) {
        continue;
      }
 
      // Build option string with separate coloring for short and long flags
      char option_str[BUFFER_SIZE_MEDIUM] = "";
      int option_len = 0;
 
      // Short name and long name with separate coloring
      if (desc->short_name) {
        char short_flag[16];
        safe_snprintf(short_flag, sizeof(short_flag), "-%c", desc->short_name);
        char long_flag[BUFFER_SIZE_SMALL];
        safe_snprintf(long_flag, sizeof(long_flag), "--%s", desc->long_name);
        // Color short flag, plain comma-space, color long flag
        option_len +=
            safe_snprintf(option_str + option_len, sizeof(option_str) - option_len, "%s, %s",
                          colored_string(LOG_COLOR_WARN, short_flag), colored_string(LOG_COLOR_WARN, long_flag));
      } else {
        char long_flag[BUFFER_SIZE_SMALL];
        safe_snprintf(long_flag, sizeof(long_flag), "--%s", desc->long_name);
        option_len += safe_snprintf(option_str + option_len, sizeof(option_str) - option_len, "%s",
                                    colored_string(LOG_COLOR_WARN, long_flag));
      }
 
      // Value placeholder (colored green)
      if (desc->type != OPTION_TYPE_BOOL && desc->type != OPTION_TYPE_ACTION) {
        option_len += safe_snprintf(option_str + option_len, sizeof(option_str) - option_len, " ");
        const char *placeholder = get_option_help_placeholder_str(desc);
        if (placeholder[0] != '\0') {
          option_len += safe_snprintf(option_str + option_len, sizeof(option_str) - option_len, "%s",
                                      colored_string(LOG_COLOR_INFO, placeholder));
        }
      }
 
      // Build description string (plain text, colors applied when printing)
      char desc_str[BUFFER_SIZE_MEDIUM] = "";
      int desc_len = 0;
 
      if (desc->help_text) {
        desc_len += safe_snprintf(desc_str + desc_len, sizeof(desc_str) - desc_len, "%s", desc->help_text);
      }
 
      // Skip adding default if the description already mentions it
      bool description_has_default =
          desc->help_text && (strstr(desc->help_text, "(default:") || strstr(desc->help_text, "=default)"));
 
      if (desc->default_value && !description_has_default) {
        char default_buf[256];
        int default_len = format_option_default_value_str(desc, default_buf, sizeof(default_buf));
        if (default_len > 0) {
          desc_len +=
              safe_snprintf(desc_str + desc_len, sizeof(desc_str) - desc_len, " (%s %s)",
                            colored_string(LOG_COLOR_FATAL, "default:"), colored_string(LOG_COLOR_FATAL, default_buf));
        }
      }
 
      if (desc->required) {
        desc_len += safe_snprintf(desc_str + desc_len, sizeof(desc_str) - desc_len, " [REQUIRED]");
      }
 
      // Use layout function with section-specific column width for consistent alignment
      // option_str already contains colored_string() results, so pass it directly
      layout_print_two_column_row(stream, option_str, desc_str, options_max_col_width, term_width, 2);
    }
  }
 
  // Cleanup
  SAFE_FREE(unique_groups);
 
  fprintf(stream, "\n");
}

References BUFFER_SIZE_MEDIUM, BUFFER_SIZE_SMALL, colored_string(), option_descriptor_t::default_value, options_config_t::descriptors, errno, format_option_default_value_str(), get_option_help_placeholder_str(), option_descriptor_t::group, option_descriptor_t::help_text, layout_print_two_column_row(), LOG_COLOR_DEBUG, LOG_COLOR_FATAL, LOG_COLOR_INFO, LOG_COLOR_WARN, log_error, option_descriptor_t::long_name, MODE_DISCOVERY, MODE_SERVER, options_config_t::num_descriptors, option_applies_to_mode(), OPTION_TYPE_ACTION, OPTION_TYPE_BOOL, option_descriptor_t::required, SAFE_FREE, SAFE_GETENV, SAFE_MALLOC, safe_snprintf(), option_descriptor_t::short_name, and option_descriptor_t::type.

◆ options_config_print_usage_section()

void options_config_print_usage_section	(	const options_config_t *	config,
		FILE *	stream
	)

Print only the USAGE section.

Prints just the USAGE section. Useful for inserting other content (like positional argument examples) between USAGE and other sections.

Parameters

config	Options configuration
stream	Output stream (stdout or stderr)

Splits usage printing from other sections to allow custom content (like positional argument examples) to be inserted between USAGE and other sections.

Definition at line 860 of file help.c.

                                                                                      {
  if (!config || !stream)
    return;
 
  // Detect terminal width from COLUMNS env var or use default
  int term_width = 80;
  const char *cols_env = SAFE_GETENV("COLUMNS");
  if (cols_env) {
    char *endptr;
    errno = 0;
    long cols = strtol(cols_env, &endptr, 10);
    if (*endptr == '\0' && errno == 0 && cols > 40 && cols <= INT_MAX)
      term_width = (int)cols;
    else if (*endptr != '\0' || errno != 0 || cols <= 40)
      log_error("options_config_print_binary_help: Invalid COLUMNS value: %s", cols_env);
  }
 
  // Calculate global max column width across all sections for consistent alignment
  int max_col_width = options_config_calculate_max_col_width(config);
 
  // Print only USAGE section
  print_usage_section(config, stream, term_width, max_col_width);
}

References errno, log_error, options_config_calculate_max_col_width(), and SAFE_GETENV.

◆ options_config_set_defaults()

asciichat_error_t options_config_set_defaults	(	const options_config_t *	config,
		void *	options_struct
	)

Set default values in options struct.

Sets defaults from descriptors, checking environment variables for options with env_var_name set.

Parameters

config	Options configuration
options_struct	Options struct to initialize

Returns: ASCIICHAT_OK on success, error code on failure

Definition at line 1400 of file builder.c.

                                                                                                    {
  if (!config || !options_struct) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Config or options struct is NULL");
  }
 
  char *base = (char *)options_struct;
 
  for (size_t i = 0; i < config->num_descriptors; i++) {
    const option_descriptor_t *desc = &config->descriptors[i];
    void *field = base + desc->offset;
 
    // Check environment variable first (primary)
    const char *env_value = NULL;
    if (desc->env_var_name) {
      env_value = SAFE_GETENV(desc->env_var_name);
    }
    // Check shorter alias names as fallback if primary not set
    if (!env_value) {
      if (desc->env_var_name && strcmp(desc->env_var_name, "ASCII_CHAT_PORT") == 0) {
        env_value = SAFE_GETENV("PORT");
      } else if (desc->env_var_name && strcmp(desc->env_var_name, "ASCII_CHAT_WEBSOCKET_PORT") == 0) {
        env_value = SAFE_GETENV("WS_PORT");
      }
    }
 
    // Use handler registry to apply environment variables and defaults
    if (desc->type >= 0 && desc->type < (int)(NUM_OPTION_TYPES)) {
      if (g_builder_handlers[desc->type].apply_env) {
        g_builder_handlers[desc->type].apply_env(field, env_value, desc);
      }
    } else if (desc->type == OPTION_TYPE_CALLBACK && desc->parse_fn && desc->default_value) {
      // Special handling for callbacks with parse_fn
      char *error_msg = NULL;
      desc->parse_fn(NULL, field, &error_msg);
      if (error_msg) {
        free(error_msg);
      }
    }
  }
 
  return ASCIICHAT_OK;
}

References option_builder_handler_t::apply_env, ASCIICHAT_OK, option_descriptor_t::default_value, options_config_t::descriptors, option_descriptor_t::env_var_name, ERROR_INVALID_PARAM, g_builder_handlers, options_config_t::num_descriptors, NUM_OPTION_TYPES, option_descriptor_t::offset, OPTION_TYPE_CALLBACK, option_descriptor_t::parse_fn, SAFE_GETENV, SET_ERRNO, and option_descriptor_t::type.

Referenced by options_init().

◆ options_config_validate()

asciichat_error_t options_config_validate	(	const options_config_t *	config,
		const void *	options_struct,
		char **	error_message
	)

Validate options struct.

Checks:

Required fields are set
Dependencies are satisfied
Custom validators pass

Parameters

config	Options configuration
options_struct	Options struct to validate
error_message	Optional: receives detailed error message (must free)

Returns: ASCIICHAT_OK if valid, error code otherwise

Definition at line 1840 of file builder.c.

                                                                {
  if (!config || !options_struct) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Config or options struct is NULL");
  }
 
  const char *base = (const char *)options_struct;
 
  // Check required fields
  for (size_t i = 0; i < config->num_descriptors; i++) {
    const option_descriptor_t *desc = &config->descriptors[i];
    if (!desc->required)
      continue;
 
    const void *field = base + desc->offset;
    // Use handler registry to check if option is set (for required field validation)
    bool is_set = true;
    if (desc->type >= 0 && desc->type < (int)(NUM_OPTION_TYPES)) {
      if (g_builder_handlers[desc->type].is_set) {
        is_set = g_builder_handlers[desc->type].is_set(field, desc);
      }
    }
 
    if (!is_set) {
      if (error_message) {
        int asprintf_result;
        if (desc->env_var_name) {
          asprintf_result = asprintf(error_message, "Required option --%s is not set (set %s env var or use --%s)",
                                     desc->long_name, desc->env_var_name, desc->long_name);
        } else {
          asprintf_result = asprintf(error_message, "Required option --%s is not set", desc->long_name);
        }
        if (asprintf_result < 0) {
          log_error("Failed to format error message for missing required option --%s", desc->long_name);
          *error_message = NULL;
        }
      }
      return ERROR_USAGE;
    }
  }
 
  // Check dependencies
  for (size_t i = 0; i < config->num_dependencies; i++) {
    const option_dependency_t *dep = &config->dependencies[i];
 
    bool option_is_set = is_option_set(config, options_struct, dep->option_name);
    bool depends_is_set = is_option_set(config, options_struct, dep->depends_on);
 
    switch (dep->type) {
    case DEPENDENCY_REQUIRES:
      if (option_is_set && !depends_is_set) {
        if (error_message) {
          if (dep->error_message) {
            *error_message = platform_strdup(dep->error_message);
          } else {
            int asprintf_result =
                asprintf(error_message, "Option --%s requires --%s to be set", dep->option_name, dep->depends_on);
            if (asprintf_result < 0) {
              log_error("Failed to format error message for option dependency: --%s requires --%s", dep->option_name,
                        dep->depends_on);
              *error_message = NULL;
            }
          }
        }
        return ERROR_USAGE;
      }
      break;
 
    case DEPENDENCY_CONFLICTS:
      if (option_is_set && depends_is_set) {
        if (error_message) {
          if (dep->error_message) {
            *error_message = platform_strdup(dep->error_message);
          } else {
            int asprintf_result =
                asprintf(error_message, "Option --%s conflicts with --%s", dep->option_name, dep->depends_on);
            if (asprintf_result < 0) {
              log_error("Failed to format error message for option conflict: --%s conflicts with --%s",
                        dep->option_name, dep->depends_on);
              *error_message = NULL;
            }
          }
        }
        return ERROR_USAGE;
      }
      break;
 
    case DEPENDENCY_IMPLIES:
      // Implies is handled during parsing, not validation
      break;
    }
  }
 
  // Run custom validators
  for (size_t i = 0; i < config->num_descriptors; i++) {
    const option_descriptor_t *desc = &config->descriptors[i];
    if (!desc->validate)
      continue;
 
    char *custom_error = NULL;
    if (!desc->validate(options_struct, &custom_error)) {
      if (error_message) {
        *error_message = custom_error;
      } else {
        free(custom_error);
      }
      return ERROR_USAGE;
    }
  }
 
  // Cross-field validation: Check for conflicting color options
  // Cannot use --color with --color-mode none
  const options_t *opts = (const options_t *)options_struct;
  if (opts->color && opts->color_mode == TERM_COLOR_NONE) {
    if (error_message) {
      int asprintf_result =
          asprintf(error_message, "Option --color cannot be used with --color-mode=none (conflicting color settings)");
      if (asprintf_result < 0) {
        log_error("Failed to format error message for color option conflict");
        *error_message = NULL;
      }
    }
    return ERROR_USAGE;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, asprintf, options_state::color, options_state::color_mode, options_config_t::dependencies, DEPENDENCY_CONFLICTS, DEPENDENCY_IMPLIES, DEPENDENCY_REQUIRES, option_dependency_t::depends_on, options_config_t::descriptors, option_descriptor_t::env_var_name, ERROR_INVALID_PARAM, option_dependency_t::error_message, ERROR_USAGE, g_builder_handlers, is_option_set(), option_builder_handler_t::is_set, is_set, log_error, option_descriptor_t::long_name, options_config_t::num_dependencies, options_config_t::num_descriptors, NUM_OPTION_TYPES, option_descriptor_t::offset, option_dependency_t::option_name, platform_strdup(), option_descriptor_t::required, SET_ERRNO, TERM_COLOR_NONE, option_descriptor_t::type, option_dependency_t::type, and option_descriptor_t::validate.

Referenced by validate_options_and_report().

◆ options_format_default_value()

int options_format_default_value	(	option_type_t	type,
		const void *	default_value,
		char *	buf,
		size_t	bufsize
	)

Format option default value to string.

Formats default value according to option type:

BOOL: "true" or "false"
INT: "%d" format
STRING: raw string (caller applies escaping if needed)
DOUBLE: "%.2f" format

Parameters

type	Option type enum value
default_value	Pointer to default value (type-specific)
buf	Output buffer
bufsize	Size of output buffer

Returns: Number of characters written, or 0 on error

Definition at line 576 of file options/common.c.

                                                                                                           {
  if (!default_value || !buf || bufsize == 0) {
    return 0;
  }
 
  switch (type) {
  case OPTION_TYPE_BOOL:
    return safe_snprintf(buf, bufsize, "%s", *(const bool *)default_value ? "true" : "false");
  case OPTION_TYPE_INT: {
    int int_val = 0;
    memcpy(&int_val, default_value, sizeof(int));
    return safe_snprintf(buf, bufsize, "%d", int_val);
  }
  case OPTION_TYPE_STRING:
    return safe_snprintf(buf, bufsize, "%s", *(const char *const *)default_value);
  case OPTION_TYPE_DOUBLE: {
    double double_val = 0.0;
    memcpy(&double_val, default_value, sizeof(double));
    return safe_snprintf(buf, bufsize, "%.2f", double_val);
  }
  default:
    // OPTION_TYPE_CALLBACK and OPTION_TYPE_ACTION don't have defaults to display
    return 0;
  }
}

References OPTION_TYPE_BOOL, OPTION_TYPE_DOUBLE, OPTION_TYPE_INT, OPTION_TYPE_STRING, and safe_snprintf().

Referenced by format_option_default_value_str(), and manpage_content_generate_options().

◆ options_get_type_placeholder()

const char * options_get_type_placeholder ( option_type_t type )

Get placeholder string for option type.

Returns standardized placeholder strings for use in help text and man pages:

INT/DOUBLE → "NUM"
STRING → "STR"
CALLBACK → "VAL"
BOOL/ACTION → "" (empty string)

Parameters

type	Option type enum value

Returns: Pointer to string literal (never NULL, may be empty)

Definition at line 558 of file options/common.c.

                                                             {
  switch (type) {
  case OPTION_TYPE_INT:
    return "INTEGER";
  case OPTION_TYPE_DOUBLE:
    return "NUMBER";
  case OPTION_TYPE_STRING:
    return "STRING";
  case OPTION_TYPE_CALLBACK:
    return "VALUE";
  case OPTION_TYPE_BOOL:
    return "BOOLEAN";
  case OPTION_TYPE_ACTION:
  default:
    return "";
  }
}

References OPTION_TYPE_ACTION, OPTION_TYPE_BOOL, OPTION_TYPE_CALLBACK, OPTION_TYPE_DOUBLE, OPTION_TYPE_INT, and OPTION_TYPE_STRING.

Referenced by get_option_help_placeholder_str(), and manpage_content_generate_options().

◆ options_preset_unified()

options_config_t * options_preset_unified	(	const char *	program_name,
		const char *	description
	)

Get binary-level options preset.

Binary options are parsed BEFORE mode selection. Includes: –help, –version, –log-file, –log-level, etc.

Parameters

program_name	Optional program name (defaults to "ascii-chat")
description	Optional program description

Returns: Preset config (caller must free after use)

Get binary-level options preset.

This is the single source of truth for all options. Each option has a mode_bitmask indicating which modes it applies to. The config includes all options, and validation happens after parsing based on detected mode.

Definition at line 51 of file presets.c.

                                                                                            {
  options_builder_t *b = options_builder_create(sizeof(options_t));
  if (!b) {
    SET_ERRNO(ERROR_MEMORY, "Failed to create options builder");
    return NULL;
  }
 
  b->program_name = program_name ? program_name : "ascii-chat";
  b->description = description ? description : "Video chat in your terminal";
 
  // Add ALL options from registry (binary + all modes)
  asciichat_error_t err = options_registry_add_all_to_builder(b);
  if (err != ASCIICHAT_OK) {
    options_builder_destroy(b);
    SET_ERRNO(err, "Failed to add all options to builder");
    return NULL;
  }
 
  // Add positional arguments for each mode
  // These allow parsing of positional arguments like "192.168.1.1" for client mode
  // and "[bind-address]" for server mode
 
  // Generate random session strings for examples
  // Use static buffers so they persist after the function returns
  static char session_buf1[SESSION_STRING_BUFFER_SIZE];
  static char session_buf2[SESSION_STRING_BUFFER_SIZE];
  static char session_buf3[SESSION_STRING_BUFFER_SIZE];
  static char session_buf4[SESSION_STRING_BUFFER_SIZE];
  static char session_buf5[SESSION_STRING_BUFFER_SIZE];
  static char session_buf6[SESSION_STRING_BUFFER_SIZE];
  static char session_buf7[SESSION_STRING_BUFFER_SIZE];
  static char session_buf8[SESSION_STRING_BUFFER_SIZE];
  static char session_buf9[SESSION_STRING_BUFFER_SIZE];
  static char session_buf10[SESSION_STRING_BUFFER_SIZE];
 
  // Fallback strings if generation fails
  char *example_session_string1 = "adjective-noun-noun";
  char *example_session_string2 = "adjective-noun-noun";
  char *example_session_string3 = "adjective-noun-noun";
  char *example_session_string4 = "adjective-noun-noun";
  char *example_session_string5 = "adjective-noun-noun";
  char *example_session_string6 = "adjective-noun-noun";
  char *example_session_string7 = "adjective-noun-noun";
  char *example_session_string8 = "adjective-noun-noun";
  char *example_session_string9 = "adjective-noun-noun";
  char *example_session_string10 = "adjective-noun-noun";
 
  // Generate session strings for examples (sodium_init called as needed by acds_string_generate)
  acds_string_generate(session_buf1, sizeof(session_buf1));
  if (session_buf1[0] != '\0') {
    example_session_string1 = session_buf1;
  }
  acds_string_generate(session_buf2, sizeof(session_buf2));
  if (session_buf2[0] != '\0') {
    example_session_string2 = session_buf2;
  }
  acds_string_generate(session_buf3, sizeof(session_buf3));
  if (session_buf3[0] != '\0') {
    example_session_string3 = session_buf3;
  }
  acds_string_generate(session_buf4, sizeof(session_buf4));
  if (session_buf4[0] != '\0') {
    example_session_string4 = session_buf4;
  }
  acds_string_generate(session_buf5, sizeof(session_buf5));
  if (session_buf5[0] != '\0') {
    example_session_string5 = session_buf5;
  }
  acds_string_generate(session_buf6, sizeof(session_buf6));
  if (session_buf6[0] != '\0') {
    example_session_string6 = session_buf6;
  }
  acds_string_generate(session_buf7, sizeof(session_buf7));
  if (session_buf7[0] != '\0') {
    example_session_string7 = session_buf7;
  }
  acds_string_generate(session_buf8, sizeof(session_buf8));
  if (session_buf8[0] != '\0') {
    example_session_string8 = session_buf8;
  }
  acds_string_generate(session_buf9, sizeof(session_buf9));
  if (session_buf9[0] != '\0') {
    example_session_string9 = session_buf9;
  }
  acds_string_generate(session_buf10, sizeof(session_buf10));
  if (session_buf10[0] != '\0') {
    example_session_string10 = session_buf10;
  }
 
  // Build session string examples dynamically for discovery mode
  // These appear at the beginning of the examples section, right after "start new session"
  static char example_buf1[SESSION_STRING_BUFFER_SIZE];
  static char example_buf2[SESSION_STRING_BUFFER_SIZE];
  static char example_buf3[SESSION_STRING_BUFFER_SIZE];
  static char example_buf4[SESSION_STRING_BUFFER_SIZE];
  static char example_buf5[SESSION_STRING_BUFFER_SIZE];
  static char example_buf6[SESSION_STRING_BUFFER_SIZE];
  static char example_buf7[SESSION_STRING_BUFFER_SIZE];
  static char example_buf8[SESSION_STRING_BUFFER_SIZE];
  static char example_buf9[SESSION_STRING_BUFFER_SIZE];
  static char example_buf10[SESSION_STRING_BUFFER_SIZE];
 
  safe_snprintf(example_buf1, sizeof(example_buf1), "%s", example_session_string1);
  safe_snprintf(example_buf2, sizeof(example_buf2), "%s", example_session_string2);
  safe_snprintf(example_buf3, sizeof(example_buf3), "%s", example_session_string3);
  safe_snprintf(example_buf4, sizeof(example_buf4), "%s", example_session_string4);
  safe_snprintf(example_buf5, sizeof(example_buf5), "%s", example_session_string5);
  safe_snprintf(example_buf6, sizeof(example_buf6), "%s", example_session_string6);
  safe_snprintf(example_buf7, sizeof(example_buf7), "%s", example_session_string7);
  safe_snprintf(example_buf8, sizeof(example_buf8), "%s", example_session_string8);
  safe_snprintf(example_buf9, sizeof(example_buf9), "%s", example_session_string9);
  safe_snprintf(example_buf10, sizeof(example_buf10), "%s", example_session_string10);
 
  // Client mode: [address] - can be IP, hostname, hostname:port, or WebSocket URL
  static const char *client_examples[] = {"localhost",
                                          "ascii-chat.com",
                                          "0.0.0.0",
                                          "::",
                                          "192.168.1.1:8080",
                                          "[2001:db8::42]:27224",
                                          "233.27.48.203:27224",
                                          "62fb:759e:2bce:21d7:9e5d:13f8:3c11:5084:27224",
                                          "ws://example.com:8080",
                                          "wss://secure.example.com:443"};
  // Discovery mode: [session-string] - session string or empty to start new session
  // Use simple static examples for positional arguments section (dynamic strings shown in examples section)
  static const char *discovery_examples[] = {
      "(empty/unset) start new session. generates a session string to give someone to connect to you.",
      (const char *)example_buf7, (const char *)example_buf8, (const char *)example_buf9, (const char *)example_buf10};
  options_builder_add_positional(
      b, "session-string", "(optional) Random three words in format adjective-noun-noun that connect you to a call.",
      false, "POSITIONAL ARGUMENTS", discovery_examples, ARRAY_SIZE(discovery_examples), OPTION_MODE_DISCOVERY,
      parse_client_address);
 
  // Server and Discovery Service modes: [bind-address] [bind-address] - can be IP or hostname, up to 2 for IPv4/IPv6
  static const char *server_examples[] = {"localhost",
                                          "ascii-chat.com",
                                          "0.0.0.0",
                                          "::",
                                          "234.50.188.236",
                                          "9631:54e7:5b5c:80dc:0f62:1f01:7ccf:5512",
                                          "105.137.19.11 3a08:7276:ccb4:7b31:e934:5330:9b3a:9598",
                                          "::1 192.168.1.100"};
  options_builder_add_positional(b, "bind-address",
                                 "(optional) 0-2 addresses for a server to bind to, one IPv4 and the other IPv6.",
                                 false, "POSITIONAL ARGUMENTS", server_examples, ARRAY_SIZE(server_examples),
                                 OPTION_MODE_SERVER | OPTION_MODE_DISCOVERY_SVC, parse_server_bind_address);
 
  options_builder_add_positional(b, "address", "(optional) Server address for client to connect to.", false,
                                 "POSITIONAL ARGUMENTS", client_examples, ARRAY_SIZE(client_examples),
                                 OPTION_MODE_CLIENT, parse_client_address);
 
  // Mirror mode: [file|url] - file path or URL to stream
  static const char *mirror_media_examples[] = {"/path/to/video.mp4", "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
                                                "https://example.com/stream.m3u8"};
  options_builder_add_positional(b, "file|url",
                                 "(optional) Media file path or URL to stream. If omitted, uses webcam. "
                                 "Cannot be combined with --file or --url.",
                                 false, "POSITIONAL ARGUMENTS", mirror_media_examples,
                                 ARRAY_SIZE(mirror_media_examples), OPTION_MODE_MIRROR, parse_mirror_media);
 
  // Add usage lines for all modes
  options_builder_add_usage(b, NULL, NULL, true, "Start a new session (share the session string)");
  options_builder_add_usage(b, NULL, "<session-string>", true, "Join an existing session");
  options_builder_add_usage(b, NULL, "<mode>", true, "Run in a specific mode");
  options_builder_add_usage(b, "server", "[bind-address] [bind-address]", true,
                            "Start server (can specify 0-2 bind addresses, one IPv4 and the other IPv6)");
  options_builder_add_usage(b, "client", "[address]", true, "Connect to server (defaults to localhost:27224)");
  options_builder_add_usage(b, "mirror", "[file|url]", true, "View local webcam or media file or URL as ASCII art");
  options_builder_add_usage(b, "discovery-service", "[bind-address] [bind-address]", true,
                            "Start discovery service (can specify 0-2 bind addresses, one IPv4 and the other IPv6)");
  options_builder_add_usage(b, NULL, "[mode] --help", false, "Show help for a specific mode");
 
  // Add examples for binary-level help and discovery mode
  options_builder_add_example(b, OPTION_MODE_BINARY, NULL, "Start new session (share the session string)", false);
  options_builder_add_example(b, OPTION_MODE_BINARY, example_buf1, "Join a session using the session string", true);
 
  // Build combined examples with session string + flags
  static char combined_buf1[256];
  static char combined_buf2[256];
  static char combined_buf3[256];
  static char combined_buf4[256];
  static char combined_buf5[256];
  safe_snprintf(combined_buf1, sizeof(combined_buf1), "%s --file video.mp4", example_buf3);
  safe_snprintf(combined_buf2, sizeof(combined_buf2), "%s --url 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'",
                example_buf4);
  safe_snprintf(combined_buf3, sizeof(combined_buf3), "%s -f -", example_buf5);
  safe_snprintf(combined_buf4, sizeof(combined_buf4), "%s --palette-chars '@%%#*+=-:. '", example_buf6);
  safe_snprintf(combined_buf5, sizeof(combined_buf5), "%s --discovery-service --discovery-service-port 27225",
                example_buf2);
 
  options_builder_add_example(b, OPTION_MODE_BINARY, combined_buf1, "Join session and stream from local video file",
                              false);
  options_builder_add_example(b, OPTION_MODE_BINARY, combined_buf2, "Join session and stream from YouTube video",
                              false);
  options_builder_add_example(b, OPTION_MODE_BINARY, combined_buf3, "Join session and stream media from stdin", false);
  options_builder_add_example(b, OPTION_MODE_BINARY, combined_buf4, "Join session with custom ASCII palette characters",
                              false);
  options_builder_add_example(b, OPTION_MODE_BINARY, combined_buf5, "Join session via custom discovery server", false);
 
  // Add examples for server-like modes (server + discovery-service)
  options_builder_add_example(b, OPTION_MODE_SERVER_LIKE, NULL, "Start on localhost (127.0.0.1 and ::1)", false);
  options_builder_add_example(b, OPTION_MODE_SERVER_LIKE, "0.0.0.0", "Start on all IPv4 interfaces", false);
  options_builder_add_example(b, OPTION_MODE_SERVER_LIKE,
                              "0.0.0.0 ::", "Start on all IPv4 and IPv6 interfaces (dual-stack)", false);
  options_builder_add_example(b, OPTION_MODE_SERVER_LIKE, "--port 8080", "Start on custom port", false);
 
  // Server-specific examples
  options_builder_add_example(b, OPTION_MODE_SERVER, "--key ~/.ssh/id_ed25519 --discovery",
                              "Start with identity key and discovery registration", false);
 
  // Add examples for client-like modes (client + mirror)
  options_builder_add_example(b, OPTION_MODE_CLIENT_LIKE, "--url 'https://youtu.be/7ynHVGCehoM'",
                              "Stream from YouTube URL (also supports RTSP, HTTP, and HTTPS URLs)", false);
  options_builder_add_example(b, OPTION_MODE_CLIENT_LIKE, "--url 'https://www.twitch.tv/ludwig'",
                              "Stream Ludwig from videogames on Twitch", false);
  options_builder_add_example(b, OPTION_MODE_CLIENT_LIKE, "-f video.mp4", "Stream from local video file", false);
  options_builder_add_example(b, OPTION_MODE_CLIENT_LIKE, "--palette-chars '@%#*+=-:. '",
                              "Custom palette characters to use. UTF-8 is allowed.", false);
  options_builder_add_example(
      b, OPTION_MODE_CLIENT_LIKE, "--snapshot",
      "Print ascii art for --snapshot-delay's value of seconds then print the last frame and exit. "
      "In snapshot mode, --width, --height, and --color are NOT autodetected when piping stdin in or redirecting "
      "output.",
      false);
  options_builder_add_example(b, OPTION_MODE_CLIENT_LIKE, "--color-filter cyan --palette cool",
                              "Apply cyan color filter and cool palette", false);
 
  // Client-specific examples
  options_builder_add_example(b, OPTION_MODE_CLIENT, "example.com", "Connect to remote server", false);
  options_builder_add_example(b, OPTION_MODE_CLIENT, "example.com:8080", "Connect to remote server on custom port",
                              false);
  options_builder_add_example(b, OPTION_MODE_CLIENT, "--color-mode mono --render-mode half-block --width 120",
                              "Connect with custom display options", false);
 
  // Mirror-specific examples (unique to mirror mode)
  options_builder_add_example(
      b, OPTION_MODE_MIRROR, NULL,
      "View the webcam or files or URLs as ASCII art. Like client mode but without network connectivity or a server.",
      false);
  options_builder_add_example(b, OPTION_MODE_MIRROR, "--color-mode mono", "View webcam in black and white", false);
  options_builder_add_example(b, OPTION_MODE_MIRROR, "--color-filter green",
                              "View webcam with green monochromatic color filter", false);
  options_builder_add_example(b, OPTION_MODE_MIRROR, "--matrix --color-filter rainbow",
                              "Matrix rain effect with rainbow colors cycling over 3.5s", false);
  options_builder_add_example(b, OPTION_MODE_MIRROR, "--file '-'",
                              "Stream media from stdin (cat file.gif | ascii-chat mirror -f '-')", false);
  options_builder_add_example_utility(b, OPTION_MODE_MIRROR, "cat video.avi | ascii-chat mirror -f '-' -l -s 00:30",
                                      "Stream .avi from stdin, looped, seeking to 00:30", true);
  options_builder_add_example(b, OPTION_MODE_MIRROR, "--file video.mov --seek 22:10",
                              "Start playback at exactly 22:10 (also works with --url)", false);
  options_builder_add_example(b, OPTION_MODE_MIRROR, "-f 'https://youtu.be/LS9W8SO-Two' -S -D 0 -s 5:12",
                              "Print a single frame from a YouTube video at exactly 5:12 and exit", false);
  options_builder_add_example(b, OPTION_MODE_MIRROR, "-S -D 0 | tee frame.txt | pbcopy",
                              "Capture single ASCII frame to clipboard (macOS) and file", false);
  options_builder_add_example_utility(b, OPTION_MODE_MIRROR, "pbpaste | cat -",
                                      "View ASCII frame from clipboard (macOS)", true);
 
  // Discovery-service specific examples
  options_builder_add_example(b, OPTION_MODE_DISCOVERY_SVC, "--require-server-identity --require-client-identity",
                              "Enforce identity verification for all parties", false);
 
  // Add mode descriptions
  options_builder_add_mode(
      b, "default",
      "When the ascii-chat binary is used without a mode, it operates as either client or server automatically and "
      "uses the discovery-service to make peer connections with session strings");
  options_builder_add_mode(b, "server", "Run as multi-client video chat server");
  options_builder_add_mode(b, "client", "Run as video chat client (connect to server)");
  options_builder_add_mode(b, "mirror", "View local media as ASCII art (no server)");
  options_builder_add_mode(b, "discovery-service", "Secure P2P session signalling");
 
  // Add custom help sections for interactive modes (client, mirror, and discovery)
  options_builder_add_custom_section(b, "KEYBINDINGS",
                                     "Available in ascii-chat client, mirror, and discovery modes. "
                                     "While rendering, press '?' to display a keyboard shortcuts help menu showing:\n"
                                     "  - Available keybindings (?, Space, arrows, m, c, f, r)\n"
                                     "  - Current settings (volume, color mode, audio status, etc.)",
                                     OPTION_MODE_CLIENT_LIKE);
 
  // Add environment variables section (all modes)
  options_builder_add_custom_section(
      b, "ENVIRONMENT",
      "All command-line flags that accept values have corresponding environment variables.\n"
      "  Format: ASCII_CHAT_<FLAG_NAME> where FLAG_NAME is uppercase with hyphens replaced by underscores\n"
      "  Example: --color-filter maps to ASCII_CHAT_COLOR_FILTER\n"
      "\n"
      "  Configuration precedence (lowest to highest):\n"
      "    1. Config file values (~/.ascii-chat/config.toml)\n"
      "    2. Environment variables (ASCII_CHAT_*)\n"
      "    3. Command-line flags (--flag-name)\n"
      "\n"
      "  Additional environment variables are documented in the ascii-chat(1) man page.",
      OPTION_MODE_ALL);
 
  // Add common dependencies (these will be validated after parsing)
  // Note: Dependencies are validated at runtime, so we add them here for documentation
 
  // ============================================================================
  // Media Source Conflicts
  // ============================================================================
  // URL conflicts: --url cannot be used with --file or --loop
  options_builder_add_dependency_conflicts(b, "url", "file",
                                           "Option --url cannot be used with --file (--url takes priority)");
  options_builder_add_dependency_conflicts(
      b, "url", "loop", "Option --url cannot be used with --loop (network streams cannot be looped)");
 
  // ============================================================================
  // Encryption & Authentication Conflicts
  // ============================================================================
  // Cannot use both --encrypt and --no-encrypt
  options_builder_add_dependency_conflicts(b, "no-encrypt", "encrypt", "Cannot use --no-encrypt with --encrypt");
  options_builder_add_dependency_conflicts(b, "no-encrypt", "key",
                                           "Cannot use --no-encrypt with --key (key requires encryption)");
  options_builder_add_dependency_conflicts(b, "no-encrypt", "password",
                                           "Cannot use --no-encrypt with --password (password requires encryption)");
  options_builder_add_dependency_conflicts(
      b, "no-encrypt", "client-keys",
      "Cannot use --no-encrypt with --client-keys (key validation requires encryption)");
  options_builder_add_dependency_conflicts(
      b, "no-encrypt", "server-key", "Cannot use --no-encrypt with --server-key (key validation requires encryption)");
 
  // Cannot use --no-auth with authentication material (--key, --password, --client-keys, --server-key)
  options_builder_add_dependency_conflicts(b, "no-auth", "key",
                                           "Cannot use --no-auth with --key (key requires authentication)");
  options_builder_add_dependency_conflicts(b, "no-auth", "password",
                                           "Cannot use --no-auth with --password (password requires authentication)");
  options_builder_add_dependency_conflicts(
      b, "no-auth", "client-keys", "Cannot use --no-auth with --client-keys (key list requires authentication)");
  options_builder_add_dependency_conflicts(
      b, "no-auth", "server-key", "Cannot use --no-auth with --server-key (verification requires authentication)");
 
  // Cannot use --key with --server-key (both server-side key options)
  options_builder_add_dependency_conflicts(
      b, "key", "server-key",
      "Cannot use --key with --server-key (--key is server identity, --server-key is client-side)");
 
  // ============================================================================
  // Compression Conflicts
  // ============================================================================
  // Cannot use --no-compress with --compression-level
  options_builder_add_dependency_conflicts(b, "no-compress", "compression-level",
                                           "Cannot use --no-compress with --compression-level");
 
  // ============================================================================
  // Audio Encoding Conflicts
  // ============================================================================
  // Cannot use both --encode-audio and --no-encode-audio
  options_builder_add_dependency_conflicts(b, "encode-audio", "no-encode-audio",
                                           "Cannot use both --encode-audio and --no-encode-audio");
 
  // ============================================================================
  // Display & Screen Conflicts
  // ============================================================================
  options_builder_add_dependency_conflicts(b, "waveform", "matrix",
                                           "Option --waveform cannot be used with --matrix");
  options_builder_add_dependency_conflicts(b, "fft", "matrix", "Option --fft cannot be used with --matrix");
  options_builder_add_dependency_conflicts(b, "waveform", "fft",
                                           "Options --waveform and --fft cannot be used together");
  options_builder_add_dependency_conflicts(b, "waveform", "audio",
                                           "Option --waveform requires audio; remove --audio=false");
  options_builder_add_dependency_conflicts(b, "fft", "audio", "Option --fft requires audio; remove --audio=false");
  options_builder_add_dependency_conflicts(b, "waveform", "stretch",
                                           "Option --waveform cannot be used with --stretch");
  options_builder_add_dependency_conflicts(b, "fft", "stretch", "Option --fft cannot be used with --stretch");
 
  // ============================================================================
  // Requirements (dependencies that must be satisfied)
  // ============================================================================
  // --snapshot-delay requires --snapshot
  options_builder_add_dependency_requires(b, "snapshot-delay", "snapshot",
                                          "Option --snapshot-delay requires --snapshot");
 
  // --loop requires --file (can't loop network streams)
  options_builder_add_dependency_requires(b, "loop", "file", "Option --loop requires --file");
 
  const options_config_t *config = options_builder_build(b);
  options_builder_destroy(b);
  return config;
}

◆ options_print_help_for_mode()

void options_print_help_for_mode	(	const options_config_t *	config,
		asciichat_mode_t	mode,
		const char *	program_name,
		const char *	description,
		FILE *	desc
	)

Print help for a specific mode or binary level (unified function)

This is the single unified function for all help output (binary level and all modes). It handles all layout logic, terminal detection, and section printing.

Parameters

config	Options config with all options
mode	Mode to show help for (-1 for binary-level help)
program_name	Full program name (e.g., "ascii-chat server")
description	Brief description
desc	Output file stream

Print help for a specific mode or binary level (unified function)

This is the single unified function for all help output (binary level and all modes). It handles common layout logic, terminal detection, and section printing.

Parameters

config	Options config with all options (binary + all modes)
mode	Mode to show help for (use -1 for binary-level help)
program_name	Full program name with mode (e.g., "ascii-chat server")
description	Brief description of the mode/binary
desc	Output file stream (usually stdout)

Definition at line 1105 of file help.c.

                                                                      {
  if (!config || !desc) {
    if (desc) {
      fprintf(desc, "Error: Failed to create options config\n");
    } else {
      SET_ERRNO(ERROR_INVALID_PARAM, "Config or desc is NULL");
    }
    return;
  }
 
  // Detect terminal width early so we can decide whether to show ASCII art
  int term_width = 80;
  terminal_size_t term_size;
  if (terminal_get_size(&term_size) == ASCIICHAT_OK && term_size.cols > 40) {
    term_width = term_size.cols;
  } else {
    const char *cols_env = SAFE_GETENV("COLUMNS");
    if (cols_env) {
      char *endptr;
      errno = 0;
      long cols = strtol(cols_env, &endptr, 10);
      if (*endptr == '\0' && errno == 0 && cols > 40 && cols <= INT_MAX)
        term_width = (int)cols;
      else if (*endptr != '\0' || errno != 0 || cols <= 40)
        log_error("options_config_print_*: Invalid COLUMNS value: %s", cols_env);
    }
  }
 
  // Print ASCII art logo only if terminal is wide enough (ASCII art is ~52 chars wide)
  if (term_width >= 60) {
    (void)fprintf(desc, "  __ _ ___  ___(_|_)       ___| |__   __ _| |_ \n");
    (void)fprintf(desc, " / _` / __|/ __| | |_____ / __| '_ \\ / _` | __|\n");
    (void)fprintf(desc, "| (_| \\__ \\ (__| | |_____| (__| | | | (_| | |_ \n");
    (void)fprintf(desc, " \\__,_|___/\\___|_|_|      \\___|_| |_|\\__,_|\\__|\n");
    (void)fprintf(desc, "\n");
  }
 
  // Print program name and description (color mode name magenta if it's a mode-specific help)
  if (program_name) {
    const char *space = strchr(program_name, ' ');
    if (space && mode >= 0) {
      // Mode-specific help: color the mode name
      int binary_len = space - program_name;
      (void)fprintf(desc, "%.*s %s - %s\n\n", binary_len, program_name, colored_string(LOG_COLOR_FATAL, space + 1),
                    description);
    } else {
      // Binary-level help: use colored_string for the program name too
      (void)fprintf(desc, "%s - %s\n\n", colored_string(LOG_COLOR_FATAL, program_name), description);
    }
  }
 
  // Print project links
  print_project_links(desc);
  (void)fprintf(desc, "\n");
 
  // Determine if this is binary-level help (called for 'ascii-chat --help')
  // Binary help uses MODE_DISCOVERY as the mode value
  bool for_binary_help = (mode == MODE_DISCOVERY);
 
  // Calculate column widths for USAGE upfront (before printing) for alignment
  int usage_max_col_width = calculate_section_max_col_width(config, "usage", mode, for_binary_help);
  // Use USAGE width for both USAGE and EXAMPLES sections for consistent alignment
  // (don't let long examples push column too far right)
  int usage_examples_col_width = usage_max_col_width;
 
  // Print USAGE section (with section-specific column width and mode filtering)
  fprintf(desc, "%s\n", colored_string(LOG_COLOR_DEBUG, "USAGE"));
  if (config->num_usage_lines > 0) {
    // Get mode name for filtering usage lines
    const char *mode_name = NULL;
    switch (mode) {
    case MODE_SERVER:
      mode_name = "server";
      break;
    case MODE_CLIENT:
      mode_name = "client";
      break;
    case MODE_MIRROR:
      mode_name = "mirror";
      break;
    case MODE_DISCOVERY_SERVICE:
      mode_name = "discovery-service";
      break;
    case MODE_DISCOVERY:
    default:
      mode_name = NULL; // Binary help shows all usage lines
      break;
    }
 
    for (size_t i = 0; i < config->num_usage_lines; i++) {
      const usage_descriptor_t *usage = &config->usage_lines[i];
 
      // Filter usage lines by mode
      if (!for_binary_help) {
        // For mode-specific help, show the current mode's usage line and the generic [mode] --help line
        bool is_current_mode = (usage->mode && mode_name && strcmp(usage->mode, mode_name) == 0);
        bool is_generic_help_line =
            (!usage->mode && usage->positional && strcmp(usage->positional, "[mode] --help") == 0);
 
        if (!is_current_mode && !is_generic_help_line) {
          continue;
        }
      }
 
      char usage_buf[BUFFER_SIZE_MEDIUM];
      int len = 0;
 
      len += safe_snprintf(usage_buf + len, sizeof(usage_buf) - len, "ascii-chat");
 
      // For mode-specific help, use [mode] placeholder when showing --help usage
      if (usage->mode) {
        if (!for_binary_help && usage->positional && strcmp(usage->positional, "--help") == 0) {
          // Mode-specific help: show [mode] --help as generic placeholder
          len +=
              safe_snprintf(usage_buf + len, sizeof(usage_buf) - len, " %s", colored_string(LOG_COLOR_FATAL, "[mode]"));
        } else {
          // Binary help or non-help usage: show actual mode name
          len += safe_snprintf(usage_buf + len, sizeof(usage_buf) - len, " %s",
                               colored_string(LOG_COLOR_FATAL, usage->mode));
        }
      }
 
      if (usage->positional) {
        len += safe_snprintf(usage_buf + len, sizeof(usage_buf) - len, " %s",
                             colored_string(LOG_COLOR_INFO, usage->positional));
      }
 
      if (usage->show_options) {
        const char *options_text =
            (usage->mode && strcmp(usage->mode, "<mode>") == 0) ? "[mode-options...]" : "[options...]";
        len += safe_snprintf(usage_buf + len, sizeof(usage_buf) - len, " %s",
                             colored_string(LOG_COLOR_WARN, options_text));
      }
 
      layout_print_two_column_row(desc, usage_buf, usage->description, usage_examples_col_width, term_width, 0);
    }
  }
  fprintf(desc, "\n");
 
  // Print MODES section (only for binary-level help)
  if (for_binary_help && config->num_modes > 0) {
    int modes_max_col_width = calculate_section_max_col_width(config, "modes", mode, for_binary_help);
    print_modes_section(config, desc, term_width, modes_max_col_width);
  }
 
  // Print positional argument examples (with mode filtering and section-specific column width)
  if (config->num_positional_args > 0) {
    // First, check if any positional args apply to this mode
    option_mode_bitmask_t current_mode_bitmask = 1U << mode;
    bool has_applicable_positional_args = false;
 
    for (size_t pa_idx = 0; pa_idx < config->num_positional_args; pa_idx++) {
      const positional_arg_descriptor_t *pos_arg = &config->positional_args[pa_idx];
 
      // Filter by mode_bitmask (matching the parsing code logic)
      if (pos_arg->mode_bitmask != 0 && !(pos_arg->mode_bitmask & current_mode_bitmask)) {
        continue;
      }
 
      if (pos_arg->section_heading && pos_arg->examples && pos_arg->num_examples > 0) {
        has_applicable_positional_args = true;
        break;
      }
    }
 
    // Only print the section if there are applicable positional args
    if (has_applicable_positional_args) {
      int positional_max_col_width = calculate_section_max_col_width(config, "positional", mode, false);
 
      for (size_t pa_idx = 0; pa_idx < config->num_positional_args; pa_idx++) {
        const positional_arg_descriptor_t *pos_arg = &config->positional_args[pa_idx];
 
        // Filter by mode_bitmask (matching the parsing code logic)
        if (pos_arg->mode_bitmask != 0 && !(pos_arg->mode_bitmask & current_mode_bitmask)) {
          continue;
        }
 
        if (pos_arg->section_heading && pos_arg->examples && pos_arg->num_examples > 0) {
          (void)fprintf(desc, "%s\n", colored_string(LOG_COLOR_DEBUG, pos_arg->section_heading));
 
          for (size_t i = 0; i < pos_arg->num_examples; i++) {
            const char *example = pos_arg->examples[i];
            const char *p = example;
            const char *desc_start = NULL;
 
            while (*p == ' ')
              p++;
            const char *first_part = p;
 
            while (*p && !(*p == ' ' && *(p + 1) == ' '))
              p++;
            int first_len_bytes = (int)(p - first_part);
 
            while (*p == ' ')
              p++;
            if (*p) {
              desc_start = p;
            }
 
            char colored_first_part[256];
            safe_snprintf(colored_first_part, sizeof(colored_first_part), "%.*s", first_len_bytes, first_part);
            char colored_result[512];
            safe_snprintf(colored_result, sizeof(colored_result), "%s",
                          colored_string(LOG_COLOR_INFO, colored_first_part));
 
            layout_print_two_column_row(desc, colored_result, desc_start ? desc_start : "", positional_max_col_width,
                                        term_width, 0);
          }
          (void)fprintf(desc, "\n");
        }
      }
    }
  }
 
  // Print EXAMPLES section (using USAGE column width for alignment)
  print_examples_section(config, desc, term_width, usage_examples_col_width, mode, for_binary_help);
 
  // Print custom sections (after EXAMPLES, before OPTIONS)
  if (config->num_custom_sections > 0) {
    option_mode_bitmask_t current_mode_bitmask = 1U << mode;
    for (size_t i = 0; i < config->num_custom_sections; i++) {
      const custom_section_descriptor_t *section = &config->custom_sections[i];
 
      // Filter by mode_bitmask
      if (section->mode_bitmask != 0 && !(section->mode_bitmask & current_mode_bitmask)) {
        continue;
      }
 
      if (section->heading) {
        fprintf(desc, "%s\n", colored_string(LOG_COLOR_DEBUG, section->heading));
      }
 
      if (section->content) {
        // Special handling for KEYBINDINGS section: colorize keybindings and wrap to 70 chars
        if (section->heading && strcmp(section->heading, "KEYBINDINGS") == 0) {
          // Build colored version with proper keybinding colorization
          char colored_output[2048] = "";
          const char *src = section->content;
          char *dst = colored_output;
          size_t remaining = sizeof(colored_output) - 1;
 
          while (*src && remaining > 0) {
            // Colorize ? that don't end sentences
            if (*src == '?' && *(src + 1) != '\n' && *(src + 1) != '\0') {
              const char *colored = colored_string(LOG_COLOR_FATAL, "?");
              size_t len = strlen(colored);
              if (len <= remaining) {
                memcpy(dst, colored, len);
                dst += len;
                remaining -= len;
                src += 1;
              } else {
                break;
              }
            } else if (strncmp(src, "Space", 5) == 0 &&
                       (src > section->content && (*(src - 1) == ',' || *(src - 1) == ' '))) {
              const char *colored = colored_string(LOG_COLOR_FATAL, "Space");
              size_t len = strlen(colored);
              if (len <= remaining) {
                memcpy(dst, colored, len);
                dst += len;
                remaining -= len;
                src += 5;
              } else {
                break;
              }
            } else if (strncmp(src, "arrows", 6) == 0 &&
                       (src > section->content && (*(src - 1) == ',' || *(src - 1) == ' '))) {
              const char *colored = colored_string(LOG_COLOR_FATAL, "arrows");
              size_t len = strlen(colored);
              if (len <= remaining) {
                memcpy(dst, colored, len);
                dst += len;
                remaining -= len;
                src += 6;
              } else {
                break;
              }
            } else if (*src == 'm' && (src > section->content && (*(src - 1) == ',' || *(src - 1) == ' ')) &&
                       (*(src + 1) == ',' || *(src + 1) == ')')) {
              const char *colored = colored_string(LOG_COLOR_FATAL, "m");
              size_t len = strlen(colored);
              if (len <= remaining) {
                memcpy(dst, colored, len);
                dst += len;
                remaining -= len;
                src += 1;
              } else {
                break;
              }
            } else if (*src == 'c' && (src > section->content && (*(src - 1) == ',' || *(src - 1) == ' ')) &&
                       (*(src + 1) == ',' || *(src + 1) == ')')) {
              const char *colored = colored_string(LOG_COLOR_FATAL, "c");
              size_t len = strlen(colored);
              if (len <= remaining) {
                memcpy(dst, colored, len);
                dst += len;
                remaining -= len;
                src += 1;
              } else {
                break;
              }
            } else if (*src == 'f' && (src > section->content && (*(src - 1) == ',' || *(src - 1) == ' ')) &&
                       (*(src + 1) == ',' || *(src + 1) == ')')) {
              const char *colored = colored_string(LOG_COLOR_FATAL, "f");
              size_t len = strlen(colored);
              if (len <= remaining) {
                memcpy(dst, colored, len);
                dst += len;
                remaining -= len;
                src += 1;
              } else {
                break;
              }
            } else if (*src == 'r' && (src > section->content && (*(src - 1) == ',' || *(src - 1) == ' ')) &&
                       (*(src + 1) == ')')) {
              const char *colored = colored_string(LOG_COLOR_FATAL, "r");
              size_t len = strlen(colored);
              if (len <= remaining) {
                memcpy(dst, colored, len);
                dst += len;
                remaining -= len;
                src += 1;
              } else {
                break;
              }
            } else {
              *dst++ = *src++;
              remaining--;
            }
          }
          *dst = '\0';
          // Print with 2-space indent, wrapping at min(terminal width, 90)
          fprintf(desc, "  ");
          int keybindings_wrap_width = term_width < 90 ? term_width : 90;
          layout_print_wrapped_description(desc, colored_output, 2, keybindings_wrap_width, 0);
          fprintf(desc, "\n");
        } else {
          fprintf(desc, "%s\n", section->content);
        }
      }
 
      fprintf(desc, "\n");
    }
  }
 
  // Print options sections (with section-specific column width for options)
  int options_max_col_width = calculate_section_max_col_width(config, "options", mode, for_binary_help);
  options_config_print_options_sections_with_width(config, desc, options_max_col_width, mode);
}

References ASCIICHAT_OK, BUFFER_SIZE_MEDIUM, colored_string(), terminal_size_t::cols, custom_section_descriptor_t::content, options_config_t::custom_sections, errno, ERROR_INVALID_PARAM, positional_arg_descriptor_t::examples, custom_section_descriptor_t::heading, layout_print_two_column_row(), layout_print_wrapped_description(), LOG_COLOR_DEBUG, LOG_COLOR_FATAL, LOG_COLOR_INFO, LOG_COLOR_WARN, log_error, positional_arg_descriptor_t::mode_bitmask, custom_section_descriptor_t::mode_bitmask, MODE_CLIENT, MODE_DISCOVERY, MODE_DISCOVERY_SERVICE, MODE_MIRROR, MODE_SERVER, options_config_t::num_custom_sections, positional_arg_descriptor_t::num_examples, options_config_t::num_modes, options_config_t::num_positional_args, options_config_t::num_usage_lines, options_config_print_options_sections_with_width(), options_config_t::positional_args, print_project_links(), SAFE_GETENV, safe_snprintf(), positional_arg_descriptor_t::section_heading, SET_ERRNO, terminal_get_size(), usage(), and options_config_t::usage_lines.

Referenced by usage().

◆ options_struct_destroy()

void options_struct_destroy	(	const options_config_t *	config,
		void *	options_struct
	)

Clean up memory owned by options struct.

Frees all auto-duplicated strings and sets pointers to NULL. Call this before freeing the options struct.

Parameters

config	Options configuration
options_struct	Options struct to clean up

Definition at line 1457 of file help.c.

                                                                                  {
  if (!config || !options_struct)
    return;
 
  // Free all owned strings
  for (size_t i = 0; i < config->num_owned_strings; i++) {
    free(config->owned_strings[i]);
  }
 
  // Reset owned strings tracking
  ((options_config_t *)config)->num_owned_strings = 0;
 
  // NULL out string fields
  char *base = (char *)options_struct;
  for (size_t i = 0; i < config->num_descriptors; i++) {
    const option_descriptor_t *desc = &config->descriptors[i];
    if (desc->type == OPTION_TYPE_STRING && desc->owns_memory) {
      char **field = (char **)(base + desc->offset);
      *field = NULL;
    }
  }
}

References options_config_t::descriptors, options_config_t::num_descriptors, options_config_t::num_owned_strings, option_descriptor_t::offset, OPTION_TYPE_STRING, options_config_t::owned_strings, option_descriptor_t::owns_memory, and option_descriptor_t::type.

Data Structures

Enumerations

Functions

Detailed Description

Integration with Registry and RCU

Builder Pattern Workflow

Builder Usage Patterns

Mode Bitmask System

Option Types and Parsing

Option Dependencies

RCU Integration

Enumeration Type Documentation

◆ dependency_type_t

◆ option_input_type_t

◆ option_type_t

Function Documentation

◆ find_similar_option_with_mode()

◆ options_builder_add_action()

◆ options_builder_add_bool()

◆ options_builder_add_callback()

◆ options_builder_add_callback_optional()

◆ options_builder_add_callback_with_metadata()

◆ options_builder_add_custom_section()

◆ options_builder_add_dependency()

◆ options_builder_add_dependency_conflicts()

◆ options_builder_add_dependency_implies()

◆ options_builder_add_dependency_requires()

◆ options_builder_add_descriptor()

◆ options_builder_add_double()

◆ options_builder_add_double_with_metadata()

◆ options_builder_add_example()

◆ options_builder_add_example_utility()

◆ options_builder_add_int()

◆ options_builder_add_int_with_metadata()

◆ options_builder_add_mode()

◆ options_builder_add_positional()

◆ options_builder_add_string()

◆ options_builder_add_usage()

◆ options_builder_build()

◆ options_builder_create()

◆ options_builder_destroy()

◆ options_builder_from_preset()

◆ options_builder_mark_as_list()

◆ options_builder_mark_binary_only()

◆ options_builder_set_arg_placeholder()

◆ options_builder_set_default_value_display()

◆ options_builder_set_enum_values()

◆ options_builder_set_examples()

◆ options_builder_set_input_type()

◆ options_builder_set_mode_bitmask()

◆ options_builder_set_numeric_range()

◆ options_config_calculate_max_col_width()

◆ options_config_destroy()

◆ options_config_parse()

◆ options_config_parse_positional()

◆ options_config_print_options_sections()

◆ options_config_print_options_sections_with_width()

◆ options_config_print_usage()

◆ options_config_print_usage_section()

◆ options_config_set_defaults()

◆ options_config_validate()

◆ options_format_default_value()

◆ options_get_type_placeholder()

◆ options_preset_unified()

◆ options_print_help_for_mode()

◆ options_struct_destroy()