registry.h File Reference

Central registry of all command-line options with mode applicability. More...

Go to the source code of this file.

Functions
asciichat_error_t	options_registry_add_all_to_builder (options_builder_t *builder)
	Add all options from registry to builder.
const option_descriptor_t *	options_registry_find_by_name (const char *long_name)
	Get option descriptor by name.
const option_descriptor_t *	options_registry_find_by_short (char short_name)
	Get option descriptor by short name.
const option_descriptor_t *	options_registry_get_for_mode (asciichat_mode_t mode, size_t *num_options)
	Get all options for a specific mode.
const option_descriptor_t *	options_registry_get_binary_options (size_t *num_options)
	Get all binary-level options.
const option_descriptor_t *	options_registry_get_for_display (asciichat_mode_t mode, bool for_binary_help, size_t *num_options)
	Get options for help/completions display with unified filtering.
const option_metadata_t *	options_registry_get_metadata (const char *long_name)
	Get complete metadata for an option.
const char **	options_registry_get_enum_values (const char *option_name, const char ***descriptions, size_t *count)
	Get enum values for an option.
bool	options_registry_get_numeric_range (const char *option_name, int *min_out, int *max_out, int *step_out)
	Get numeric range for an option.
const char **	options_registry_get_examples (const char *option_name, size_t *count)
	Get example values for an option.
option_input_type_t	options_registry_get_input_type (const char *option_name)
	Get input type for an option.

Detailed Description

Central registry of all command-line options with mode applicability.

This module defines the single source of truth for all command-line options that can be used across all modes (server, client, mirror, discovery service, etc.).

Architecture Overview

The registry is the single source of truth for option definitions. It works with:

• Builder (builder.h): Use builder to construct custom option configurations, populated from the registry via options_registry_add_all_to_builder().
• RCU Thread-Safety (rcu.h): Registered options are parsed and published to RCU for lock-free thread-safe access via GET_OPTION() macro.
• Options System (options.h): The unified parsing system uses the registry to build option configurations for different modes.

Design Philosophy

• Single Definition: Each option defined exactly once with all metadata (no duplication)
• Mode Bitmasks: Each option includes mode_bitmask indicating which modes it applies to
• Automatic Filtering: Registry functions automatically filter by mode
• Immutable After Load: Once loaded, registry is read-only (no runtime modifications)
• Shared with Builder: Registry options added to builder via options_registry_add_all_to_builder()
• Completion Metadata: Each option includes shell completion hints (enums, ranges, examples)

Registry Structure

The registry is defined in registry.c as a static array of option_descriptor_t structures. Each descriptor includes complete metadata:

Identification:

• Long name (e.g., "port")
• Short name (e.g., 'p')
• Argument placeholder (e.g., "NUM", "STR", "PATH")

Type and Storage:

• Type: BOOL, INT, STRING, DOUBLE, CALLBACK, ACTION
• Offset into options_t struct (via offsetof())

Documentation:

• Help text (brief description for –help output)
• Group name (for organizing help sections: "NETWORK OPTIONS", "DISPLAY OPTIONS", etc.)
• Visibility flags (hide_from_binary_help, hide_from_mode_help)

Values and Validation:

• Default value pointer
• Required flag (must user provide this option?)
• Environment variable fallback (e.g., PORT, PASSWORD_FILE)
• Custom validator function (validates across option fields)

Parsing and Actions:

• Custom parser for OPTION_TYPE_CALLBACK
• Action function for OPTION_TYPE_ACTION (executes immediately, may exit)

Mode Applicability:

• Bitmask indicating which modes this option applies to

Completion Metadata (Phase 3):

• Enum values and descriptions (for shell completions)
• Numeric range (min, max, step)
• Example values
• Input type hint (ENUM, NUMERIC, FILEPATH, CHOICE, etc.)

Mode Bitmask System

Each option includes a mode_bitmask that controls where it appears:

Mode Bitmask Values:

