builder.c File Reference

Implementation of options builder API. More...

Go to the source code of this file.

Macros
#define	INITIAL_DESCRIPTOR_CAPACITY   32
#define	INITIAL_DEPENDENCY_CAPACITY   16
#define	INITIAL_POSITIONAL_ARG_CAPACITY   8
#define	INITIAL_OWNED_STRINGS_CAPACITY   32

Functions
	__attribute__ ((unused))
	Track an owned string for cleanup.
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 *, char **))
void	options_builder_add_string (options_builder_t *builder, const char *long_name, char short_name, size_t offset, const char *default_value, const char *help_text, const char *group, bool required, const char *env_var_name, bool(*validate)(const void *, char **))
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 *, char **))
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 *, void *, char **), const char *help_text, const char *group, bool required, const char *env_var_name)
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 *, void *, char **), const char *help_text, const char *group, bool required, const char *env_var_name, bool optional_arg)
	Add callback option with optional argument support.
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.
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

Implementation of options builder API.

Definition in file builder.c.

Macro Definition Documentation

INITIAL_DEPENDENCY_CAPACITY

#define INITIAL_DEPENDENCY_CAPACITY   16

Definition at line 25 of file builder.c.

INITIAL_DESCRIPTOR_CAPACITY

#define INITIAL_DESCRIPTOR_CAPACITY   32

Definition at line 24 of file builder.c.

INITIAL_OWNED_STRINGS_CAPACITY

#define INITIAL_OWNED_STRINGS_CAPACITY   32

Definition at line 27 of file builder.c.

INITIAL_POSITIONAL_ARG_CAPACITY

#define INITIAL_POSITIONAL_ARG_CAPACITY   8

Definition at line 26 of file builder.c.

Function Documentation

__attribute__()

static int __attribute__ ( (unused)  )

inline

Track an owned string for cleanup.

Definition at line 90 of file builder.c.

                                                                                            {
  if (!str)
    return;
 
  if (config->num_owned_strings >= config->owned_strings_capacity) {
    size_t new_capacity = config->owned_strings_capacity * 2;
    if (new_capacity == 0)
      new_capacity = INITIAL_OWNED_STRINGS_CAPACITY;
 
    char **new_owned = SAFE_REALLOC(config->owned_strings, new_capacity * sizeof(char *), char **);
    if (!new_owned) {
      log_fatal("Failed to reallocate owned_strings array");
      return;
    }
    config->owned_strings = new_owned;
    config->owned_strings_capacity = new_capacity;
  }
 
  config->owned_strings[config->num_owned_strings++] = str;
}

References INITIAL_OWNED_STRINGS_CAPACITY, log_fatal, options_config_t::num_owned_strings, options_config_t::owned_strings, options_config_t::owned_strings_capacity, and SAFE_REALLOC.

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 *, void *, char **)	parse_fn,
		const char *	help_text,
		const char *	group,
		bool	required,
		const char *	env_var_name
	)

Definition at line 467 of file builder.c.

                                                                                              {
  (void)value_size; // Unused parameter
  ensure_descriptor_capacity(builder);
 
  option_descriptor_t desc = {.long_name = long_name,
                              .short_name = short_name,
                              .type = OPTION_TYPE_CALLBACK,
                              .offset = offset,
                              .help_text = help_text,
                              .group = group,
                              .default_value = default_value,
                              .required = required,
                              .env_var_name = env_var_name,
                              .validate = NULL,
                              .parse_fn = parse_fn,
                              .owns_memory = false,
                              .optional_arg = 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_CALLBACK.

Referenced by options_preset_acds().

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 *, void *, char **)	parse_fn,
		const char *	help_text,
		const char *	group,
		bool	required,
		const char *	env_var_name,
		bool	optional_arg
	)

Add callback option with optional argument support.

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)
optional_arg	If true, argument is optional (parser receives NULL if not provided)

