builder.c File Reference

Implementation of options builder API. More...

Go to the source code of this file.

Macros
#define	asprintf   platform_asprintf

Functions
const char *	get_option_help_placeholder_str (const option_descriptor_t *desc)
	Get help placeholder string for an option type.
int	format_option_default_value_str (const option_descriptor_t *desc, char *buf, size_t bufsize)
	Format option default value as a string.
bool	option_applies_to_mode (const option_descriptor_t *desc, asciichat_mode_t mode, bool for_binary_help)
	Check if an option applies to a specific mode using bitmask.
void	ensure_descriptor_capacity (options_builder_t *builder)
	Grow descriptor array if needed.
void	ensure_dependency_capacity (options_builder_t *builder)
	Grow dependency array if needed.
void	ensure_positional_arg_capacity (options_builder_t *builder)
	Grow positional arg array if needed.
const option_descriptor_t *	find_option (const options_config_t *config, const char *long_name)
	Find option descriptor by long name.
bool	is_option_set (const options_config_t *config, const void *options_struct, const char *option_name)
	Check if an option is set (has non-default value)
options_builder_t *	options_builder_create (size_t struct_size)
options_builder_t *	options_builder_from_preset (const options_config_t *preset)
void	options_builder_destroy (options_builder_t *builder)
options_config_t *	options_builder_build (options_builder_t *builder)
void	options_config_destroy (options_config_t *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)
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_int_with_metadata (options_builder_t *builder, const char *long_name, char short_name, size_t offset, int default_value, const char *help_text, const char *group, bool required, const char *env_var_name, bool(*validate)(const void *options_struct, char **error_msg), const option_metadata_t *metadata)
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_double_with_metadata (options_builder_t *builder, const char *long_name, char short_name, size_t offset, double default_value, const char *help_text, const char *group, bool required, const char *env_var_name, bool(*validate)(const void *, char **), const option_metadata_t *metadata)
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_callback_with_metadata (options_builder_t *builder, const char *long_name, char short_name, size_t offset, const void *default_value, size_t value_size, bool(*parse_fn)(const char *, void *, char **), const char *help_text, const char *group, bool required, const char *env_var_name, bool optional_arg, const option_metadata_t *metadata)
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)
void	options_builder_add_descriptor (options_builder_t *builder, const option_descriptor_t *descriptor)
void	options_builder_set_mode_bitmask (options_builder_t *builder, option_mode_bitmask_t mode_bitmask)
void	options_builder_set_arg_placeholder (options_builder_t *builder, const char *arg_placeholder)
void	options_builder_set_enum_values (options_builder_t *builder, const char *option_name, const char **values, const char **descriptions)
void	options_builder_set_numeric_range (options_builder_t *builder, const char *option_name, int min, int max, int step)
void	options_builder_set_examples (options_builder_t *builder, const char *option_name, const char **examples)
void	options_builder_set_input_type (options_builder_t *builder, const char *option_name, option_input_type_t input_type)
void	options_builder_mark_as_list (options_builder_t *builder, const char *option_name)
void	options_builder_set_default_value_display (options_builder_t *builder, const char *option_name, const char *default_value)
void	options_builder_add_dependency_requires (options_builder_t *builder, const char *option_name, const char *depends_on, const char *error_message)
void	options_builder_add_dependency_conflicts (options_builder_t *builder, const char *option_name, const char *conflicts_with, const char *error_message)
void	options_builder_add_dependency_implies (options_builder_t *builder, const char *option_name, const char *implies, const char *error_message)
void	options_builder_add_dependency (options_builder_t *builder, const option_dependency_t *dependency)
void	options_builder_mark_binary_only (options_builder_t *builder, const char *option_name)
void	options_builder_add_positional (options_builder_t *builder, const char *name, const char *help_text, bool required, const char *section_heading, const char **examples, size_t num_examples, option_mode_bitmask_t mode_bitmask, int(*parse_fn)(const char *arg, void *config, char **remaining, int num_remaining, char **error_msg))
void	options_builder_add_usage (options_builder_t *builder, const char *mode, const char *positional, bool show_options, const char *description)
void	options_builder_add_example (options_builder_t *builder, uint32_t mode_bitmask, const char *args, const char *description, bool owns_args)
void	options_builder_add_example_utility (options_builder_t *builder, uint32_t mode_bitmask, const char *args, const char *description, bool is_utility_command)
	Add an example with utility command support.