• OPTION_MODE_BINARY: Parsed before mode detection (–help, –version, –log-file, –log-level)
• OPTION_MODE_SERVER: Server-only options (–max-clients, –discovery-service, etc.)
• OPTION_MODE_CLIENT: Client-only options (–color, –audio, –snapshot, etc.)
• OPTION_MODE_MIRROR: Mirror mode options (local webcam preview)
• OPTION_MODE_DISCOVERY_SVC: Discovery service (ACDS) options
• OPTION_MODE_ALL: Available in all modes

Examples:

.mode_bitmask = OPTION_MODE_CLIENT | OPTION_MODE_MIRROR  // Client and mirror modes
.mode_bitmask = OPTION_MODE_SERVER                        // Server mode only
.mode_bitmask = OPTION_MODE_BINARY | OPTION_MODE_CLIENT   // Binary + client options
.mode_bitmask = OPTION_MODE_ALL                           // All modes

How Mode Filtering Works:

1. User runs ascii-chat client or ascii-chat server
2. Mode detection determines detected_mode (MODE_CLIENT, MODE_SERVER, etc.)
3. Registry functions filter options by matching mode_bitmask
4. Parser only accepts options for the detected mode
5. Help output only shows relevant options

Usage Patterns

Pattern 1: Get all options for a specific mode

