internal.h File Reference

Internal declarations for builder implementation. More...

Go to the source code of this file.

Data Structures
struct	option_builder_handler_t
	Type handler for builder operations. More...

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

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.
void	ensure_owned_strings_capacity (options_builder_t *builder)
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)

Variables
const option_builder_handler_t	g_builder_handlers []

Detailed Description

Internal declarations for builder implementation.

Shared structures and forward declarations used across builder modules.

Author

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

Date

January 2026

Definition in file options/builder/internal.h.

Macro Definition Documentation

INITIAL_DEPENDENCY_CAPACITY

#define INITIAL_DEPENDENCY_CAPACITY   16

Definition at line 21 of file options/builder/internal.h.

INITIAL_DESCRIPTOR_CAPACITY

#define INITIAL_DESCRIPTOR_CAPACITY   32

Definition at line 20 of file options/builder/internal.h.

INITIAL_OWNED_STRINGS_CAPACITY

#define INITIAL_OWNED_STRINGS_CAPACITY   32

Definition at line 23 of file options/builder/internal.h.

INITIAL_POSITIONAL_ARG_CAPACITY

#define INITIAL_POSITIONAL_ARG_CAPACITY   8

Definition at line 22 of file options/builder/internal.h.

NUM_OPTION_TYPES

#define NUM_OPTION_TYPES   6

Definition at line 41 of file options/builder/internal.h.

Function Documentation

ensure_dependency_capacity()

void ensure_dependency_capacity

(

options_builder_t *

builder

)

Grow dependency array if needed.

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

References options_builder_t::dependencies, options_builder_t::dependency_capacity, log_fatal, options_builder_t::num_dependencies, and SAFE_REALLOC.

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 213 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;
  }
}

References options_builder_t::descriptor_capacity, options_builder_t::descriptors, log_fatal, options_builder_t::num_descriptors, and SAFE_REALLOC.

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

void ensure_owned_strings_capacity

(

options_builder_t *

builder

)

ensure_positional_arg_capacity()

void ensure_positional_arg_capacity

(

options_builder_t *

builder

)

Grow positional arg array if needed.

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

References INITIAL_POSITIONAL_ARG_CAPACITY, log_fatal, options_builder_t::num_positional_args, options_builder_t::positional_arg_capacity, options_builder_t::positional_args, and SAFE_REALLOC.

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 344 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;
}

References options_config_t::descriptors, option_descriptor_t::long_name, and options_config_t::num_descriptors.

Referenced by is_option_set().

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 83 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 option_descriptor_t::default_value, option_metadata_t::enum_integer_values, option_metadata_t::enum_values, option_metadata_t::max, option_descriptor_t::metadata, option_metadata_t::min, option_metadata_t::numeric_range, OPTION_TYPE_CALLBACK, options_format_default_value(), safe_snprintf(), and option_descriptor_t::type.

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

                                                                             {
  if (!desc) {
    return "";
  }
  // Check for custom placeholder first
  if (desc->arg_placeholder != NULL) {
    return desc->arg_placeholder;
  }
 
  // For callback options, check if it's a boolean based on enum values
  if (desc->type == OPTION_TYPE_CALLBACK && desc->metadata.enum_values) {
    // Check if enum values contain "true" and "false" (boolean-like)
    const char *const *values = desc->metadata.enum_values;
    bool has_true = false, has_false = false;
 
    for (int i = 0; values[i] != NULL; i++) {
      if (strcmp(values[i], "true") == 0 || strcmp(values[i], "yes") == 0 || strcmp(values[i], "on") == 0) {
        has_true = true;
      }
      if (strcmp(values[i], "false") == 0 || strcmp(values[i], "no") == 0 || strcmp(values[i], "off") == 0) {
        has_false = true;
      }
    }
 
    // If it has both true-like and false-like values, it's boolean
    if (has_true && has_false) {
      return "BOOLEAN";
    }
  }
 
  return options_get_type_placeholder(desc->type);
}

References option_descriptor_t::arg_placeholder, option_metadata_t::enum_values, option_descriptor_t::metadata, OPTION_TYPE_CALLBACK, options_get_type_placeholder(), and option_descriptor_t::type.

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 356 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(), g_builder_handlers, option_builder_handler_t::is_set, NUM_OPTION_TYPES, option_descriptor_t::offset, and option_descriptor_t::type.

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 177 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;
}

References ERROR_INVALID_PARAM, option_descriptor_t::hide_from_binary_help, option_descriptor_t::hide_from_mode_help, option_descriptor_t::mode_bitmask, MODE_DISCOVERY, OPTION_MODE_BINARY, OPTION_MODE_DISCOVERY, and SET_ERRNO.

Referenced by options_config_print_options_sections_with_width(), and options_config_print_usage().

Variable Documentation

g_builder_handlers

const option_builder_handler_t g_builder_handlers[]

extern

Definition at line 54 of file options/builder/handlers.c.

                                                      {
    [OPTION_TYPE_BOOL] = {is_set_bool, apply_env_bool, apply_cli_bool, format_help_placeholder_bool},
    [OPTION_TYPE_INT] = {is_set_int, apply_env_int, apply_cli_int, format_help_placeholder_int},
    [OPTION_TYPE_STRING] = {is_set_string, apply_env_string, apply_cli_string, format_help_placeholder_string},
    [OPTION_TYPE_DOUBLE] = {is_set_double, apply_env_double, apply_cli_double, format_help_placeholder_double},
    [OPTION_TYPE_CALLBACK] = {is_set_callback, apply_env_callback, apply_cli_callback,
                              format_help_placeholder_callback},
    [OPTION_TYPE_ACTION] = {is_set_action, apply_env_action, apply_cli_action, format_help_placeholder_action},
};

Referenced by is_option_set(), options_config_set_defaults(), and options_config_validate().