core.h File Reference

Internal helper functions and data for registry implementation. More...

Go to the source code of this file.

Functions
void	registry_init_from_builders (void)
	Initialize registry from category builders Populates g_options_registry by concatenating all category arrays.
asciichat_error_t	registry_validate_unique_options (void)
	Validate that no short or long options appear more than once in the registry.
void	registry_init_size (void)
	Initialize registry size and metadata.
const registry_entry_t *	registry_find_entry_by_name (const char *long_name)
	Get a registry entry by long name.
const registry_entry_t *	registry_find_entry_by_short (char short_name)
	Get a registry entry by short name.
option_descriptor_t	registry_entry_to_descriptor (const registry_entry_t *entry)
	Convert registry entry to option descriptor.
bool	registry_entry_applies_to_mode (const registry_entry_t *entry, asciichat_mode_t mode, bool for_binary_help)
	Check if an option applies to the given mode for display purposes.

Variables
registry_entry_t	g_options_registry [2048]
size_t	g_registry_size
bool	g_metadata_populated
category_builder_t	g_category_builders []

Detailed Description

Internal helper functions and data for registry implementation.

This header declares internal helper functions and global registry data that are used by core.c and public_api.c. These are NOT part of the public API.

Author

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

Date

January 2026

Definition in file core.h.

Function Documentation

registry_entry_applies_to_mode()

bool registry_entry_applies_to_mode	(	const registry_entry_t *	entry,
		asciichat_mode_t	mode,
		bool	for_binary_help
	)

Check if an option applies to the given mode for display purposes.

This implements the same filtering logic as the help system's option_applies_to_mode(). Used by options_registry_get_for_display() to ensure completions match help output.

Parameters

entry	Registry entry to check
mode	Mode to check (use MODE_DISCOVERY for binary help)
for_binary_help	If true, show all options for any mode; if false, filter by mode

Returns

true if option should be displayed for this mode

Definition at line 200 of file core.c.

                                                                                                                {
  if (!entry) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Entry is NULL");
    return false;
  }
 
  // Hardcoded list of options to hide from binary help (matches builder.c line 752)
  // These are options that have hide_from_binary_help=true set in builder.c
  const char *hidden_from_binary[] = {NULL};
 
  // When for_binary_help is true (i.e., for 'ascii-chat --help'),
  // we want to show all options that apply to any mode, plus binary-level options.
  if (for_binary_help) {
    // Check if this option is explicitly hidden from binary help
    for (int i = 0; hidden_from_binary[i] != NULL; i++) {
      if (strcmp(entry->long_name, hidden_from_binary[i]) == 0) {
        return false; // Hidden from binary help
      }
    }
 
    // An option applies if its mode_bitmask has any bit set for any valid mode.
    // OPTION_MODE_ALL is a bitmask of all modes (including OPTION_MODE_BINARY).
    return (entry->mode_bitmask & OPTION_MODE_ALL) != 0;
  }
 
  // For mode-specific help, show only options for that mode.
  // Do not show binary options here unless it also specifically applies to the mode.
  if (mode < 0 || mode > MODE_DISCOVERY) {
    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 ((entry->mode_bitmask & OPTION_MODE_BINARY) && !(entry->mode_bitmask & mode_bit)) {
    return false; // Binary options not shown in mode-specific help unless also mode-specific
  }
 
  return (entry->mode_bitmask & mode_bit) != 0;
}

References ERROR_INVALID_PARAM, registry_entry_t::long_name, registry_entry_t::mode_bitmask, MODE_DISCOVERY, OPTION_MODE_ALL, OPTION_MODE_BINARY, and SET_ERRNO.

Referenced by options_registry_get_for_display().

registry_entry_to_descriptor()

option_descriptor_t registry_entry_to_descriptor

(

const registry_entry_t *

entry

)

Convert registry entry to option descriptor.

Definition at line 161 of file core.c.

                                                                                {
  option_descriptor_t desc = {0};
  if (entry) {
    desc.long_name = entry->long_name;
    desc.short_name = entry->short_name;
    desc.type = entry->type;
    desc.offset = entry->offset;
    desc.help_text = entry->help_text;
    desc.group = entry->group;
    desc.arg_placeholder = entry->arg_placeholder;
    desc.hide_from_mode_help = false;
    // Hide discovery service options from binary-level help (they're for discovery-service mode only)
    desc.hide_from_binary_help = (entry->mode_bitmask == OPTION_MODE_DISCOVERY_SVC);
    desc.default_value = entry->default_value;
    desc.required = entry->required;
    desc.env_var_name = entry->env_var_name;
    desc.validate = entry->validate_fn;
    desc.parse_fn = entry->parse_fn;
    desc.action_fn = NULL;
    desc.owns_memory = entry->owns_memory;
    desc.optional_arg = entry->optional_arg;
    desc.mode_bitmask = entry->mode_bitmask;
    desc.metadata = entry->metadata;
    desc.mode_default_getter = entry->mode_default_getter;
  }
  return desc;
}