size_t num_opts;
const option_descriptor_t *opts = options_registry_get_for_mode(MODE_CLIENT, &num_opts);
for (size_t i = 0; i < num_opts; i++) {
    printf(\"%s: %s\\n\", opts[i].long_name, opts[i].help_text);
}

Pattern 2: Look up individual options

const option_descriptor_t *port_opt = options_registry_find_by_name(\"port\");
if (port_opt && (port_opt->mode_bitmask & OPTION_MODE_SERVER)) {
    printf(\"Port option available in server mode\\n\");
}

Pattern 3: Populate builder with registry options

options_builder_t *builder = options_builder_create(sizeof(options_t));
options_registry_add_all_to_builder(builder);  // Add all registered options
options_config_t *config = options_builder_build(builder);

Pattern 4: Get shell completion metadata

const option_metadata_t *meta = options_registry_get_metadata(\"color-mode\");
if (meta && meta->input_type == OPTION_INPUT_ENUM) {
    size_t count;
    const char **values = options_registry_get_enum_values(\"color-mode\", NULL, &count);
    // Use values for shell completion suggestions
}

Adding New Options to Registry

To add a new option to the registry:

1. Add field to options_t struct in include/ascii-chat/options/options.h
2. Add default constant in options.h (e.g., OPT_MY_OPTION_DEFAULT)
3. Add registry entry in lib/options/registry.c with:
   • Long and short names
   • Type and storage offset (via offsetof)
   • Default value and validation function
   • Help text and group name
   • Mode bitmask(s) indicating which modes apply
   • Completion metadata (if enum, ranges, or examples needed)

Example Registry Entry:

{
    .long_name = \"max-clients\",
    .short_name = 'c',
    .type = OPTION_TYPE_INT,
    .offset = offsetof(options_t, max_clients),
    .default_value = &(int){OPT_MAX_CLIENTS_DEFAULT},
    .help_text = \"Maximum number of simultaneous clients\",
    .group = \"NETWORK OPTIONS\",
    .mode_bitmask = OPTION_MODE_SERVER,
    .validate = validate_max_clients,  // Custom validator
    .metadata = {
        .input_type = OPTION_INPUT_NUMERIC,
        .numeric_range = {.min = 1, .max = 100, .step = 1},
        .examples = (const char *[]){\"1\", \"4\", \"10\", NULL},
    }
}

Registry Lookup Functions

Core Functions:

• options_registry_add_all_to_builder(): Populate builder with all registry options
• options_registry_find_by_name(): Find option by long name (e.g., "port")
• options_registry_find_by_short(): Find option by short name (e.g., 'p')
• options_registry_get_for_mode(): Get all options for a specific mode
• options_registry_get_binary_options(): Get all binary-level options
• options_registry_get_for_display(): Get options filtered for help/completions display

Completion Metadata Functions (Phase 3):

• options_registry_get_metadata(): Get complete metadata for option
• options_registry_get_enum_values(): Get enum values and descriptions
• options_registry_get_numeric_range(): Get numeric min/max/step
• options_registry_get_examples(): Get example values
• options_registry_get_input_type(): Get input type hint

RCU Thread-Safety Integration

After registry options are parsed through the builder, they're published via RCU:

// Build config from registered options
options_builder_t *builder = options_builder_create(sizeof(options_t));
options_registry_add_all_to_builder(builder);
options_config_t *config = options_builder_build(builder);
 
// Parse command line
options_t opts = options_t_new();
options_config_parse(config, argc, argv, &opts, MODE_DETECTION_RESULT, ...);
 
// Publish to RCU (lock-free access from worker threads)
options_state_init();
options_state_set(&opts);
 
// Worker threads now read lock-free via GET_OPTION() macro

See also

builder.h - Builder API for constructing option configurations

rcu.h - Thread-safe RCU-based access to published Options Module

options.h - Unified Options Module parsing system (uses registry internally)

Author

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

Date

January 2026

Definition in file registry.h.

Function Documentation

options_registry_add_all_to_builder()

asciichat_error_t options_registry_add_all_to_builder

(

options_builder_t *

builder

)

Add all options from registry to builder.

Iterates through the central options registry and adds each option to the provided builder with its mode bitmask set.

Parameters

builder

Options builder to add options to

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 20 of file public_api.c.

                                                                                  {
  if (!builder) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Builder is NULL");
  }
 
  registry_init_size();
 
  for (size_t i = 0; i < g_registry_size; i++) {
    const registry_entry_t *entry = &g_options_registry[i];
    if (!entry->long_name) {
      continue;
    }
    // Silent - no debug logging needed
 
    switch (entry->type) {
    case OPTION_TYPE_STRING:
      options_builder_add_string(builder, entry->long_name, entry->short_name, entry->offset,
                                 entry->default_value ? (const char *)entry->default_value : "", entry->help_text,
                                 entry->group, entry->required, entry->env_var_name, entry->validate_fn);
      break;
    case OPTION_TYPE_INT:
      // Use metadata-aware function if metadata is present
      if (entry->metadata.numeric_range.max != 0 ||
          (entry->metadata.enum_values && entry->metadata.enum_values[0] != NULL)) {
        options_builder_add_int_with_metadata(builder, entry->long_name, entry->short_name, entry->offset,
                                              entry->default_value ? *(const int *)entry->default_value : 0,
                                              entry->help_text, entry->group, entry->required, entry->env_var_name,
                                              entry->validate_fn, &entry->metadata);
      } else {
        options_builder_add_int(builder, entry->long_name, entry->short_name, entry->offset,
                                entry->default_value ? *(const int *)entry->default_value : 0, entry->help_text,
                                entry->group, entry->required, entry->env_var_name, entry->validate_fn);
      }
      break;
    case OPTION_TYPE_BOOL:
      options_builder_add_bool(builder, entry->long_name, entry->short_name, entry->offset,
                               entry->default_value ? *(const bool *)entry->default_value : false, entry->help_text,
                               entry->group, entry->required, entry->env_var_name);
      break;
    case OPTION_TYPE_DOUBLE:
      // Use metadata-aware function if metadata is present (has numeric range)
      if (entry->metadata.numeric_range.max != 0) {
        options_builder_add_double_with_metadata(builder, entry->long_name, entry->short_name, entry->offset,
                                                 entry->default_value ? *(const double *)entry->default_value : 0.0,
                                                 entry->help_text, entry->group, entry->required, entry->env_var_name,
                                                 entry->validate_fn, &entry->metadata, entry->optional_arg);
      } else {
        options_builder_add_double(builder, entry->long_name, entry->short_name, entry->offset,
                                   entry->default_value ? *(const double *)entry->default_value : 0.0, entry->help_text,
                                   entry->group, entry->required, entry->env_var_name, entry->validate_fn,
                                   entry->optional_arg);
      }
      break;
    case OPTION_TYPE_CALLBACK:
      // Always use metadata-aware function to preserve enum/metadata information
      options_builder_add_callback_with_metadata(builder, entry->long_name, entry->short_name, entry->offset,
                                                 entry->default_value, entry->default_value_size, entry->parse_fn,
                                                 entry->help_text, entry->group, entry->required, entry->env_var_name,
                                                 entry->optional_arg, &entry->metadata);
      break;
    case OPTION_TYPE_ACTION:
      options_builder_add_action(builder, entry->long_name, entry->short_name,
                                 options_action_callback(entry->long_name, false), entry->help_text, entry->group);
      break;
    }
 
    if (entry->metadata.enum_values)
      options_builder_set_enum_values(builder, entry->long_name, entry->metadata.enum_values,
                                      entry->metadata.enum_descriptions);
    options_builder_set_input_type(builder, entry->long_name, entry->metadata.input_type);
 
    if (entry->type == OPTION_TYPE_STRING && entry->parse_fn)
      options_builder_set_string_parser(builder, entry->parse_fn);
 
    // Set mode bitmask on the last added descriptor
    options_builder_set_mode_bitmask(builder, entry->mode_bitmask);
 
    // Set custom arg_placeholder if defined
    if (entry->arg_placeholder) {
      options_builder_set_arg_placeholder(builder, entry->arg_placeholder);
    }
  }
 
  return ASCIICHAT_OK;
}

References registry_entry_t::arg_placeholder, ASCIICHAT_OK, registry_entry_t::default_value, registry_entry_t::default_value_size, option_metadata_t::enum_descriptions, option_metadata_t::enum_values, registry_entry_t::env_var_name, ERROR_INVALID_PARAM, g_options_registry, g_registry_size, registry_entry_t::group, registry_entry_t::help_text, option_metadata_t::input_type, registry_entry_t::long_name, option_metadata_t::max, registry_entry_t::metadata, registry_entry_t::mode_bitmask, option_metadata_t::numeric_range, registry_entry_t::offset, OPTION_TYPE_ACTION, OPTION_TYPE_BOOL, OPTION_TYPE_CALLBACK, OPTION_TYPE_DOUBLE, OPTION_TYPE_INT, OPTION_TYPE_STRING, registry_entry_t::optional_arg, options_action_callback(), options_builder_add_action(), options_builder_add_bool(), options_builder_add_callback_with_metadata(), options_builder_add_double(), options_builder_add_double_with_metadata(), options_builder_add_int(), options_builder_add_int_with_metadata(), options_builder_add_string(), options_builder_set_arg_placeholder(), options_builder_set_enum_values(), options_builder_set_input_type(), options_builder_set_mode_bitmask(), options_builder_set_string_parser(), registry_entry_t::parse_fn, registry_init_size(), registry_entry_t::required, SET_ERRNO, registry_entry_t::short_name, registry_entry_t::type, and registry_entry_t::validate_fn.

Referenced by options_preset_unified().

options_registry_find_by_name()

const option_descriptor_t * options_registry_find_by_name

(

const char *

long_name

)

Get option descriptor by name.

Looks up an option descriptor from the registry by its long name.

Parameters

long_name

Long option name (e.g., "port")

Returns

Pointer to option descriptor, or NULL if not found

Definition at line 129 of file public_api.c.

                                                                                {
  if (!long_name) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Long name is NULL");
    return NULL;
  }
 
  registry_init_size();
 
  const registry_entry_t *entry = registry_find_entry_by_name(long_name);
  if (!entry) {
    // Don't log error for binary-level options like "config" that aren't in registry
    if (strcmp(long_name, "config") != 0) {
      SET_ERRNO(ERROR_NOT_FOUND, "Option not found: %s", long_name);
    }
    return NULL;
  }
 
  static option_descriptor_t desc;
  desc = registry_entry_to_descriptor(entry);
  return &desc;
}

References ERROR_INVALID_PARAM, ERROR_NOT_FOUND, registry_entry_to_descriptor(), registry_find_entry_by_name(), registry_init_size(), and SET_ERRNO.

options_registry_find_by_short()

const option_descriptor_t * options_registry_find_by_short

(

char

short_name

)

Get option descriptor by short name.

Looks up an option descriptor from the registry by its short name.

Parameters

short_name

Short option character (e.g., 'p')

Returns

Pointer to option descriptor, or NULL if not found

Definition at line 151 of file public_api.c.

                                                                           {
  if (short_name == '\0') {
    SET_ERRNO(ERROR_INVALID_PARAM, "Short name is empty");
    return NULL;
  }
 
  registry_init_size();
 
  const registry_entry_t *entry = registry_find_entry_by_short(short_name);
  if (!entry) {
    SET_ERRNO(ERROR_NOT_FOUND, "Option not found: -%c", short_name);
    return NULL;
  }
 
  static option_descriptor_t desc;
  desc = registry_entry_to_descriptor(entry);
  return &desc;
}

References ERROR_INVALID_PARAM, ERROR_NOT_FOUND, registry_entry_to_descriptor(), registry_find_entry_by_short(), registry_init_size(), and SET_ERRNO.

options_registry_get_binary_options()

const option_descriptor_t * options_registry_get_binary_options

(

size_t *

num_options

)

Get all binary-level options.

Returns an array of all binary-level options (those with OPTION_MODE_BINARY). The array is allocated and must be freed by the caller.

Parameters

num_options

OUTPUT: Number of options returned

Returns

Array of option descriptors (caller must free), or NULL on error

Definition at line 238 of file public_api.c.

                                                                                    {
  if (!num_options) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Number of options is NULL");
    return NULL;
  }
 
  registry_init_size();
 
  /* Count binary-level options */
  size_t count = 0;
  for (size_t i = 0; i < g_registry_size; i++) {
    if (g_options_registry[i].mode_bitmask & OPTION_MODE_BINARY) {
      count++;
    }
  }
 
  if (count == 0) {
    *num_options = 0;
    return NULL;
  }
 
  /* Allocate array for binary options */
  option_descriptor_t *binary_opts = SAFE_MALLOC(count * sizeof(option_descriptor_t), option_descriptor_t *);
  if (!binary_opts) {
    SET_ERRNO(ERROR_INVALID_STATE, "Failed to allocate binary options array");
    *num_options = 0;
    return NULL;
  }
 
  /* Copy binary options */
  size_t idx = 0;
  for (size_t i = 0; i < g_registry_size; i++) {
    if (g_options_registry[i].mode_bitmask & OPTION_MODE_BINARY) {
      binary_opts[idx++] = registry_entry_to_descriptor(&g_options_registry[i]);
    }
  }
 
  *num_options = count;
  return binary_opts;
}

References ERROR_INVALID_PARAM, ERROR_INVALID_STATE, g_options_registry, g_registry_size, OPTION_MODE_BINARY, registry_entry_to_descriptor(), registry_init_size(), SAFE_MALLOC, and SET_ERRNO.

options_registry_get_enum_values()

const char ** options_registry_get_enum_values	(	const char *	option_name,
		const char ***	descriptions,
		size_t *	count )

Get enum values for an option.

Retrieves enum values and descriptions for an option that has OPTION_INPUT_ENUM type in its metadata.

Parameters

option_name	Long name of option
descriptions	OUTPUT: Pointer to descriptions array (or NULL if not needed)
count	OUTPUT: Number of values/descriptions

Returns

Array of enum value strings, or NULL if not found or not an enum type

Example:

const char **values;
const char **descs;
size_t count;
values = options_registry_get_enum_values("color-mode", &descs, &count);
if (values) {
    for (size_t i = 0; i < count; i++) {
        printf("%s: %s\n", values[i], descs[i]);
    }
}

Definition at line 346 of file public_api.c.

                                                                                                                  {
  if (!option_name || !count) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Option name is NULL or count is NULL");
    if (count)
      *count = 0;
    return NULL;
  }
 
  const option_metadata_t *meta = options_registry_get_metadata(option_name);
  if (!meta || meta->input_type != OPTION_INPUT_ENUM || !meta->enum_values || meta->enum_values[0] == NULL) {
    SET_ERRNO(ERROR_NOT_FOUND, "Option '%s' not found", option_name);
    *count = 0;
    if (descriptions)
      *descriptions = NULL;
    return NULL;
  }
 
  // Count enum values (NULL-terminated array)
  size_t enum_count = 0;
  while (meta->enum_values[enum_count] != NULL) {
    enum_count++;
  }
 
  *count = enum_count;
  if (descriptions) {
    *descriptions = meta->enum_descriptions;
  }
  return meta->enum_values;
}

References option_metadata_t::enum_descriptions, option_metadata_t::enum_values, ERROR_INVALID_PARAM, ERROR_NOT_FOUND, option_metadata_t::input_type, OPTION_INPUT_ENUM, options_registry_get_metadata(), and SET_ERRNO.

Referenced by asciichat_suggest_enum_value(), options_get_enum_values(), and options_is_enum_option().

options_registry_get_examples()

const char ** options_registry_get_examples	(	const char *	option_name,
		size_t *	count )

Get example values for an option.

Retrieves example values or command invocations for an option.

Parameters

option_name	Long name of option
count	OUTPUT: Number of examples

Returns

Array of example strings, or NULL if no examples defined

Definition at line 396 of file public_api.c.

                                                                                   {
  if (!option_name || !count) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Option name is NULL or count is NULL");
    if (count)
      *count = 0;
    return NULL;
  }
 
  const option_metadata_t *meta = options_registry_get_metadata(option_name);
  if (!meta || !meta->examples || meta->examples[0] == NULL) {
    *count = 0;
    return NULL;
  }
 
  // Count examples by finding NULL terminator
  size_t example_count = 0;
  for (size_t i = 0; meta->examples[i] != NULL; i++) {
    example_count++;
  }
 
  *count = example_count;
  return meta->examples;
}

References ERROR_INVALID_PARAM, option_metadata_t::examples, options_registry_get_metadata(), and SET_ERRNO.

options_registry_get_for_display()

const option_descriptor_t * options_registry_get_for_display	(	asciichat_mode_t	mode,
		bool	for_binary_help,
		size_t *	num_options )

Get options for help/completions display with unified filtering.

Returns options filtered using the same logic as the help system. This ensures help output and completions are always in sync.

Uses the same filtering rules as options_print_help_for_mode():

• For binary-level help (mode == MODE_DISCOVERY): shows all options that apply to any mode
• For mode-specific help: shows only options for that mode (binary options excluded unless also mode-specific)
• Respects hide_from_binary_help and hide_from_mode_help flags

Parameters

mode	Mode to filter for (use MODE_DISCOVERY for binary-level help)
for_binary_help	If true, use binary-help filtering; if false, use mode-specific filtering
num_options	OUTPUT: Number of options returned

Returns

Array of option descriptors (caller must free), or NULL on error

Note

This is the AUTHORITATIVE filtering function for both help and completions. Always use this function to ensure consistency across the application.

Definition at line 279 of file public_api.c.

                                                                                 {
  if (!num_options) {
    SET_ERRNO(ERROR_INVALID_PARAM, "num_options is NULL");
    return NULL;
  }
 
  registry_init_size();
 
  // Count matching options
  size_t count = 0;
  for (size_t i = 0; i < g_registry_size; i++) {
    if (registry_entry_applies_to_mode(&g_options_registry[i], mode, for_binary_help)) {
      count++;
    }
  }
 
  if (count == 0) {
    *num_options = 0;
    return NULL;
  }
 
  // Allocate array
  option_descriptor_t *descriptors = SAFE_MALLOC(count * sizeof(option_descriptor_t), option_descriptor_t *);
  if (!descriptors) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate descriptors array");
    *num_options = 0;
    return NULL;
  }
 
  // Copy matching options
  size_t idx = 0;
  for (size_t i = 0; i < g_registry_size; i++) {
    if (registry_entry_applies_to_mode(&g_options_registry[i], mode, for_binary_help)) {
      descriptors[idx++] = registry_entry_to_descriptor(&g_options_registry[i]);
    }
  }
 
  *num_options = count;
  return descriptors;
}