Definition at line 507 of file builder.c.

                                                              {
  (void)value_size; // Unused parameter
  ensure_descriptor_capacity(builder);
 
  option_descriptor_t desc = {.long_name = long_name,
                              .short_name = short_name,
                              .type = OPTION_TYPE_CALLBACK,
                              .offset = offset,
                              .help_text = help_text,
                              .group = group,
                              .default_value = default_value,
                              .required = required,
                              .env_var_name = env_var_name,
                              .validate = NULL,
                              .parse_fn = parse_fn,
                              .owns_memory = false,
                              .optional_arg = optional_arg};
 
  builder->descriptors[builder->num_descriptors++] = desc;
}

References options_builder_t::descriptors, option_descriptor_t::long_name, options_builder_t::num_descriptors, and OPTION_TYPE_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 *, char **)	validate
	)

Definition at line 436 of file builder.c.

                                                                                                   {
  ensure_descriptor_capacity(builder);
 
  static double defaults[256];
  static size_t num_defaults = 0;
 
  if (num_defaults >= 256) {
    log_error("Too many double options (max 256)");
    return;
  }
 
  defaults[num_defaults] = default_value;
 
  option_descriptor_t desc = {.long_name = long_name,
                              .short_name = short_name,
                              .type = OPTION_TYPE_DOUBLE,
                              .offset = offset,
                              .help_text = help_text,
                              .group = group,
                              .default_value = &defaults[num_defaults++],
                              .required = required,
                              .env_var_name = env_var_name,
                              .validate = validate,
                              .parse_fn = NULL,
                              .owns_memory = false};
 
  builder->descriptors[builder->num_descriptors++] = desc;
}

References options_builder_t::descriptors, log_error, option_descriptor_t::long_name, options_builder_t::num_descriptors, and OPTION_TYPE_DOUBLE.

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 *, char **)	validate
	)

Definition at line 367 of file builder.c.

                                                                                                {
  ensure_descriptor_capacity(builder);
 
  // Store default value statically
  static int defaults[256]; // Assume we won't have more than 256 int options
  static size_t num_defaults = 0;
 
  if (num_defaults >= 256) {
    log_error("Too many int options (max 256)");
    return;
  }
 
  defaults[num_defaults] = default_value;
 
  option_descriptor_t desc = {.long_name = long_name,
                              .short_name = short_name,
                              .type = OPTION_TYPE_INT,
                              .offset = offset,
                              .help_text = help_text,
                              .group = group,
                              .default_value = &defaults[num_defaults++],
                              .required = required,
                              .env_var_name = env_var_name,
                              .validate = validate,
                              .parse_fn = NULL,
                              .owns_memory = false};
 
  builder->descriptors[builder->num_descriptors++] = desc;
}

References options_builder_t::descriptors, log_error, option_descriptor_t::long_name, options_builder_t::num_descriptors, and OPTION_TYPE_INT.

Referenced by options_preset_client(), and options_preset_server().

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 *, char **)	validate
	)

Definition at line 399 of file builder.c.

                                                                                                   {
  ensure_descriptor_capacity(builder);
 
  // Store default string pointer in static storage to avoid stack-use-after-return
  static const char *defaults[256];
  static size_t num_defaults = 0;
 
  const void *default_ptr = NULL;
  if (default_value) {
    if (num_defaults >= 256) {
      log_error("Too many string options (max 256)");
      return;
    }
    defaults[num_defaults] = default_value;
    default_ptr = &defaults[num_defaults++];
  }
 
  option_descriptor_t desc = {
      .long_name = long_name,
      .short_name = short_name,
      .type = OPTION_TYPE_STRING,
      .offset = offset,
      .help_text = help_text,
      .group = group,
      .default_value = default_ptr,
      .required = required,
      .env_var_name = env_var_name,
      .validate = validate,
      .parse_fn = NULL,
      .owns_memory = true // Strings are always owned
  };
 
  builder->descriptors[builder->num_descriptors++] = desc;
}

References options_builder_t::descriptors, log_error, option_descriptor_t::long_name, options_builder_t::num_descriptors, and OPTION_TYPE_STRING.

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

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.