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_descriptor_t
	Option descriptor. More...
struct	option_dependency_t
	Option dependency. More...
struct	positional_arg_descriptor_t
	Positional argument 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	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_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))
	Add double/float option.
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_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_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, 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.
const options_config_t *	options_preset_binary (const char *program_name, const char *description)
	Get binary-level options preset.
const options_config_t *	options_preset_server (const char *program_name, const char *description)
	Get server mode options preset.
const options_config_t *	options_preset_client (const char *program_name, const char *description)
	Get client mode options preset.
const options_config_t *	options_preset_mirror (const char *program_name, const char *description)
	Get mirror mode options preset.
const options_config_t *	options_preset_acds (const char *program_name, const char *description)
	Get acds mode 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, 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.
void	options_config_print_usage (const options_config_t *config, FILE *stream)
	Print usage/help text.
void	options_config_cleanup (const options_config_t *config, void *options_struct)
	Clean up memory owned by options struct.

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.

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
• Preset configs for server/client/mirror/acds modes

Usage Pattern:

1. Create builder (from scratch or preset)
2. Add options with builder functions
3. Add dependencies if needed
4. Build immutable config
5. Parse command line into options struct
6. Validate (required, dependencies, custom)
7. Use options in application
8. Cleanup memory before exit

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 59 of file builder.h.

             {
  DEPENDENCY_REQUIRES,  
  DEPENDENCY_CONFLICTS, 
  DEPENDENCY_IMPLIES    
} dependency_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 45 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

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 532 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};
 
  builder->descriptors[builder->num_descriptors++] = desc;
}

References options_builder_t::descriptors, option_descriptor_t::long_name, options_builder_t::num_descriptors, and OPTION_TYPE_ACTION.

Referenced by options_preset_acds(), options_preset_client(), options_preset_mirror(), and options_preset_server().

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 344 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,
                              .validate = NULL,
                              .parse_fn = NULL,
                              .owns_memory = false};
 
  builder->descriptors[builder->num_descriptors++] = desc;
}

References options_builder_t::descriptors, option_descriptor_t::long_name, options_builder_t::num_descriptors, and OPTION_TYPE_BOOL.

Referenced by options_preset_acds(), options_preset_binary(), options_preset_client(), and options_preset_server().

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_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 599 of file builder.c.

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

References options_builder_t::dependencies, 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 577 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, options_builder_t::num_dependencies, and option_dependency_t::option_name.

Referenced by options_preset_client(), and options_preset_server().

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 589 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, 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 565 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, options_builder_t::num_dependencies, and option_dependency_t::option_name.

Referenced by options_preset_client(), and options_preset_mirror().

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 553 of file builder.c.

                                                                                                       {
  if (!builder || !descriptor)
    return;
 
  ensure_descriptor_capacity(builder);
  builder->descriptors[builder->num_descriptors++] = *descriptor;
}

References options_builder_t::descriptors, and options_builder_t::num_descriptors.

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
	)

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_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_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,
		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
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 627 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,
                                         .parse_fn = parse_fn};
 
  builder->positional_args[builder->num_positional_args++] = pos_arg;
}

References positional_arg_descriptor_t::name, options_builder_t::num_positional_args, and options_builder_t::positional_args.

Referenced by options_builder_from_preset(), options_preset_acds(), options_preset_client(), and options_preset_server().

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_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 265 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;
  }
 
  config->struct_size = builder->struct_size;
  config->program_name = builder->program_name;
  config->description = builder->description;
 
  // Initialize memory management
  config->owned_strings = NULL;
  config->num_owned_strings = 0;
  config->owned_strings_capacity = 0;
 
  return config;
}

References options_config_t::dependencies, options_builder_t::dependencies, options_config_t::description, options_builder_t::description, options_config_t::descriptors, options_builder_t::descriptors, ERROR_INVALID_PARAM, ERROR_MEMORY, options_config_t::num_dependencies, options_builder_t::num_dependencies, options_config_t::num_descriptors, options_builder_t::num_descriptors, options_config_t::num_owned_strings, options_config_t::num_positional_args, options_builder_t::num_positional_args, options_config_t::owned_strings, options_config_t::owned_strings_capacity, options_config_t::positional_args, options_builder_t::positional_args, options_config_t::program_name, options_builder_t::program_name, SAFE_FREE, SAFE_MALLOC, SET_ERRNO, options_config_t::struct_size, and options_builder_t::struct_size.

Referenced by options_preset_acds(), options_preset_binary(), options_preset_client(), options_preset_mirror(), and options_preset_server().

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 184 of file builder.c.

                                                              {
  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->struct_size = struct_size;
  builder->program_name = NULL;
  builder->description = NULL;
 
  return builder;
}

References options_builder_t::dependencies, options_builder_t::dependency_capacity, options_builder_t::description, options_builder_t::descriptor_capacity, options_builder_t::descriptors, ERROR_MEMORY, INITIAL_DEPENDENCY_CAPACITY, INITIAL_DESCRIPTOR_CAPACITY, options_builder_t::num_dependencies, options_builder_t::num_descriptors, options_builder_t::num_positional_args, options_builder_t::positional_arg_capacity, options_builder_t::positional_args, options_builder_t::program_name, SAFE_FREE, SAFE_MALLOC, SET_ERRNO, and options_builder_t::struct_size.