References ERROR_INVALID_PARAM, ERROR_MEMORY, g_options_registry, g_registry_size, registry_entry_applies_to_mode(), registry_entry_to_descriptor(), registry_init_size(), SAFE_MALLOC, and SET_ERRNO.

Referenced by completions_generate_fish(), completions_generate_powershell(), and completions_generate_zsh().

options_registry_get_for_mode()

const option_descriptor_t * options_registry_get_for_mode	(	asciichat_mode_t	mode,
		size_t *	num_options )

Get all options for a specific mode.

Returns an array of option descriptors that apply to the given mode. The array is allocated and must be freed by the caller.

Parameters

mode	Mode to filter by
num_options	OUTPUT: Number of options returned

Returns

Array of option descriptors (caller must free), or NULL on error

Definition at line 170 of file public_api.c.

                                                                                                     {
  if (!num_options) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Number of options is NULL");
    return NULL;
  }
 
  registry_init_size();
 
  /* Convert mode to bitmask */
  option_mode_bitmask_t mode_bitmask = 0;
  switch (mode) {
  case MODE_SERVER:
    mode_bitmask = OPTION_MODE_SERVER;
    break;
  case MODE_CLIENT:
    mode_bitmask = OPTION_MODE_CLIENT;
    break;
  case MODE_MIRROR:
    mode_bitmask = OPTION_MODE_MIRROR;
    break;
  case MODE_DISCOVERY_SERVICE:
    mode_bitmask = OPTION_MODE_DISCOVERY_SVC;
    break;
  case MODE_DISCOVERY:
    mode_bitmask = OPTION_MODE_DISCOVERY;
    break;
  case MODE_MCP_SERVER:
    mode_bitmask = OPTION_MODE_MCP_SERVER;
    break;
  default:
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid mode: %d", mode);
    *num_options = 0;
    return NULL;
  }
 
  /* Count matching options */
  size_t count = 0;
  for (size_t i = 0; i < g_registry_size; i++) {
    if (g_options_registry[i].mode_bitmask & mode_bitmask) {
      count++;
    }
  }
 
  if (count == 0) {
    *num_options = 0;
    return NULL;
  }
 
  /* Allocate array for matching options */
  option_descriptor_t *filtered = SAFE_MALLOC(count * sizeof(option_descriptor_t), option_descriptor_t *);
  if (!filtered) {
    SET_ERRNO(ERROR_INVALID_STATE, "Failed to allocate filtered options array");
    *num_options = 0;
    return NULL;
  }
 
  /* Copy matching options */
  size_t idx = 0;
  for (size_t i = 0; i < g_registry_size; i++) {
    if (g_options_registry[i].mode_bitmask & mode_bitmask) {
      filtered[idx++] = registry_entry_to_descriptor(&g_options_registry[i]);
    }
  }
 
  *num_options = count;
  return filtered;
}