void	options_builder_add_mode (options_builder_t *builder, const char *name, const char *description)
void	options_builder_add_custom_section (options_builder_t *builder, const char *heading, const char *content, option_mode_bitmask_t mode_bitmask)
asciichat_error_t	options_config_parse_positional (const options_config_t *config, int remaining_argc, char **remaining_argv, void *options_struct)
asciichat_error_t	options_config_set_defaults (const options_config_t *config, void *options_struct)
const option_descriptor_t *	find_option_descriptor (const options_config_t *config, const char *opt_name)
	Find option descriptor by short or long name.
asciichat_error_t	options_config_parse (const options_config_t *config, int argc, char **argv, void *options_struct, option_mode_bitmask_t detected_mode, int *remaining_argc, char ***remaining_argv)
asciichat_error_t	options_config_validate (const options_config_t *config, const void *options_struct, char **error_message)

Detailed Description

Implementation of options builder API.

Definition in file builder.c.

Macro Definition Documentation

asprintf

#define asprintf   platform_asprintf

Definition at line 25 of file builder.c.

Function Documentation

ensure_dependency_capacity()

void ensure_dependency_capacity

(

options_builder_t *

builder

)

Grow dependency array if needed.

Definition at line 203 of file builder.c.

                                                            {
  if (builder->num_dependencies >= builder->dependency_capacity) {
    size_t new_capacity = builder->dependency_capacity * 2;
    option_dependency_t *new_dependencies =
        SAFE_REALLOC(builder->dependencies, new_capacity * sizeof(option_dependency_t), option_dependency_t *);
    if (!new_dependencies) {
      log_fatal("Failed to reallocate dependencies array");
      return;
    }
    builder->dependencies = new_dependencies;
    builder->dependency_capacity = new_capacity;
  }
}

Referenced by options_builder_add_dependency(), options_builder_add_dependency_conflicts(), options_builder_add_dependency_implies(), and options_builder_add_dependency_requires().

ensure_descriptor_capacity()

void ensure_descriptor_capacity

(

options_builder_t *

builder

)

Grow descriptor array if needed.

Definition at line 186 of file builder.c.

                                                            {
  if (builder->num_descriptors >= builder->descriptor_capacity) {
    size_t new_capacity = builder->descriptor_capacity * 2;
    option_descriptor_t *new_descriptors =
        SAFE_REALLOC(builder->descriptors, new_capacity * sizeof(option_descriptor_t), option_descriptor_t *);
    if (!new_descriptors) {
      log_fatal("Failed to reallocate descriptors array");
      return;
    }
    builder->descriptors = new_descriptors;
    builder->descriptor_capacity = new_capacity;
  }
}

Referenced by options_builder_add_action(), options_builder_add_bool(), options_builder_add_callback(), options_builder_add_callback_optional(), options_builder_add_callback_with_metadata(), options_builder_add_descriptor(), options_builder_add_double(), options_builder_add_double_with_metadata(), options_builder_add_int(), options_builder_add_int_with_metadata(), and options_builder_add_string().

ensure_positional_arg_capacity()

void ensure_positional_arg_capacity

(

options_builder_t *

builder

)

Grow positional arg array if needed.