References option_descriptor_t::action_fn, option_descriptor_t::arg_placeholder, registry_entry_t::arg_placeholder, option_descriptor_t::default_value, registry_entry_t::default_value, option_descriptor_t::env_var_name, registry_entry_t::env_var_name, option_descriptor_t::group, registry_entry_t::group, option_descriptor_t::help_text, registry_entry_t::help_text, option_descriptor_t::hide_from_binary_help, option_descriptor_t::hide_from_mode_help, option_descriptor_t::long_name, registry_entry_t::long_name, option_descriptor_t::metadata, registry_entry_t::metadata, option_descriptor_t::mode_bitmask, registry_entry_t::mode_bitmask, option_descriptor_t::mode_default_getter, registry_entry_t::mode_default_getter, option_descriptor_t::offset, registry_entry_t::offset, OPTION_MODE_DISCOVERY_SVC, option_descriptor_t::optional_arg, registry_entry_t::optional_arg, option_descriptor_t::owns_memory, registry_entry_t::owns_memory, option_descriptor_t::parse_fn, registry_entry_t::parse_fn, option_descriptor_t::required, registry_entry_t::required, option_descriptor_t::short_name, registry_entry_t::short_name, option_descriptor_t::type, registry_entry_t::type, option_descriptor_t::validate, and registry_entry_t::validate_fn.

Referenced by options_registry_get_binary_options(), options_registry_get_for_display(), and options_registry_get_for_mode().

registry_find_entry_by_name()

const registry_entry_t * registry_find_entry_by_name

(

const char *

long_name

)

Get a registry entry by long name.

Note

This is used internally for option lookup

Definition at line 127 of file core.c.

                                                                           {
  if (!long_name) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Long name is NULL");
    return NULL;
  }
 
  for (size_t i = 0; g_options_registry[i].long_name != NULL; i++) {
    if (strcmp(g_options_registry[i].long_name, long_name) == 0) {
      return &g_options_registry[i];
    }
  }
  return NULL;
}

References ERROR_INVALID_PARAM, g_options_registry, registry_entry_t::long_name, and SET_ERRNO.

Referenced by options_registry_find_by_name().

registry_find_entry_by_short()

const registry_entry_t * registry_find_entry_by_short

(

char

short_name

)

Get a registry entry by short name.

Note

This is used internally for option lookup

Definition at line 145 of file core.c.

                                                                      {
  if (short_name == '\0') {
    return NULL;
  }
 
  for (size_t i = 0; g_options_registry[i].long_name != NULL; i++) {
    if (g_options_registry[i].short_name == short_name) {
      return &g_options_registry[i];
    }
  }
  return NULL;
}

References g_options_registry, and registry_entry_t::long_name.

Referenced by options_registry_find_by_short().

registry_init_from_builders()

void registry_init_from_builders

(

void

)

Initialize registry from category builders Populates g_options_registry by concatenating all category arrays.

Definition at line 23 of file core.c.

                                       {
  static bool initialized = false;
  if (initialized) {
    return;
  }
 
  size_t offset = 0;
  for (int i = 0; g_category_builders[i].entries != NULL; i++) {
    // Count entries in this category (until sentinel terminator)
    size_t count = 0;
    for (const registry_entry_t *e = g_category_builders[i].entries; e->long_name != NULL; e++) {
      count++;
    }
 
    // Copy category entries (count already excludes sentinel)
    if (offset + count <= 2048) {
      memcpy(&g_options_registry[offset], g_category_builders[i].entries, count * sizeof(registry_entry_t));
      offset += count;
    }
  }
 
  // Add final null terminator
  if (offset < 2048) {
    g_options_registry[offset] = (registry_entry_t){.long_name = NULL,
                                                    .short_name = '\0',
                                                    .type = OPTION_TYPE_BOOL,
                                                    .offset = 0,
                                                    .default_value = NULL,
                                                    .default_value_size = 0,
                                                    .help_text = NULL,
                                                    .group = NULL,
                                                    .required = false,
                                                    .env_var_name = NULL,
                                                    .validate_fn = NULL,
                                                    .parse_fn = NULL,
                                                    .owns_memory = false,
                                                    .optional_arg = false,
                                                    .mode_bitmask = OPTION_MODE_NONE,
                                                    .metadata = {0}};
  }
 
  initialized = true;
}