References ERROR_INVALID_PARAM, ERROR_INVALID_STATE, g_options_registry, g_registry_size, MODE_CLIENT, MODE_DISCOVERY, MODE_DISCOVERY_SERVICE, MODE_MCP_SERVER, MODE_MIRROR, MODE_SERVER, OPTION_MODE_CLIENT, OPTION_MODE_DISCOVERY, OPTION_MODE_DISCOVERY_SVC, OPTION_MODE_MCP_SERVER, OPTION_MODE_MIRROR, OPTION_MODE_SERVER, registry_entry_to_descriptor(), registry_init_size(), SAFE_MALLOC, and SET_ERRNO.

Referenced by completions_collect_all_modes_unique().

options_registry_get_input_type()

option_input_type_t options_registry_get_input_type

(

const char *

option_name

)

Get input type for an option.

Retrieves the input type (OPTION_INPUT_ENUM, OPTION_INPUT_NUMERIC, etc.) for the given option.

Parameters

option_name

Long name of option

Returns

Input type (OPTION_INPUT_NONE if not found)

Definition at line 420 of file public_api.c.

                                                                             {
  if (!option_name) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Option name is NULL");
    return OPTION_INPUT_NONE;
  }
 
  const option_metadata_t *meta = options_registry_get_metadata(option_name);
  if (!meta) {
    SET_ERRNO(ERROR_NOT_FOUND, "Option '%s' not found", option_name);
    return OPTION_INPUT_NONE;
  }
 
  return meta->input_type;
}

