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

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:

User runs ascii-chat client or ascii-chat server
Mode detection determines detected_mode (MODE_CLIENT, MODE_SERVER, etc.)
Registry functions filter options by matching mode_bitmask
Parser only accepts options for the detected mode
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:

Add field to options_t struct in include/ascii-chat/options/options.h
Add default constant in options.h (e.g., OPT_MY_OPTION_DEFAULT)
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:
      // Actions are now registered as options with help text
      // Look up the corresponding action function based on option name
      if (strcmp(entry->long_name, "list-webcams") == 0) {
        options_builder_add_action(builder, entry->long_name, entry->short_name, action_list_webcams, entry->help_text,
                                   entry->group);
      } else if (strcmp(entry->long_name, "list-microphones") == 0) {
        options_builder_add_action(builder, entry->long_name, entry->short_name, action_list_microphones,
                                   entry->help_text, entry->group);
      } else if (strcmp(entry->long_name, "list-speakers") == 0) {
        options_builder_add_action(builder, entry->long_name, entry->short_name, action_list_speakers, entry->help_text,
                                   entry->group);
      } else if (strcmp(entry->long_name, "show-capabilities") == 0) {
        options_builder_add_action(builder, entry->long_name, entry->short_name, action_show_capabilities,
                                   entry->help_text, entry->group);
      } else if (strcmp(entry->long_name, "check-update") == 0) {
        options_builder_add_action(builder, entry->long_name, entry->short_name, action_check_update, entry->help_text,
                                   entry->group);
      } else if (strcmp(entry->long_name, "help") == 0 || strcmp(entry->long_name, "version") == 0) {
        // Help and version are handled specially in options.c, just add them for help display
        // They don't have actual action functions - pass a dummy one
        options_builder_add_action(builder, entry->long_name, entry->short_name, NULL, entry->help_text, entry->group);
      }
      break;
    }
 
    // 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;
}

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 141 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;
  }
 
  /* Create descriptor from registry entry */
  static option_descriptor_t desc;
  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.hide_from_mode_help = false;
  desc.hide_from_binary_help = false;
  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;
 
  return &desc;
}

◆ 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 181 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;
  }
 
  /* Create descriptor from registry entry */
  static option_descriptor_t desc;
  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.hide_from_mode_help = false;
  desc.hide_from_binary_help = false;
  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;
 
  return &desc;
}

◆ 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 283 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 391 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.

◆ 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 441 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 324 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 218 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;
  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_MIRROR, MODE_SERVER, OPTION_MODE_CLIENT, OPTION_MODE_DISCOVERY, OPTION_MODE_DISCOVERY_SVC, 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 465 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 370 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_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 421 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.