Definition at line 220 of file builder.c.

                                                                {
  if (builder->num_positional_args >= builder->positional_arg_capacity) {
    size_t new_capacity = builder->positional_arg_capacity * 2;
    if (new_capacity == 0)
      new_capacity = INITIAL_POSITIONAL_ARG_CAPACITY;
 
    positional_arg_descriptor_t *new_positional = SAFE_REALLOC(
        builder->positional_args, new_capacity * sizeof(positional_arg_descriptor_t), positional_arg_descriptor_t *);
    if (!new_positional) {
      log_fatal("Failed to reallocate positional_args array");
      return;
    }
    builder->positional_args = new_positional;
    builder->positional_arg_capacity = new_capacity;
  }
}

Referenced by options_builder_add_positional().

find_option()

const option_descriptor_t * find_option	(	const options_config_t *	config,
		const char *	long_name
	)

Find option descriptor by long name.

Definition at line 317 of file builder.c.

                                                                                              {
  for (size_t i = 0; i < config->num_descriptors; i++) {
    if (strcmp(config->descriptors[i].long_name, long_name) == 0) {
      return &config->descriptors[i];
    }
  }
  return NULL;
}

Referenced by is_option_set().

find_option_descriptor()

const option_descriptor_t * find_option_descriptor	(	const options_config_t *	config,
		const char *	opt_name
	)

Find option descriptor by short or long name.

Definition at line 1453 of file builder.c.

                                                                                                        {
  if (!opt_name || opt_name[0] == '\0')
    return NULL;
 
  // Handle short options: -x (single dash, single char)
  if (opt_name[0] == '-' && opt_name[1] != '-' && opt_name[1] != '\0') {
    // This is a short option like -x
    char short_char = opt_name[1];
    for (size_t i = 0; i < config->num_descriptors; i++) {
      if (config->descriptors[i].short_name == short_char) {
        return &config->descriptors[i];
      }
    }
    // Short option not found
    return NULL;
  }
 
  // Handle long options: --name (double dash)
  if (opt_name[0] == '-' && opt_name[1] == '-' && opt_name[2] != '\0') {
    const char *long_name = opt_name + 2; // Skip the '--'
    for (size_t i = 0; i < config->num_descriptors; i++) {
      if (strcmp(config->descriptors[i].long_name, long_name) == 0) {
        return &config->descriptors[i];
      }
    }
    // Long option not found
    return NULL;
  }
 
  // Not a recognized option format
  return NULL;
}

format_option_default_value_str()

int format_option_default_value_str	(	const option_descriptor_t *	desc,
		char *	buf,
		size_t	bufsize
	)

Format option default value as a string.

Parameters

desc	Option descriptor
buf	Output buffer
bufsize	Size of buffer

Returns

Number of characters written to buf