References ERROR_INVALID_PARAM, ERROR_NOT_FOUND, option_metadata_t::input_type, OPTION_INPUT_NONE, options_registry_get_metadata(), and SET_ERRNO.

options_registry_get_metadata()

const option_metadata_t * options_registry_get_metadata

(

const char *

long_name

)

Get complete metadata for an option.

Retrieves all completion metadata for the given option, including enum values, numeric ranges, examples, input type, etc.

Parameters

long_name

Long name of option to look up

Returns

Pointer to metadata structure, or NULL if option not found

Note

The returned pointer points to data within the registry and should not be modified or freed.

Definition at line 325 of file public_api.c.

                                                                              {
  if (!long_name) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Long name is NULL");
    return NULL;
  }
 
  // Look up option in registry and return its metadata
  registry_init_size();
  for (size_t i = 0; i < g_registry_size; i++) {
    const registry_entry_t *entry = &g_options_registry[i];
    if (entry->long_name && strcmp(entry->long_name, long_name) == 0) {
      // Return the metadata from the registry entry
      return &entry->metadata;
    }
  }
 
  // If not found, return empty metadata
  static option_metadata_t empty_metadata = {0};
  return &empty_metadata;
}

References ERROR_INVALID_PARAM, g_options_registry, g_registry_size, registry_entry_t::long_name, registry_entry_t::metadata, registry_init_size(), and SET_ERRNO.

