builder.h File Reference

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

Go to the source code of this file.

Data Structures
struct	option_metadata_t
	Completion metadata attached to one option descriptor. More...
struct	option_descriptor_t
	The complete registry entry for one command-line/configuration option. More...
struct	usage_descriptor_t
	The complete registry entry for one command-line/configuration option. 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
	A rule connecting one option to another during validation. More...
struct	positional_arg_descriptor_t
	Describes one non-option command-line argument and how the parser consumes it. More...
struct	custom_section_descriptor_t
	Describes one non-option command-line argument and how the parser consumes it. More...
struct	options_config_t
	Immutable parsing tables produced from an options builder. More...
struct	options_builder_t
	Immutable parsing tables produced from an 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 }
	Custom help section descriptor. 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 }
	Completion metadata attached to one option descriptor. More...

Functions
options_builder_t *	options_builder_create (size_t struct_size)
	Mutable owner used to assemble option descriptors, dependencies, help sections, and examples before building a config.
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))
	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), 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))
	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), 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), 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.
void	options_builder_set_string_parser (options_builder_t *builder, bool(*parser)(const char *, void *, char **))

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

Completion metadata attached to one option descriptor.

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 236 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 181 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

Custom help section descriptor.

Example descriptor for programmatic EXAMPLES generation

Mode descriptor for programmatic MODES generation (for help output)

A rule connecting one option to another during validation

Usage line descriptor for programmatic USAGE generation

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 166 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 121 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[OPTIONS_COMMON_SUGGESTION_BUFFER_SIZE];
  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, OPTIONS_COMMON_SUGGESTION_BUFFER_SIZE, and safe_snprintf().

options_builder_add_action()

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).

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

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)

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(*	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.

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(*	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.

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(*	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.).

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.)

Referenced by options_registry_add_all_to_builder().

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)

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

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)

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)

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)

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

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(*	validate )(const void *options_struct),
		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)

Referenced by options_registry_add_all_to_builder().

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(*	validate )(const void *options_struct),
		const option_metadata_t *	metadata,
		bool	optional_arg )

Referenced by options_registry_add_all_to_builder().

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

References args.

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

References args.

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(*	validate )(const void *options_struct) )

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)

Referenced by options_registry_add_all_to_builder().

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(*	validate )(const void *options_struct),
		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)

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)");

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(*	parse_fn )(const char *arg, void *config, char **remaining, int num_remaining, char **error_msg) )

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

Referenced by 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(*	validate )(const void *options_struct) )

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)

Referenced by options_registry_add_all_to_builder().

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");

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)

Referenced by options_builder_generate_manpage_template(), and options_preset_unified().

options_builder_create()

options_builder_t * options_builder_create

(

size_t

struct_size

)

Mutable owner used to assemble option descriptors, dependencies, help sections, and examples before building a config.

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)

Referenced by 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)

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)

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_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_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

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

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);

Referenced by options_registry_add_all_to_builder().

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_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);

Referenced by options_registry_add_all_to_builder().

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

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_string_parser()

void options_builder_set_string_parser	(	options_builder_t *	builder,
		bool(*	parser )(const char *, void *, char **) )

Set the CLI parser for the last added string option; environment strings remain scalar.

Referenced by options_registry_add_all_to_builder().

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

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)

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

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

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)

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)

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)

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)

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

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

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 590 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 ? OPT_VALUE_TRUE : OPT_VALUE_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 OPT_VALUE_FALSE, OPT_VALUE_TRUE, OPTION_TYPE_BOOL, OPTION_TYPE_DOUBLE, OPTION_TYPE_INT, OPTION_TYPE_STRING, and safe_snprintf().

Referenced by 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 572 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 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 58 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 | OPTION_MODE_MCP_SERVER, 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, "mcp-server", "[--transport http|stdio] [--server] [bind-address] [bind-address]", true,
                            "MCP rendering tools (stdio locally, HTTP with --transport http, default port 27228)");
  options_builder_add_example(b, OPTION_MODE_MCP_SERVER, "", "Local MCP tools over stdio", false);
  options_builder_add_example(b, OPTION_MODE_MCP_SERVER, "--transport http --address 127.0.0.1 --port 27228",
                              "Local MCP tools over Streamable HTTP", false);
  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[OPTIONS_CONFIG_PRESETS_COMBINED_BUF1_BUFFER_SIZE];
  static char combined_buf2[OPTIONS_CONFIG_PRESETS_COMBINED_BUF2_BUFFER_SIZE];
  static char combined_buf3[OPTIONS_CONFIG_PRESETS_COMBINED_BUF3_BUFFER_SIZE];
  static char combined_buf4[OPTIONS_CONFIG_PRESETS_COMBINED_BUF4_BUFFER_SIZE];
  static char combined_buf5[OPTIONS_CONFIG_PRESETS_COMBINED_BUF5_BUFFER_SIZE];
  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");
  options_builder_add_mode(b, "mcp-server", "MCP media rendering tools");
  options_builder_add_mode(b, "api-server", "HTTP image-to-ASCII API");
 
  // 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"
                                     "  - Press - to toggle the FPS counter (always visible in keyboard help).\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
  // ============================================================================
  // Reject contradictory CLI requests before initializing transport security.
  options_builder_add_dependency_conflicts(b, "no-encrypt", "encrypt", "Cannot use --no-encrypt with --encrypt");
 
  // Authentication material conflicts with explicitly disabling authentication.
  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)");
 
  // Identity and verification keys can be combined, including with --no-encrypt.
 
  // ============================================================================
  // 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

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