Definition at line 56 of file builder.c.

                                                                                                {
  if (!desc || !buf || bufsize == 0) {
    return 0;
  }
 
  // For callback options with enums, look up the enum string by matching the default value
  if (desc->type == OPTION_TYPE_CALLBACK && desc->metadata.enum_values && desc->default_value) {
    int default_int_val = 0;
    memcpy(&default_int_val, desc->default_value, sizeof(int));
 
    // Try to find matching enum value
    if (desc->metadata.enum_integer_values) {
      for (size_t i = 0; desc->metadata.enum_values[i] != NULL; i++) {
        if (desc->metadata.enum_integer_values[i] == default_int_val) {
          return safe_snprintf(buf, bufsize, "%s", desc->metadata.enum_values[i]);
        }
      }
    } else {
      // Fallback: assume sequential 0-based indices if integer values not provided
      // Count enum values to check bounds
      size_t enum_count = 0;
      while (desc->metadata.enum_values[enum_count] != NULL) {
        enum_count++;
      }
      if (default_int_val >= 0 && (size_t)default_int_val < enum_count) {
        return safe_snprintf(buf, bufsize, "%s", desc->metadata.enum_values[default_int_val]);
      }
    }
  }
 
  // For callback options storing numeric types (int/double/float), format them as numbers
  if (desc->type == OPTION_TYPE_CALLBACK && desc->default_value && desc->metadata.enum_values == NULL) {
    // Check if this is a numeric callback by looking for numeric_range metadata
    // Numeric callbacks have min/max range constraints set (max != 0 indicates a range was set)
    if (desc->metadata.numeric_range.max != 0 || desc->metadata.numeric_range.min != 0) {
      // This is a numeric callback option - extract and format the value
      // Determine if it's int or double based on range (int max is 2147483647)
      double default_double = 0.0;
      if (desc->metadata.numeric_range.max <= 2147483647.0 && desc->metadata.numeric_range.min >= -2147483648.0) {
        // Integer-ranged value (like port 1-65535) - stored as int
        int default_int = 0;
        memcpy(&default_int, desc->default_value, sizeof(int));
        default_double = (double)default_int;
      } else {
        // Double-ranged value - stored as double
        memcpy(&default_double, desc->default_value, sizeof(double));
      }
 
      // Format with appropriate precision (remove trailing zeros for integers)
      char formatted[32];
      safe_snprintf(formatted, sizeof(formatted), "%.1f", default_double);
 
      // Remove trailing zeros after decimal point
      char *dot = strchr(formatted, '.');
      if (dot) {
        char *end = formatted + strlen(formatted) - 1;
        while (end > dot && *end == '0') {
          end--;
        }
        if (*end == '.') {
          *end = '\0';
        } else {
          *(end + 1) = '\0';
        }
      }
 
      return safe_snprintf(buf, bufsize, "%s", formatted);
    }
  }
 
  // For callback options with string defaults (no enum, no numeric range)
  // Treat default_value as a const char* string pointer
  if (desc->type == OPTION_TYPE_CALLBACK && desc->default_value && desc->metadata.enum_values == NULL &&
      desc->metadata.numeric_range.max == 0 && desc->metadata.numeric_range.min == 0) {
    const char *str_default = (const char *)desc->default_value;
    if (str_default && str_default[0] != '\0') {
      return safe_snprintf(buf, bufsize, "%s", str_default);
    }
  }
 
  return options_format_default_value(desc->type, desc->default_value, buf, bufsize);
}

References options_format_default_value(), and safe_snprintf().

Referenced by options_config_print_options_sections_with_width(), and options_config_print_usage().

get_option_help_placeholder_str()

const char * get_option_help_placeholder_str

(

const option_descriptor_t *

desc

)

Get help placeholder string for an option type.

Parameters

desc	Option descriptor

Returns

Pointer to string literal ("INTEGER", "NUMBER", "STRING", "VALUE", "[BOOLEAN]"), custom placeholder, or empty string

Definition at line 38 of file builder.c.

                                                                             {
  if (!desc) {
    return "";
  }
  // Check for custom placeholder first
  if (desc->arg_placeholder != NULL) {
    return desc->arg_placeholder;
  }
  return options_get_type_placeholder(desc->type);
}

References options_get_type_placeholder().

Referenced by options_config_print_options_sections_with_width(), and options_config_print_usage().

is_option_set()

bool is_option_set	(	const options_config_t *	config,
		const void *	options_struct,
		const char *	option_name
	)

Check if an option is set (has non-default value)

Definition at line 329 of file builder.c.

                                                                                                        {
  const option_descriptor_t *desc = find_option(config, option_name);
  if (!desc)
    return false;
 
  const char *base = (const char *)options_struct;
  const void *field = base + desc->offset;
 
  // Use handler registry to check if option is set
  if (desc->type >= 0 && desc->type < (int)(NUM_OPTION_TYPES)) {
    if (g_builder_handlers[desc->type].is_set) {
      return g_builder_handlers[desc->type].is_set(field, desc);
    }
  }
 
  return false;
}

References find_option(), and g_builder_handlers.

Referenced by options_config_validate().

option_applies_to_mode()

bool option_applies_to_mode	(	const option_descriptor_t *	desc,
		asciichat_mode_t	mode,
		bool	for_binary_help
	)

Check if an option applies to a specific mode using bitmask.

Parameters

desc	Option descriptor
mode	Mode to check (use invalid value like -1 for binary help)
for_binary_help	If true, show binary options; if false, hide them