Referenced by options_get_enum_entries(), options_registry_get_enum_values(), options_registry_get_examples(), options_registry_get_input_type(), and options_registry_get_numeric_range().

options_registry_get_numeric_range()

bool options_registry_get_numeric_range	(	const char *	option_name,
		int *	min_out,
		int *	max_out,
		int *	step_out )

Get numeric range for an option.

Retrieves min/max/step values for an option that has OPTION_INPUT_NUMERIC type in its metadata.

Parameters

option_name	Long name of option
min_out	OUTPUT: Minimum value (or 0 if no limit)
max_out	OUTPUT: Maximum value (or 0 if no limit)
step_out	OUTPUT: Step size (or 0 if continuous)

Returns

true if option found and has numeric range, false otherwise

Example:

int min, max, step;
if (options_registry_get_numeric_range("compression-level", &min, &max, &step)) {
    printf("Range: %d-%d (step: %d)\n", min, max, step);
}

Definition at line 376 of file public_api.c.

                                                                                                            {
  if (!option_name || !min_out || !max_out || !step_out) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Option name is NULL or min_out, max_out, or step_out is NULL");
    return false;
  }
 
  const option_metadata_t *meta = options_registry_get_metadata(option_name);
  if (!meta || meta->input_type != OPTION_INPUT_NUMERIC) {
    *min_out = 0;
    *max_out = 0;
    *step_out = 0;
    return false;
  }
 
  *min_out = meta->numeric_range.min;
  *max_out = meta->numeric_range.max;
  *step_out = meta->numeric_range.step;
  return true;
}

References ERROR_INVALID_PARAM, option_metadata_t::input_type, option_metadata_t::max, option_metadata_t::min, option_metadata_t::numeric_range, OPTION_INPUT_NUMERIC, options_registry_get_metadata(), SET_ERRNO, and option_metadata_t::step.