Referenced by options_builder_from_preset(), options_preset_acds(), options_preset_binary(), options_preset_client(), options_preset_mirror(), and options_preset_server().

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 255 of file builder.c.

                                                         {
  if (!builder)
    return;
 
  SAFE_FREE(builder->descriptors);
  SAFE_FREE(builder->dependencies);
  SAFE_FREE(builder->positional_args);
  SAFE_FREE(builder);
}

References options_builder_t::dependencies, options_builder_t::descriptors, options_builder_t::positional_args, and SAFE_FREE.

Referenced by options_preset_acds(), options_preset_binary(), options_preset_client(), options_preset_mirror(), and options_preset_server().

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 220 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->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::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_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");

Definition at line 607 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_config_cleanup()

void options_config_cleanup	(	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 1345 of file builder.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.

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_cleanup() for that.

Parameters

config

Config to free (can be NULL)

Definition at line 329 of file builder.c.

                                                      {
  if (!config)
    return;
 
  SAFE_FREE(config->descriptors);
  SAFE_FREE(config->dependencies);
  SAFE_FREE(config->positional_args);
  SAFE_FREE(config->owned_strings);
  SAFE_FREE(config);
}

References options_config_t::dependencies, options_config_t::descriptors, options_config_t::owned_strings, options_config_t::positional_args, and SAFE_FREE.

Referenced by parse_acds_options(), parse_client_options(), parse_mirror_options(), parse_server_options(), usage_acds(), usage_client(), usage_mirror(), and usage_server().

options_config_parse()

asciichat_error_t options_config_parse	(	const options_config_t *	config,
		int	argc,
		char **	argv,
		void *	options_struct,
		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 1101 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);
  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 parse_acds_options(), parse_client_options(), parse_mirror_options(), and parse_server_options().

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 647 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) {
    (void)fprintf(stderr, "Error: Unexpected positional argument '%s'\n", 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) {
      (void)fprintf(stderr, "Error: Missing required positional argument '%s'\n", pos_arg->name);
      if (pos_arg->help_text) {
        (void)fprintf(stderr, "  %s\n", 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) {
        (void)fprintf(stderr, "Error parsing positional argument '%s': %s\n", pos_arg->name, error_msg);
        free(error_msg);
      } else {
        (void)fprintf(stderr, "Error parsing positional argument '%s': %s\n", 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) {
    (void)fprintf(stderr, "Error: Unexpected positional argument '%s'\n", remaining_argv[arg_index]);
    return ERROR_USAGE;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_USAGE, positional_arg_descriptor_t::help_text, 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_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 1236 of file builder.c.

                                                                              {
  if (!config || !stream)
    return;
 
  // Print header
  if (config->program_name) {
    fprintf(stream, "USAGE: %s [OPTIONS]\n\n", config->program_name);
  }
  if (config->description) {
    fprintf(stream, "%s\n\n", config->description);
  }
 
  // Group options by group name
  const char *current_group = NULL;
 
  for (size_t i = 0; i < config->num_descriptors; i++) {
    const option_descriptor_t *desc = &config->descriptors[i];
 
    // Skip binary-level options (they're shown in top-level help only)
    if (desc->hide_from_mode_help) {
      continue;
    }
 
    // Print group header if changed
    if (desc->group && (!current_group || strcmp(current_group, desc->group) != 0)) {
      fprintf(stream, "\n%s:\n", desc->group);
      current_group = desc->group;
    }
 
    // Print option
    fprintf(stream, "  ");
    if (desc->short_name) {
      fprintf(stream, "-%c, ", desc->short_name);
    } else {
      fprintf(stream, "    ");
    }
 
    fprintf(stream, "--%s", desc->long_name);
 
    // Print value placeholder
    if (desc->type != OPTION_TYPE_BOOL && desc->type != OPTION_TYPE_ACTION) {
      fprintf(stream, " ");
      switch (desc->type) {
      case OPTION_TYPE_INT:
        fprintf(stream, "NUM");
        break;
      case OPTION_TYPE_STRING:
        fprintf(stream, "STR");
        break;
      case OPTION_TYPE_DOUBLE:
        fprintf(stream, "NUM");
        break;
      case OPTION_TYPE_CALLBACK:
        fprintf(stream, "VAL");
        break;
      default:
        break;
      }
    }
 
    // Print description
    if (desc->help_text) {
      fprintf(stream, "  %s", desc->help_text);
    }
 
    // Print default if exists
    if (desc->default_value && desc->type != OPTION_TYPE_CALLBACK) {
      fprintf(stream, " (default: ");
      switch (desc->type) {
      case OPTION_TYPE_BOOL:
        fprintf(stream, "%s", *(const bool *)desc->default_value ? "true" : "false");
        break;
      case OPTION_TYPE_INT: {
        int int_val = 0;
        memcpy(&int_val, desc->default_value, sizeof(int));
        fprintf(stream, "%d", int_val);
        break;
      }
      case OPTION_TYPE_STRING:
        fprintf(stream, "%s", *(const char *const *)desc->default_value);
        break;
      case OPTION_TYPE_DOUBLE: {
        double double_val = 0.0;
        memcpy(&double_val, desc->default_value, sizeof(double));
        fprintf(stream, "%.2f", double_val);
        break;
      }
      default:
        break;
      }
      fprintf(stream, ")");
    }
 
    // Mark as required
    if (desc->required) {
      fprintf(stream, " [REQUIRED]");
    }
 
    // Print env var
    if (desc->env_var_name) {
      fprintf(stream, " (env: %s)", desc->env_var_name);
    }
 
    fprintf(stream, "\n");
  }
 
  fprintf(stream, "\n");
}

References option_descriptor_t::default_value, options_config_t::description, options_config_t::descriptors, option_descriptor_t::env_var_name, option_descriptor_t::group, option_descriptor_t::help_text, option_descriptor_t::hide_from_mode_help, option_descriptor_t::long_name, options_config_t::num_descriptors, OPTION_TYPE_ACTION, OPTION_TYPE_BOOL, OPTION_TYPE_CALLBACK, OPTION_TYPE_DOUBLE, OPTION_TYPE_INT, OPTION_TYPE_STRING, options_config_t::program_name, option_descriptor_t::required, option_descriptor_t::short_name, and option_descriptor_t::type.

Referenced by usage_acds(), usage_client(), usage_mirror(), and usage_server().

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 716 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
    const char *env_value = NULL;
    if (desc->env_var_name) {
      env_value = SAFE_GETENV(desc->env_var_name);
    }
 
    switch (desc->type) {
    case OPTION_TYPE_BOOL: {
      bool value = false;
      if (env_value) {
        // Parse env var as bool
        value = (strcmp(env_value, "1") == 0 || strcmp(env_value, "true") == 0 || strcmp(env_value, "yes") == 0 ||
                 strcmp(env_value, "on") == 0);
      } else if (desc->default_value) {
        value = *(const bool *)desc->default_value;
      }
      *(bool *)field = value;
      break;
    }
 
    case OPTION_TYPE_INT: {
      int value = 0;
      if (env_value) {
        // Parse env var as int
        char *endptr;
        long parsed = strtol(env_value, &endptr, 10);
        if (*endptr == '\0' && parsed >= INT_MIN && parsed <= INT_MAX) {
          value = (int)parsed;
        }
      } else if (desc->default_value) {
        value = *(const int *)desc->default_value;
      }
      // Use memcpy to handle potentially misaligned memory safely
      memcpy(field, &value, sizeof(int));
      break;
    }
 
    case OPTION_TYPE_STRING: {
      const char *value = NULL;
      if (env_value) {
        value = env_value;
      } else if (desc->default_value) {
        value = *(const char *const *)desc->default_value;
      }
 
      // Copy into fixed-size buffer (same as parsing logic in options_config_parse)
      // String fields in options_t are char[OPTIONS_BUFF_SIZE] arrays, not pointers
      if (value && value[0] != '\0') {
        char *dest = (char *)field;
        snprintf(dest, OPTIONS_BUFF_SIZE, "%s", value);
        dest[OPTIONS_BUFF_SIZE - 1] = '\0'; // Ensure null termination
      }
      break;
    }
 
    case OPTION_TYPE_DOUBLE: {
      double value = 0.0;
      if (env_value) {
        char *endptr;
        value = strtod(env_value, &endptr);
        if (*endptr != '\0') {
          value = 0.0; // Parse failed
        }
      } else if (desc->default_value) {
        value = *(const double *)desc->default_value;
      }
      // Use memcpy to handle potentially misaligned memory safely
      memcpy(field, &value, sizeof(double));
      break;
    }
 
    case OPTION_TYPE_CALLBACK:
      // Callbacks don't have automatic defaults in set_defaults
      // Defaults are applied during parsing via the parse_fn callback
      // Note: value_size is not stored in descriptor, so we can't memcpy safely
      break;
 
    case OPTION_TYPE_ACTION:
      // Actions don't store defaults - they execute when encountered
      break;
    }
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, option_descriptor_t::default_value, options_config_t::descriptors, option_descriptor_t::env_var_name, ERROR_INVALID_PARAM, options_config_t::num_descriptors, option_descriptor_t::offset, OPTION_TYPE_ACTION, OPTION_TYPE_BOOL, OPTION_TYPE_CALLBACK, OPTION_TYPE_DOUBLE, OPTION_TYPE_INT, OPTION_TYPE_STRING, OPTIONS_BUFF_SIZE, SAFE_GETENV, SET_ERRNO, and option_descriptor_t::type.

Referenced by parse_acds_options(), parse_client_options(), parse_mirror_options(), and parse_server_options().

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 1125 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;
    bool is_set = false;
 
    switch (desc->type) {
    case OPTION_TYPE_BOOL:
      is_set = true; // Bools are always set
      break;
    case OPTION_TYPE_INT:
      is_set = true; // Ints are always set
      break;
    case OPTION_TYPE_STRING:
      is_set = (*(const char *const *)field != NULL);
      break;
    case OPTION_TYPE_DOUBLE:
      is_set = true; // Doubles are always set
      break;
    case OPTION_TYPE_CALLBACK:
      is_set = (*(const void *const *)field != NULL);
      break;
    case OPTION_TYPE_ACTION:
      is_set = true; // Actions are never required
      break;
    }
 
    if (!is_set) {
      if (error_message) {
        if (desc->env_var_name) {
          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(error_message, "Required option --%s is not set", desc->long_name);
        }
      }
      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 = strdup(dep->error_message);
          } else {
            asprintf(error_message, "Option --%s requires --%s to be set", dep->option_name, dep->depends_on);
          }
        }
        return ERROR_USAGE;
      }
      break;
 
    case DEPENDENCY_CONFLICTS:
      if (option_is_set && depends_is_set) {
        if (error_message) {
          if (dep->error_message) {
            *error_message = strdup(dep->error_message);
          } else {
            asprintf(error_message, "Option --%s conflicts with --%s", dep->option_name, dep->depends_on);
          }
        }
        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;
    }
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, 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, is_set, option_descriptor_t::long_name, options_config_t::num_dependencies, options_config_t::num_descriptors, option_descriptor_t::offset, option_dependency_t::option_name, OPTION_TYPE_ACTION, OPTION_TYPE_BOOL, OPTION_TYPE_CALLBACK, OPTION_TYPE_DOUBLE, OPTION_TYPE_INT, OPTION_TYPE_STRING, option_descriptor_t::required, SET_ERRNO, option_descriptor_t::type, option_dependency_t::type, and option_descriptor_t::validate.

options_preset_acds()

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

Get acds mode options preset.

Parameters

program_name	Optional program name (defaults to "ascii-chat acds")
description	Optional program description (defaults to "ASCII Chat Discovery Service")

Returns

Preset config (caller must free after use)

Definition at line 571 of file presets.c.

                                                                                               {
  // Note: Each call creates a new config (no static caching) since program_name/description vary
  options_builder_t *b = options_builder_create(sizeof(options_t));
  if (!b)
    return NULL;
 
  b->program_name = program_name ? program_name : "ascii-chat discovery service";
  b->description = description ? description : "session management and WebRTC signaling";
 
  // Help and version
  options_builder_add_bool(b, "help", 'h', offsetof(options_t, help), false, "Show this help", "GENERAL", false, NULL);
 
  // Network options
  // Note: Bind addresses are specified via positional arguments, not flags
  add_port_option(b, "27225", "ACDS_PORT");
 
  // ACDS-specific options
  options_builder_add_string(b, "key", 'k', offsetof(options_t, acds_key_path), "",
                             "Path to ACDS identity key file (default: ~/.ascii-chat/acds_identity)", "ACDS", false,
                             "ACDS_KEY_PATH", NULL);
 
  options_builder_add_string(b, "database", 'd', offsetof(options_t, acds_database_path), "",
                             "Path to ACDS database file (default: ~/.ascii-chat/acds.db)", "ACDS", false,
                             "ACDS_DATABASE_PATH", NULL);
 
  // Logging options (binary-level, work before or after mode name)
  // Note: ACDS uses partial logging options due to short name conflicts with identity verification options
  options_builder_add_string(b, "log-file", 'L', offsetof(options_t, log_file), "", "Redirect logs to FILE", "LOGGING",
                             false, "ASCII_CHAT_LOG_FILE", NULL);
 
  options_builder_add_callback(b, "log-level", '\0', offsetof(options_t, log_level), &(log_level_t){LOG_INFO},
                               sizeof(log_level_t), parse_log_level,
                               "Set log level: dev, debug, info, warn, error, fatal", "LOGGING", false, NULL);
 
  // Encryption options (shared with client and server)
  options_builder_add_bool(b, "encrypt", 'E', offsetof(options_t, encrypt_enabled), false, "Enable encryption",
                           "SECURITY", false, NULL);
 
  options_builder_add_string(b, "key", 'K', offsetof(options_t, encrypt_key), "", "SSH/GPG key file path", "SECURITY",
                             false, "ASCII_CHAT_KEY", NULL);
 
  options_builder_add_string(b, "password", '\0', offsetof(options_t, password), "",
                             "Shared password for authentication", "SECURITY", false, "ASCII_CHAT_PASSWORD", NULL);
 
  options_builder_add_string(b, "keyfile", 'F', offsetof(options_t, encrypt_keyfile), "", "Alternative key file path",
                             "SECURITY", false, NULL, NULL);
 
  options_builder_add_bool(b, "no-encrypt", '\0', offsetof(options_t, no_encrypt), false, "Disable encryption",
                           "SECURITY", false, NULL);
 
  // Identity verification options
  options_builder_add_bool(b, "require-server-identity", 'S', offsetof(options_t, require_server_identity), false,
                           "Require servers to provide signed Ed25519 identity when creating sessions", "SECURITY",
                           false, NULL);
 
  options_builder_add_bool(b, "require-client-identity", 'C', offsetof(options_t, require_client_identity), false,
                           "Require clients to provide signed Ed25519 identity when joining sessions", "SECURITY",
                           false, NULL);
 
  options_builder_add_bool(b, "require-server-verify", 'V', offsetof(options_t, require_server_verify), false,
                           "ACDS policy: require servers to verify client identity during handshake", "SECURITY", false,
                           NULL);
 
  options_builder_add_bool(b, "require-client-verify", 'c', offsetof(options_t, require_client_verify), false,
                           "ACDS policy: require clients to verify server identity during handshake", "SECURITY", false,
                           NULL);
 
  // WebRTC connectivity options
  options_builder_add_string(b, "stun-servers", '\0', offsetof(options_t, stun_servers),
                             "stun:stun.ascii-chat.com:3478,stun:stun.l.google.com:19302",
                             "Comma-separated list of STUN server URLs", "WEBRTC", false, "ASCII_CHAT_STUN_SERVERS",
                             NULL);
 
  options_builder_add_string(b, "turn-servers", '\0', offsetof(options_t, turn_servers),
                             "turn:turn.ascii-chat.com:3478", "Comma-separated list of TURN server URLs", "WEBRTC",
                             false, "ASCII_CHAT_TURN_SERVERS", NULL);
 
  options_builder_add_string(b, "turn-username", '\0', offsetof(options_t, turn_username), "ascii",
                             "Username for TURN server authentication", "WEBRTC", false, "ASCII_CHAT_TURN_USERNAME",
                             NULL);
 
  options_builder_add_string(b, "turn-credential", '\0', offsetof(options_t, turn_credential),
                             "0aa9917b4dad1b01631e87a32b875e09", "Credential/password for TURN server authentication",
                             "WEBRTC", false, "ASCII_CHAT_TURN_CREDENTIAL", NULL);
 
  options_builder_add_string(b, "turn-secret", '\0', offsetof(options_t, turn_secret), "",
                             "Shared secret for dynamic TURN credential generation (HMAC-SHA1)", "WEBRTC", false,
                             "ASCII_CHAT_TURN_SECRET", NULL);
 
  options_builder_add_bool(b, "upnp", '\0', offsetof(options_t, enable_upnp), true,
                           "Enable UPnP/NAT-PMP for automatic port mapping (enables direct TCP for most home users)",
                           "WEBRTC", false, "ASCII_CHAT_UPNP");
 
  options_builder_add_bool(b, "no-upnp", '\0', offsetof(options_t, no_upnp), false,
                           "Disable UPnP/NAT-PMP port mapping (requires manual port forwarding)", "WEBRTC", false,
                           NULL);
 
  // Action options (execute and exit)
  options_builder_add_action(b, "version", 'v', action_show_version, "Show version information and exit", "ACTIONS");
 
  // Positional arguments: 0-2 bind addresses (IPv4 and/or IPv6)
  options_builder_add_positional(b, "bind-address", "IPv4 or IPv6 bind address (can specify 0-2 addresses)",
                                 false, // Not required (defaults to localhost)
                                 "BIND ADDRESS FORMATS", g_server_bind_address_examples,
                                 sizeof(g_server_bind_address_examples) / sizeof(g_server_bind_address_examples[0]),
                                 parse_server_bind_address);
 
  const options_config_t *config = options_builder_build(b);
  options_builder_destroy(b);
  return config;
}

References action_show_version(), options_builder_t::description, log_file, LOG_INFO, options_builder_add_action(), options_builder_add_bool(), options_builder_add_callback(), options_builder_add_positional(), options_builder_add_string(), options_builder_build(), options_builder_create(), options_builder_destroy(), parse_log_level(), parse_server_bind_address(), and options_builder_t::program_name.

Referenced by parse_acds_options(), and usage_acds().

options_preset_binary()

const options_config_t * options_preset_binary	(	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)

Definition at line 273 of file presets.c.

                                                                                                 {
  // Note: Each call creates a new config (no static caching) since program_name/description vary
  options_builder_t *b = options_builder_create(sizeof(options_t));
  if (!b)
    return NULL;
 
  b->program_name = program_name ? program_name : "ascii-chat";
  b->description = description ? description : "Video chat in your terminal";
 
  // Help and version
  options_builder_add_bool(b, "help", '\0', offsetof(options_t, help), false, "Show this help", "GENERAL", false, NULL);
 
  options_builder_add_bool(b, "version", '\0', offsetof(options_t, version), false, "Show version information",
                           "GENERAL", false, NULL);
 
  // Add logging options
  add_binary_logging_options(b);
 
  const options_config_t *config = options_builder_build(b);
  options_builder_destroy(b);
  return config;
}

References options_builder_t::description, options_builder_add_bool(), options_builder_build(), options_builder_create(), options_builder_destroy(), and options_builder_t::program_name.

options_preset_client()

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

Get client mode options preset.

Parameters

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

Returns

Preset config (caller must free after use)

Definition at line 398 of file presets.c.

                                                                                                 {
  // Note: Each call creates a new config (no static caching) since program_name/description vary
  options_builder_t *b = options_builder_create(sizeof(options_t));
  if (!b)
    return NULL;
 
  b->program_name = program_name ? program_name : "ascii-chat client";
  b->description = description ? description : "Connect to ascii-chat server";
 
  // Network options
  // Note: Server address and port are specified via positional argument [address][:port], not flags
  add_port_option(b, OPT_PORT_DEFAULT, "ASCII_CHAT_PORT");
 
  options_builder_add_int(b, "reconnect", 'r', offsetof(options_t, reconnect_attempts), OPT_RECONNECT_ATTEMPTS_DEFAULT,
                          "Reconnection attempts (-1=infinite)", "NETWORK", false, NULL, NULL);
 
  options_builder_add_bool(b, "scan", '\0', offsetof(options_t, lan_discovery), false,
                           "Scan for ASCII-Chat servers on local network (mDNS)", "NETWORK", false, NULL);
 
  // Terminal dimensions, webcam, display, and snapshot options (shared with mirror)
  add_terminal_dimension_options(b);
  add_webcam_options(b);
  add_display_options(b);
  add_snapshot_options(b);
 
  // Audio options
  options_builder_add_bool(b, "audio", 'A', offsetof(options_t, audio_enabled), false, "Enable audio streaming",
                           "AUDIO", false, NULL);
 
  options_builder_add_int(b, "microphone-index", '\0', offsetof(options_t, microphone_index),
                          OPT_MICROPHONE_INDEX_DEFAULT, "Microphone device index (-1=default)", "AUDIO", false, NULL,
                          NULL);
 
  options_builder_add_int(b, "speakers-index", '\0', offsetof(options_t, speakers_index), OPT_SPEAKERS_INDEX_DEFAULT,
                          "Speakers device index (-1=default)", "AUDIO", false, NULL, NULL);
 
  options_builder_add_bool(b, "audio-analysis", '\0', offsetof(options_t, audio_analysis_enabled), false,
                           "Enable audio analysis (debug)", "AUDIO", false, NULL);
 
  options_builder_add_bool(b, "no-audio-playback", '\0', offsetof(options_t, audio_no_playback), false,
                           "Disable speaker playback (debug)", "AUDIO", false, NULL);
 
  // Compression and audio encoding options (shared with server)
  add_compression_options(b);
 
  // ACDS Discovery options (shared with server)
  add_acds_discovery_options(b);
 
  // WebRTC Connection Strategy Options (Phase 3 fallback control)
  options_builder_add_bool(b, "prefer-webrtc", '\0', offsetof(options_t, prefer_webrtc), false,
                           "Try WebRTC before Direct TCP (useful when Direct TCP fails)", "NETWORK", false, NULL);
 
  options_builder_add_bool(b, "no-webrtc", '\0', offsetof(options_t, no_webrtc), false,
                           "Disable WebRTC, use Direct TCP only", "NETWORK", false, NULL);
 
  options_builder_add_bool(b, "webrtc-skip-stun", '\0', offsetof(options_t, webrtc_skip_stun), false,
                           "Skip WebRTC+STUN stage, go straight to TURN relay", "NETWORK", false, NULL);
 
  options_builder_add_bool(b, "webrtc-disable-turn", '\0', offsetof(options_t, webrtc_disable_turn), false,
                           "Disable WebRTC+TURN relay, use STUN only", "NETWORK", false, NULL);
 
  // WebRTC Server Configuration (for testing/debugging - production uses ACDS)
  // Note: In production, ACDS provides these automatically via SESSION_JOINED response
  options_builder_add_string(b, "stun-servers", '\0', offsetof(options_t, stun_servers), "",
                             "Comma-separated STUN server URLs (debug/test only - ACDS provides in production)",
                             "WEBRTC", false, "ASCII_CHAT_STUN_SERVERS", NULL);
 
  options_builder_add_string(b, "turn-servers", '\0', offsetof(options_t, turn_servers), "",
                             "Comma-separated TURN server URLs (debug/test only - ACDS provides in production)",
                             "WEBRTC", false, "ASCII_CHAT_TURN_SERVERS", NULL);
 
  options_builder_add_string(b, "turn-username", '\0', offsetof(options_t, turn_username), "",
                             "TURN authentication username (debug/test only - ACDS provides in production)", "WEBRTC",
                             false, "ASCII_CHAT_TURN_USERNAME", NULL);
 
  options_builder_add_string(b, "turn-credential", '\0', offsetof(options_t, turn_credential), "",
                             "TURN authentication credential (debug/test only - ACDS provides in production)", "WEBRTC",
                             false, "ASCII_CHAT_TURN_CREDENTIAL", NULL);
 
  // Security options (common with server, plus client-specific server-key)
  add_crypto_common_options(b);
 
  options_builder_add_string(b, "server-key", '\0', offsetof(options_t, server_key), "", "Expected server public key",
                             "SECURITY", false, NULL, NULL);
 
  options_builder_add_bool(b, "acds-insecure", '\0', offsetof(options_t, acds_insecure), false,
                           "Skip server key verification (MITM-vulnerable, requires explicit opt-in)", "SECURITY",
                           false, NULL);
 
  // Add binary-level logging options (--log-file, --log-level, -V, -q)
  // These work before or after the mode name
  add_binary_logging_options(b);
 
  // Dependencies
  options_builder_add_dependency_requires(b, "snapshot-delay", "snapshot",
                                          "Option --snapshot-delay requires --snapshot");
  options_builder_add_dependency_conflicts(b, "no-compress", "compression-level",
                                           "Cannot use --no-compress with --compression-level");
  options_builder_add_dependency_conflicts(b, "encode-audio", "no-encode-audio",
                                           "Cannot use both --encode-audio and --no-encode-audio");
 
  // Action options (execute and exit)
  options_builder_add_action(b, "help", 'h', action_help_client, "Show this help message and exit", "ACTIONS");
 
  options_builder_add_action(b, "list-webcams", '\0', action_list_webcams, "List available webcam devices and exit",
                             "ACTIONS");
 
  options_builder_add_action(b, "list-microphones", '\0', action_list_microphones,
                             "List available microphone devices and exit", "ACTIONS");
 
  options_builder_add_action(b, "list-speakers", '\0', action_list_speakers, "List available speaker devices and exit",
                             "ACTIONS");
 
  options_builder_add_action(b, "show-capabilities", '\0', action_show_capabilities,
                             "Show terminal capabilities and exit", "ACTIONS");
 
  // Positional argument: [address][:port]
  options_builder_add_positional(
      b, "address", "[address][:port] - Server address (IPv4, IPv6, or hostname) with optional port",
      false, // Not required (defaults to localhost:27224)
      "ADDRESS FORMATS", g_client_address_examples,
      sizeof(g_client_address_examples) / sizeof(g_client_address_examples[0]), parse_client_address);
 
  const options_config_t *config = options_builder_build(b);
  options_builder_destroy(b);
  return config;
}

References action_help_client(), action_list_microphones(), action_list_speakers(), action_list_webcams(), action_show_capabilities(), options_builder_t::description, OPT_MICROPHONE_INDEX_DEFAULT, OPT_PORT_DEFAULT, OPT_RECONNECT_ATTEMPTS_DEFAULT, OPT_SPEAKERS_INDEX_DEFAULT, options_builder_add_action(), options_builder_add_bool(), options_builder_add_dependency_conflicts(), options_builder_add_dependency_requires(), options_builder_add_int(), options_builder_add_positional(), options_builder_add_string(), options_builder_build(), options_builder_create(), options_builder_destroy(), parse_client_address(), and options_builder_t::program_name.

Referenced by parse_client_options(), and usage_client().

options_preset_mirror()

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

Get mirror mode options preset.

Parameters

program_name	Optional program name (defaults to "ascii-chat mirror")
description	Optional program description (defaults to "Local webcam viewing (no network)")

Returns

Preset config (caller must free after use)

Definition at line 530 of file presets.c.

                                                                                                 {
  // Note: Each call creates a new config (no static caching) since program_name/description vary
  options_builder_t *b = options_builder_create(sizeof(options_t));
  if (!b)
    return NULL;
 
  b->program_name = program_name ? program_name : "ascii-chat mirror";
  b->description = description ? description : "Local webcam viewing (no network)";
 
  // Terminal dimensions, webcam, display, and snapshot options (shared with client)
  add_terminal_dimension_options(b);
  add_webcam_options(b);
  add_display_options(b);
  add_snapshot_options(b);
 
  // Add binary-level logging options (--log-file, --log-level, -V, -q)
  // These work before or after the mode name
  add_binary_logging_options(b);
 
  // Dependencies
  options_builder_add_dependency_requires(b, "snapshot-delay", "snapshot",
                                          "Option --snapshot-delay requires --snapshot");
 
  // Action options (execute and exit)
  options_builder_add_action(b, "help", 'h', action_help_mirror, "Show this help message and exit", "ACTIONS");
 
  options_builder_add_action(b, "list-webcams", '\0', action_list_webcams, "List available webcam devices and exit",
                             "ACTIONS");
 
  options_builder_add_action(b, "show-capabilities", '\0', action_show_capabilities,
                             "Show terminal capabilities and exit", "ACTIONS");
 
  const options_config_t *config = options_builder_build(b);
  options_builder_destroy(b);
  return config;
}

References action_help_mirror(), action_list_webcams(), action_show_capabilities(), options_builder_t::description, options_builder_add_action(), options_builder_add_dependency_requires(), options_builder_build(), options_builder_create(), options_builder_destroy(), and options_builder_t::program_name.

Referenced by parse_mirror_options(), and usage_mirror().

options_preset_server()

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

Get server mode options preset.

Parameters

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

Returns

Preset config (caller must free after use)

Definition at line 300 of file presets.c.

                                                                                                 {
  // Note: Each call creates a new config (no static caching) since program_name/description vary
  options_builder_t *b = options_builder_create(sizeof(options_t));
  if (!b)
    return NULL;
 
  b->program_name = program_name ? program_name : "ascii-chat server";
  b->description = description ? description : "Start ascii-chat server";
 
  // Network options
  // Note: Server bind addresses are positional arguments only, not flags
  add_port_option(b, OPT_PORT_DEFAULT, "ASCII_CHAT_PORT");
 
  options_builder_add_int(b, "max-clients", '\0', offsetof(options_t, max_clients), OPT_MAX_CLIENTS_DEFAULT,
                          "Maximum concurrent clients", "NETWORK", false, "ASCII_CHAT_MAX_CLIENTS", NULL);
 
  // Compression and audio encoding options (shared with client)
  add_compression_options(b);
 
  options_builder_add_bool(b, "no-audio-mixer", '\0', offsetof(options_t, no_audio_mixer), false,
                           "Disable audio mixer (debug)", "PERFORMANCE", false, NULL);
 
  // Security options (common with client, plus server-specific client-keys and no-encrypt)
  add_crypto_common_options(b);
 
  options_builder_add_string(b, "client-keys", '\0', offsetof(options_t, client_keys), "",
                             "Allowed client keys whitelist", "SECURITY", false, NULL, NULL);
 
  options_builder_add_bool(b, "acds-expose-ip", '\0', offsetof(options_t, acds_expose_ip), false,
                           "Explicitly allow public IP disclosure in ACDS sessions (requires ACDS, opt-in only)",
                           "SECURITY", false, NULL);
 
  options_builder_add_bool(b, "no-encrypt", '\0', offsetof(options_t, no_encrypt), false, "Disable encryption",
                           "SECURITY", false, NULL);
 
  // ACDS Session Registration
  options_builder_add_bool(b, "acds", '\0', offsetof(options_t, acds), false,
                           "Enable ACDS session registration (requires --key or --password or --acds-expose-ip)",
                           "DISCOVERY", false, NULL);
 
  // ACDS Discovery options (shared with client)
  add_acds_discovery_options(b);
 
  options_builder_add_bool(b, "upnp", '\0', offsetof(options_t, enable_upnp), true,
                           "Enable UPnP/NAT-PMP for automatic port mapping (enables direct TCP for most home users)",
                           "DISCOVERY", false, "ASCII_CHAT_UPNP");
 
  options_builder_add_bool(b, "no-upnp", '\0', offsetof(options_t, no_upnp), false,
                           "Disable UPnP/NAT-PMP port mapping (requires manual port forwarding)", "DISCOVERY", false,
                           NULL);
 
  options_builder_add_bool(b, "no-mdns-advertise", '\0', offsetof(options_t, no_mdns_advertise), false,
                           "Disable mDNS service advertisement on local network (LAN discovery won't find this server)",
                           "DISCOVERY", false, NULL);
 
  // Add binary-level logging options (--log-file, --log-level, -V, -q)
  // These work before or after the mode name
  add_binary_logging_options(b);
 
  // Dependencies
  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");
  options_builder_add_dependency_conflicts(b, "no-encrypt", "password", "Cannot use --no-encrypt with --password");
  options_builder_add_dependency_conflicts(b, "no-compress", "compression-level",
                                           "Cannot use --no-compress with --compression-level");
  options_builder_add_dependency_conflicts(b, "encode-audio", "no-encode-audio",
                                           "Cannot use both --encode-audio and --no-encode-audio");
 
  // Action options (execute and exit)
  options_builder_add_action(b, "help", 'h', action_help_server, "Show this help message and exit", "ACTIONS");
 
  options_builder_add_action(b, "list-webcams", '\0', action_list_webcams, "List available webcam devices and exit",
                             "ACTIONS");
 
  options_builder_add_action(b, "list-microphones", '\0', action_list_microphones,
                             "List available microphone devices and exit", "ACTIONS");
 
  options_builder_add_action(b, "list-speakers", '\0', action_list_speakers, "List available speaker devices and exit",
                             "ACTIONS");
 
  options_builder_add_action(b, "version", 'V', action_show_version, "Show version information and exit", "ACTIONS");
 
  // Positional arguments: 0-2 bind addresses (IPv4 and/or IPv6)
  options_builder_add_positional(b, "bind-address", "IPv4 or IPv6 bind address (can specify 0-2 addresses)",
                                 false, // Not required (defaults to localhost)
                                 "BIND ADDRESS FORMATS", g_server_bind_address_examples,
                                 sizeof(g_server_bind_address_examples) / sizeof(g_server_bind_address_examples[0]),
                                 parse_server_bind_address);
 
  const options_config_t *config = options_builder_build(b);
  options_builder_destroy(b);
  return config;
}

References action_help_server(), action_list_microphones(), action_list_speakers(), action_list_webcams(), action_show_version(), options_builder_t::description, OPT_MAX_CLIENTS_DEFAULT, OPT_PORT_DEFAULT, options_builder_add_action(), options_builder_add_bool(), options_builder_add_dependency_conflicts(), options_builder_add_int(), options_builder_add_positional(), options_builder_add_string(), options_builder_build(), options_builder_create(), options_builder_destroy(), parse_server_bind_address(), and options_builder_t::program_name.

Referenced by parse_server_options(), and usage_server().