Returns

true if option should be shown for this mode

Definition at line 150 of file builder.c.

                                                                                                          {
  if (!desc) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Descriptor is NULL");
    return false;
  }
 
  // When for_binary_help is true (i.e., for 'ascii-chat --help'),
  // show options that apply to the default mode (DISCOVERY) or binary-level options only.
  // Don't show mode-specific options for other modes (server, client, mirror, discovery-service).
  if (for_binary_help) {
    // Binary-level options or options that apply to discovery mode (the default)
    option_mode_bitmask_t default_modes = OPTION_MODE_BINARY | OPTION_MODE_DISCOVERY;
    return (desc->mode_bitmask & default_modes) != 0 && !desc->hide_from_binary_help;
  }
 
  // For mode-specific help (non-discovery modes), show only options for that mode.
  // Do not show binary options here unless it also specifically applies to the mode.
  // The 'mode' parameter is the actual mode (e.g., MODE_CLIENT, MODE_SERVER).
  if (mode < 0 || mode > MODE_DISCOVERY) { // Use MODE_INVALID as upper bound for valid modes
    return false;
  }
  option_mode_bitmask_t mode_bit = (1 << mode);
 
  // Check if it's a binary option. If so, only show if it also explicitly applies to this mode.
  if ((desc->mode_bitmask & OPTION_MODE_BINARY) && !(desc->mode_bitmask & mode_bit)) {
    return false; // Binary options not shown in mode-specific help unless also mode-specific
  }
 
  bool applies = (desc->mode_bitmask & mode_bit) != 0;
 
  return applies && !desc->hide_from_mode_help;
}

Referenced by options_config_print_options_sections_with_width(), and options_config_print_usage().

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
	)

Definition at line 919 of file builder.c.

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

References ensure_descriptor_capacity().

Referenced by options_registry_add_all_to_builder().

options_builder_add_bool()

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

Definition at line 627 of file builder.c.

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

References ensure_descriptor_capacity().

Referenced by options_registry_add_all_to_builder().

options_builder_add_callback()

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

Definition at line 825 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,
                              .mode_bitmask = OPTION_MODE_NONE};
 
  builder->descriptors[builder->num_descriptors++] = desc;
}

References ensure_descriptor_capacity().

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 866 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,
                              .mode_bitmask = OPTION_MODE_NONE};
 
  builder->descriptors[builder->num_descriptors++] = desc;
}

References ensure_descriptor_capacity().

options_builder_add_callback_with_metadata()

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

Definition at line 892 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,
                              .mode_bitmask = OPTION_MODE_NONE,
                              .metadata = metadata ? *metadata : (option_metadata_t){0}};
 
  builder->descriptors[builder->num_descriptors++] = desc;
}

References ensure_descriptor_capacity().

Referenced by options_registry_add_all_to_builder().

options_builder_add_custom_section()

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

Definition at line 1295 of file builder.c.

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

Referenced by options_preset_unified().

options_builder_add_dependency()

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

Definition at line 1140 of file builder.c.

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

References ensure_dependency_capacity().

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
	)

Definition at line 1118 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 ensure_dependency_capacity().

Referenced by options_preset_unified().

options_builder_add_dependency_implies()

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

Definition at line 1130 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 ensure_dependency_capacity().

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
	)

Definition at line 1106 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 ensure_dependency_capacity().

Referenced by options_preset_unified().

options_builder_add_descriptor()

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

Definition at line 949 of file builder.c.

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

References ensure_descriptor_capacity().

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

                                                                                                   {
  ensure_descriptor_capacity(builder);
 
  // Increased from 256 to 1024 to support multiple test builders without overflow
  static double defaults[1024];
  static size_t num_defaults = 0;
 
  if (num_defaults >= 1024) {
    log_error("Too many double options (max 1024)");
    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,
                              .mode_bitmask = OPTION_MODE_NONE};
 
  builder->descriptors[builder->num_descriptors++] = desc;
}