References category_builder_t::entries, g_category_builders, g_options_registry, initialized, registry_entry_t::long_name, OPTION_MODE_NONE, and OPTION_TYPE_BOOL.

Referenced by registry_init_size().

registry_init_size()

void registry_init_size

(

void

)

Initialize registry size and metadata.

Definition at line 108 of file core.c.

                              {
  registry_init_from_builders();
 
  if (g_registry_size == 0) {
    for (size_t i = 0; g_options_registry[i].long_name != NULL; i++) {
      g_registry_size++;
    }
    // Validate that all options have unique short and long names
    registry_validate_unique_options();
    // DEPRECATED: Metadata is now initialized compile-time in registry entries
    // registry_populate_metadata_for_critical_options();
    g_metadata_populated = true;
  }
}

References g_metadata_populated, g_options_registry, g_registry_size, registry_entry_t::long_name, registry_init_from_builders(), and registry_validate_unique_options().

Referenced by options_get_help_text(), options_registry_add_all_to_builder(), options_registry_find_by_name(), options_registry_find_by_short(), options_registry_get_binary_options(), options_registry_get_count(), options_registry_get_for_display(), options_registry_get_for_mode(), options_registry_get_metadata(), options_registry_get_raw(), and options_state_init().

registry_validate_unique_options()

asciichat_error_t registry_validate_unique_options

(

void

)

Validate that no short or long options appear more than once in the registry.

Returns

Result of SET_ERRNO if duplicates found, ASCIICHAT_OK if valid

Definition at line 71 of file core.c.

                                                         {
  // Check for duplicate long options
  for (size_t i = 0; g_options_registry[i].long_name != NULL; i++) {
    const char *long_name = g_options_registry[i].long_name;
    if (!long_name || long_name[0] == '\0') {
      continue; // Skip empty long names
    }
 
    for (size_t j = i + 1; g_options_registry[j].long_name != NULL; j++) {
      if (strcmp(g_options_registry[j].long_name, long_name) == 0) {
        return SET_ERRNO(ERROR_CONFIG, "Duplicate long option '--%s' at registry indices %zu and %zu", long_name, i, j);
      }
    }
  }
 
  // Check for duplicate short options (skip if '\0')
  for (size_t i = 0; g_options_registry[i].long_name != NULL; i++) {
    char short_name = g_options_registry[i].short_name;
    if (short_name == '\0') {
      continue; // Skip if no short option
    }
 
    for (size_t j = i + 1; g_options_registry[j].long_name != NULL; j++) {
      if (g_options_registry[j].short_name == short_name) {
        return SET_ERRNO(ERROR_CONFIG,
                         "Duplicate short option '-%c' for '--%s' and '--%s' at registry indices %zu and %zu",
                         short_name, g_options_registry[i].long_name, g_options_registry[j].long_name, i, j);
      }
    }
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_CONFIG, g_options_registry, registry_entry_t::long_name, SET_ERRNO, and registry_entry_t::short_name.

Referenced by registry_init_size().

Variable Documentation

g_category_builders

category_builder_t g_category_builders[]

extern

Definition at line 27 of file registry.c.

                                           {{g_general_entries, "GENERAL"},
                                            {g_logging_entries, "LOGGING"},
                                            {g_terminal_entries, "TERMINAL"},
                                            {g_configuration_entries, "CONFIGURATION"},
                                            {g_display_entries, "DISPLAY"},
                                            {g_webcam_entries, "WEBCAM"},
                                            {g_audio_entries, "AUDIO"},
                                            {g_media_entries, "MEDIA"},
                                            {g_network_entries, "NETWORK"},
                                            {g_security_entries, "SECURITY"},
                                            {g_database_entries, "DATABASE"},
                                            {g_debug_entries, "DEBUG"},
                                            {NULL, NULL}};

Referenced by registry_init_from_builders().

g_metadata_populated

bool g_metadata_populated

extern

Definition at line 54 of file registry.c.

Referenced by registry_init_size().

g_options_registry

registry_entry_t g_options_registry[2048]

extern

Definition at line 51 of file registry.c.

Referenced by options_get_help_text(), options_registry_add_all_to_builder(), options_registry_get_binary_options(), options_registry_get_for_display(), options_registry_get_for_mode(), options_registry_get_metadata(), options_registry_get_raw(), registry_find_entry_by_name(), registry_find_entry_by_short(), registry_init_from_builders(), registry_init_size(), and registry_validate_unique_options().

g_registry_size

size_t g_registry_size

extern

Definition at line 53 of file registry.c.

Referenced by options_get_help_text(), options_registry_add_all_to_builder(), options_registry_get_binary_options(), options_registry_get_count(), options_registry_get_for_display(), options_registry_get_for_mode(), options_registry_get_metadata(), and registry_init_size().