References ensure_descriptor_capacity().

Referenced by options_registry_add_all_to_builder().

options_builder_add_double_with_metadata()

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

Definition at line 790 of file builder.c.

                                                                                 {
  ensure_descriptor_capacity(builder);
 
  static double defaults[1024];
  static size_t num_defaults = 0;
 
  if (num_defaults >= 1024) {
    log_error("Too many double options (max 1024)");
    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,
                              .mode_bitmask = OPTION_MODE_NONE,
                              .metadata = metadata ? *metadata : (option_metadata_t){0}};
 
  builder->descriptors[builder->num_descriptors++] = desc;
}

References ensure_descriptor_capacity().

Referenced by options_registry_add_all_to_builder().

options_builder_add_example()

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

Definition at line 1231 of file builder.c.

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

References args, and platform_strdup().

Referenced by options_preset_unified().

options_builder_add_example_utility()

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

Add an example with utility command support.

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

Definition at line 1265 of file builder.c.

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

References args.

Referenced by options_preset_unified().

options_builder_add_int()

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

Definition at line 651 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,
                              .mode_bitmask = OPTION_MODE_NONE};
 
  builder->descriptors[builder->num_descriptors++] = desc;
}

References ensure_descriptor_capacity().

Referenced by options_registry_add_all_to_builder().

options_builder_add_int_with_metadata()

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

Definition at line 684 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,
                              .mode_bitmask = OPTION_MODE_NONE,
                              .metadata = metadata ? *metadata : (option_metadata_t){0}};
 
  builder->descriptors[builder->num_descriptors++] = desc;
}

References ensure_descriptor_capacity().

Referenced by options_registry_add_all_to_builder().

options_builder_add_mode()

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

Definition at line 1284 of file builder.c.

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

Referenced by options_preset_unified().

options_builder_add_positional()

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

Definition at line 1168 of file builder.c.

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

References ensure_positional_arg_capacity().

Referenced by options_builder_from_preset(), and options_preset_unified().

options_builder_add_string()

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

Definition at line 720 of file builder.c.

                                                                                                   {
  ensure_descriptor_capacity(builder);
 
  // Store default string pointer in static storage to avoid stack-use-after-return
  // Increased from 256 to 1024 to support multiple test builders without overflow
  static const char *defaults[1024];
  static size_t num_defaults = 0;
 
  const void *default_ptr = NULL;
  if (default_value) {
    if (num_defaults >= 1024) {
      log_error("Too many string options (max 1024)");
      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
                              .mode_bitmask = OPTION_MODE_NONE};
 
  builder->descriptors[builder->num_descriptors++] = desc;
}

References ensure_descriptor_capacity().

Referenced by options_registry_add_all_to_builder().

options_builder_add_usage()

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

Definition at line 1218 of file builder.c.

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

References usage().

Referenced by options_preset_unified().

options_builder_build()

options_config_t * options_builder_build

(

options_builder_t *

builder

)

Definition at line 452 of file builder.c.

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

Referenced by options_builder_generate_manpage_template(), and options_preset_unified().

options_builder_create()

options_builder_t * options_builder_create

(

size_t

struct_size

)

Definition at line 351 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->usage_lines = NULL;
  builder->num_usage_lines = 0;
  builder->usage_line_capacity = 0;
  builder->examples = NULL;
  builder->num_examples = 0;
  builder->example_capacity = 0;
  builder->modes = NULL;
  builder->num_modes = 0;
  builder->mode_capacity = 0;
  builder->custom_sections = NULL;
  builder->num_custom_sections = 0;
  builder->custom_section_capacity = 0;
  builder->struct_size = struct_size;
  builder->program_name = NULL;
  builder->description = NULL;
  builder->owned_strings_builder = NULL;
  builder->num_owned_strings_builder = 0;
  builder->owned_strings_builder_capacity = 0;
 
  return builder;
}

Referenced by options_builder_from_preset(), and options_preset_unified().

options_builder_destroy()

void options_builder_destroy

(

options_builder_t *

builder

)

Definition at line 437 of file builder.c.

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

Referenced by options_preset_unified().

options_builder_from_preset()

options_builder_t * options_builder_from_preset

(

const options_config_t *

preset

)

Definition at line 402 of file builder.c.

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

References options_builder_add_dependency(), options_builder_add_descriptor(), options_builder_add_positional(), and options_builder_create().

options_builder_mark_as_list()

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

Definition at line 1069 of file builder.c.

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

options_builder_mark_binary_only()

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

Definition at line 1148 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);
}

options_builder_set_arg_placeholder()

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

Definition at line 968 of file builder.c.

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

Referenced by options_registry_add_all_to_builder().

options_builder_set_default_value_display()

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

Definition at line 1085 of file builder.c.

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

options_builder_set_enum_values()

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

Definition at line 998 of file builder.c.

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

options_builder_set_examples()

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

Definition at line 1035 of file builder.c.

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

options_builder_set_input_type()

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

Definition at line 1052 of file builder.c.

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

options_builder_set_mode_bitmask()

void options_builder_set_mode_bitmask	(	options_builder_t *	builder,
		option_mode_bitmask_t	mode_bitmask
	)

Definition at line 960 of file builder.c.

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

Referenced by options_registry_add_all_to_builder().

options_builder_set_numeric_range()

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

Definition at line 1016 of file builder.c.

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

options_config_destroy()

void options_config_destroy

(

options_config_t *

config

)

Definition at line 601 of file builder.c.

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

Referenced by options_init(), and usage().

options_config_parse()

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

Definition at line 1750 of file builder.c.

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

Referenced by options_init().

options_config_parse_positional()

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

Definition at line 1307 of file builder.c.

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

options_config_set_defaults()

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

Definition at line 1376 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);
    }
 
    // Use handler registry to apply environment variables and defaults
    if (desc->type >= 0 && desc->type < (int)(NUM_OPTION_TYPES)) {
      if (g_builder_handlers[desc->type].apply_env) {
        g_builder_handlers[desc->type].apply_env(field, env_value, desc);
      }
    } else if (desc->type == OPTION_TYPE_CALLBACK && desc->parse_fn && desc->default_value) {
      // Special handling for callbacks with parse_fn
      char *error_msg = NULL;
      desc->parse_fn(NULL, field, &error_msg);
      if (error_msg) {
        free(error_msg);
      }
    }
  }
 
  return ASCIICHAT_OK;
}

References g_builder_handlers.

Referenced by options_init().

options_config_validate()

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

Definition at line 1775 of file builder.c.

                                                                {
  if (!config || !options_struct) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Config or options struct is NULL");
  }
 
  const char *base = (const char *)options_struct;
 
  // Check required fields
  for (size_t i = 0; i < config->num_descriptors; i++) {
    const option_descriptor_t *desc = &config->descriptors[i];
    if (!desc->required)
      continue;
 
    const void *field = base + desc->offset;
    // Use handler registry to check if option is set (for required field validation)
    bool is_set = true;
    if (desc->type >= 0 && desc->type < (int)(NUM_OPTION_TYPES)) {
      if (g_builder_handlers[desc->type].is_set) {
        is_set = g_builder_handlers[desc->type].is_set(field, desc);
      }
    }
 
    if (!is_set) {
      if (error_message) {
        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 = platform_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 = platform_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;
    }
  }
 
  // Cross-field validation: Check for conflicting color options
  // Cannot use --color with --color-mode none
  const options_t *opts = (const options_t *)options_struct;
  if (opts->color && opts->color_mode == TERM_COLOR_NONE) {
    if (error_message) {
      asprintf(error_message, "Option --color cannot be used with --color-mode=none (conflicting color settings)");
    }
    return ERROR_USAGE;
  }
 
  return ASCIICHAT_OK;
}

References asprintf, g_builder_handlers, is_option_set(), is_set, and platform_strdup().

Referenced by validate_options_and_report().