schema.h File Reference

Schema metadata for config file options. More...

Go to the source code of this file.

Data Structures
struct	config_option_metadata_t
	Option metadata for config file parsing. More...

Typedefs
typedef bool(*	builder_validate_fn_t) (const void *options_struct)
	Validation function from options builder.

Enumerations
enum	option_context_t { OPTION_CONTEXT_CLI , OPTION_CONTEXT_CONFIG , OPTION_CONTEXT_BOTH }
	Context where an option can appear. More...

Functions
const config_option_metadata_t *	config_schema_get_by_toml_key (const char *toml_key)
	Get option metadata by TOML key.
const config_option_metadata_t **	config_schema_get_by_category (const char *category, size_t *count)
	Get all option metadata for a category.
const config_option_metadata_t *	config_schema_get_all (size_t *count)
	Get all option metadata.
asciichat_error_t	config_schema_build_from_configs (const options_config_t **configs, size_t num_configs)
	Build schema dynamically from options builder configs.
void	config_schema_destroy (void)
	Clean up dynamically allocated schema resources.

Detailed Description

Schema metadata for config file options.

This module provides declarative metadata for all configurable options that can appear in TOML configuration files. The schema drives the generic config parser, eliminating duplicate validation code.

Note

This is separate from builder.h's option_descriptor_t which is for CLI parsing. This schema is specifically for TOML config files.

Definition in file schema.h.

Typedef Documentation

builder_validate_fn_t

typedef bool(* builder_validate_fn_t) (const void *options_struct)

Validation function from options builder.

This is the same validation function signature used by the options builder. It receives the full options struct and can perform cross-field validation.

Parameters

options_struct

Full options struct (cast to void* for generic use)

Returns

true if valid, false after setting error context with SET_ERRNO() if invalid

Definition at line 40 of file schema.h.

Enumeration Type Documentation

option_context_t

enum option_context_t

Context where an option can appear.

Enumerator
OPTION_CONTEXT_CLI	CLI-only option (cannot appear in config).
OPTION_CONTEXT_CONFIG	Config-only option (never on CLI).
OPTION_CONTEXT_BOTH	Can appear in both CLI and config.

Definition at line 25 of file schema.h.

             {
  OPTION_CONTEXT_CLI,    
  OPTION_CONTEXT_CONFIG, 
  OPTION_CONTEXT_BOTH,   
} option_context_t;

Function Documentation

config_schema_build_from_configs()

asciichat_error_t config_schema_build_from_configs	(	const options_config_t **	configs,
		size_t	num_configs )

Build schema dynamically from options builder configs.

This function builds the config schema by merging all mode configs (server, client, mirror, etc.). It generates TOML keys, CLI flags, categories, and types from the builder's option descriptors.

Parameters

configs	Array of option configs (can contain NULL entries)
num_configs	Number of configs in the array

Returns

ASCIICHAT_OK on success, error code on failure

Note

This should be called once during initialization before any config parsing

Definition at line 252 of file schema.c.

                                                                                                         {
  // Free existing dynamic schema if any
  if (g_dynamic_schema) {
    SAFE_FREE(g_dynamic_schema);
    g_dynamic_schema = NULL;
    g_dynamic_schema_count = 0;
  }
 
  // Free existing string storage
  if (g_dynamic_strings) {
    for (size_t i = 0; i < g_dynamic_strings_count; i++) {
      SAFE_FREE(g_dynamic_strings[i]);
    }
    SAFE_FREE(g_dynamic_strings);
    g_dynamic_strings = NULL;
    g_dynamic_strings_count = 0;
    g_dynamic_strings_capacity = 0;
  }
 
  // Count total unique descriptors (by offset) across all configs
  // Use a simple approach: collect all descriptors, then deduplicate by offset
  const option_descriptor_t *all_descriptors[SCHEMA_OPTION_CAPACITY] = {0}; // Max expected options
  size_t descriptor_count = 0;
 
  // Collect descriptors from all configs
  for (size_t cfg_idx = 0; cfg_idx < num_configs; cfg_idx++) {
    const options_config_t *config = configs[cfg_idx];
    if (!config) {
      log_debug("Config %zu is NULL, skipping", cfg_idx);
      continue;
    }
 
    if (!config->descriptors || config->num_descriptors == 0) {
      log_debug("Config %zu has no descriptors", cfg_idx);
      continue;
    }
 
    for (size_t i = 0; i < config->num_descriptors && descriptor_count < SCHEMA_OPTION_CAPACITY; i++) {
      const option_descriptor_t *desc = &config->descriptors[i];
      if (!desc) {
        log_warn("Descriptor at index %zu in config %zu is NULL", i, cfg_idx);
        continue;
      }
      if (should_add_descriptor(desc, all_descriptors, descriptor_count)) {
        all_descriptors[descriptor_count++] = desc;
      }
    }
  }
 
  // Allocate schema array
  g_dynamic_schema = SAFE_MALLOC(descriptor_count * sizeof(config_option_metadata_t), config_option_metadata_t *);
  if (!g_dynamic_schema) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate dynamic schema");
  }
 
  // Build schema entries
  g_dynamic_schema_count = 0;
  char toml_key_buffer[BUFFER_SIZE_SMALL];
  char cli_flag_buffer[OPTIONS_CONFIG_SCHEMA_CLI_FLAG_BUFFER_SIZE];
  char category_buffer[OPTIONS_CONFIG_SCHEMA_CATEGORY_BUFFER_SIZE];
 
  for (size_t i = 0; i < descriptor_count; i++) {
    const option_descriptor_t *desc = all_descriptors[i];
    if (!desc || !desc->long_name || !desc->group) {
      continue;
    }
 
    config_option_metadata_t *meta = &g_dynamic_schema[g_dynamic_schema_count++];
    // Zero-initialize the metadata struct to ensure all fields are initialized
    memset(meta, 0, sizeof(*meta));
 
    // Use builder's type directly
    meta->type = desc->type;
 
    // Generate category: lowercase the group name from builder
    SAFE_STRNCPY(category_buffer, desc->group, sizeof(category_buffer) - 1);
    category_buffer[sizeof(category_buffer) - 1] = '\0';
    str_tolower(category_buffer);
 
    // Generate TOML key: "category.field_name" (category is lowercase group, field_name is long_name with
    // dashes->underscores)
    const char *field_name = desc->long_name;
    if (strcmp(category_buffer, "otel") == 0 && strncmp(field_name, "otel-", 5) == 0)
      field_name += 5;
    if (!generate_toml_key(category_buffer, field_name, toml_key_buffer, sizeof(toml_key_buffer))) {
      g_dynamic_schema_count--; // Skip this entry
      continue;
    }
 
    // Store generated strings (allocate and store)
    meta->toml_key = store_dynamic_string(toml_key_buffer);
    meta->category = store_dynamic_string(category_buffer);
    if (!meta->toml_key || !meta->category) {
      // Failed to allocate strings, skip this entry
      g_dynamic_schema_count--;
      continue;
    }
 
    // Generate CLI flag: "--long-name"
    if (generate_cli_flag(desc->long_name, cli_flag_buffer, sizeof(cli_flag_buffer))) {
      meta->cli_flag = store_dynamic_string(cli_flag_buffer);
      if (!meta->cli_flag) {
        // Failed to allocate, but continue (cli_flag can be NULL)
      }
    } else {
      meta->cli_flag = NULL;
    }
 
    // Set other fields
    meta->context = OPTION_CONTEXT_BOTH; // Most options can appear in both CLI and config
    meta->field_offset = desc->offset;
    meta->field_size = get_field_size(meta->type, desc->offset);
    // Use builder's validate function directly - it receives the full options struct
    meta->validate_fn = desc->validate;
    // Use builder's parse function for CALLBACK types
    meta->parse_fn = desc->parse_fn;
    meta->description = desc->help_text;
 
    // Set mode_bitmask from option descriptor
    // The descriptor should have mode_bitmask set from the registry
    meta->mode_bitmask = desc->mode_bitmask;
 
    // Copy mode_default_getter function pointer
    meta->mode_default_getter = desc->mode_default_getter;
 
    // Copy constraints from descriptor's metadata
    // For integer types, copy numeric_range to int_range (always copy, even if min is 0)
    memset(&meta->constraints, 0, sizeof(meta->constraints));
    // Always copy numeric_range if descriptor has it (check max or min)
    if (desc && desc->metadata.numeric_range.max > 0) {
      meta->constraints.int_range.min = desc->metadata.numeric_range.min;
      meta->constraints.int_range.max = desc->metadata.numeric_range.max;
    }
  }
 
  g_schema_built = true;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, BUFFER_SIZE_SMALL, config_option_metadata_t::category, config_option_metadata_t::cli_flag, config_option_metadata_t::constraints, config_option_metadata_t::context, config_option_metadata_t::description, options_config_t::descriptors, ERROR_MEMORY, config_option_metadata_t::field_offset, config_option_metadata_t::field_size, option_descriptor_t::group, option_descriptor_t::help_text, config_option_metadata_t::int_range, log_debug, log_warn, option_descriptor_t::long_name, config_option_metadata_t::max, option_metadata_t::max, option_descriptor_t::metadata, config_option_metadata_t::min, option_metadata_t::min, config_option_metadata_t::mode_bitmask, option_descriptor_t::mode_bitmask, config_option_metadata_t::mode_default_getter, option_descriptor_t::mode_default_getter, options_config_t::num_descriptors, option_metadata_t::numeric_range, option_descriptor_t::offset, OPTION_CONTEXT_BOTH, OPTIONS_CONFIG_SCHEMA_CATEGORY_BUFFER_SIZE, OPTIONS_CONFIG_SCHEMA_CLI_FLAG_BUFFER_SIZE, config_option_metadata_t::parse_fn, option_descriptor_t::parse_fn, SAFE_FREE, SAFE_MALLOC, SAFE_STRNCPY, SCHEMA_OPTION_CAPACITY, SET_ERRNO, config_option_metadata_t::toml_key, config_option_metadata_t::type, option_descriptor_t::type, option_descriptor_t::validate, and config_option_metadata_t::validate_fn.

Referenced by action_create_config(), and config_create_default().

config_schema_destroy()

void config_schema_destroy

(

void

)

Clean up dynamically allocated schema resources.

Frees all memory allocated by config_schema_build_from_configs(), including the dynamic schema array and all associated strings. Safe to call multiple times or if schema was never built.

Note

This should be called during shutdown to prevent memory leaks

Definition at line 469 of file schema.c.

                                 {
  if (!g_schema_built) {
    return; // Nothing to clean up
  }
 
  // Free all dynamically allocated strings (toml_key, cli_flag, category)
  if (g_dynamic_strings) {
    for (size_t i = 0; i < g_dynamic_strings_count; i++) {
      SAFE_FREE(g_dynamic_strings[i]);
    }
    SAFE_FREE(g_dynamic_strings);
    g_dynamic_strings = NULL;
    g_dynamic_strings_count = 0;
    g_dynamic_strings_capacity = 0;
  }
 
  // Free the schema array itself
  if (g_dynamic_schema) {
    SAFE_FREE(g_dynamic_schema);
    g_dynamic_schema = NULL;
    g_dynamic_schema_count = 0;
  }
 
  g_schema_built = false;
}

References SAFE_FREE.

Referenced by options_cleanup_schema(), and options_state_destroy().

config_schema_get_all()

const config_option_metadata_t * config_schema_get_all

(

size_t *

count

)

Get all option metadata.

Parameters

count

Output: total number of options

Returns

Array of all metadata (NULL-terminated)

Definition at line 449 of file schema.c.

                                                                     {
  // Schema must be built before use
  if (!g_schema_built || !g_dynamic_schema) {
    if (count) {
      *count = 0;
    }
    SET_ERRNO(ERROR_INVALID_STATE, "Schema not built");
    return NULL;
  }
 
  if (count) {
    *count = g_dynamic_schema_count;
  }
  return g_dynamic_schema;
}

References ERROR_INVALID_STATE, and SET_ERRNO.

Referenced by config_create_default().

config_schema_get_by_category()

const config_option_metadata_t ** config_schema_get_by_category	(	const char *	category,
		size_t *	count )

Get all option metadata for a category.

Parameters

category	Category name (e.g., "network")
count	Output: number of options in category

Returns

Array of metadata pointers (NULL-terminated)

Definition at line 416 of file schema.c.

                                                                                                    {
  static const config_option_metadata_t *results[SCHEMA_CATEGORY_OPTION_CAPACITY]; // Max options per category
  size_t result_count = 0;
 
  if (!category) {
    if (count) {
      *count = 0;
    }
    return NULL;
  }
 
  // Schema must be built before use
  if (!g_schema_built || !g_dynamic_schema) {
    if (count) {
      *count = 0;
    }
    SET_ERRNO(ERROR_INVALID_STATE, "Schema not built");
    return NULL;
  }
 
  for (size_t i = 0; i < g_dynamic_schema_count && result_count < SCHEMA_CATEGORY_OPTION_CAPACITY; i++) {
    if (g_dynamic_schema[i].category && strcmp(g_dynamic_schema[i].category, category) == 0) {
      results[result_count++] = &g_dynamic_schema[i];
    }
  }
 
  if (count) {
    *count = result_count;
  }
 
  return (result_count > 0) ? results : NULL;
}

References ERROR_INVALID_STATE, SCHEMA_CATEGORY_OPTION_CAPACITY, and SET_ERRNO.

Referenced by config_create_default().

config_schema_get_by_toml_key()

const config_option_metadata_t * config_schema_get_by_toml_key

(

const char *

toml_key

)

Get option metadata by TOML key.

Parameters

toml_key

TOML key path (e.g., "network.port")

Returns

Pointer to metadata or NULL if not found

Definition at line 395 of file schema.c.

                                                                                    {
  if (!toml_key) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid arguments");
    return NULL;
  }
 
  // Schema must be built before use
  if (!g_schema_built || !g_dynamic_schema) {
    SET_ERRNO(ERROR_INVALID_STATE, "Schema not built");
    return NULL;
  }
 
  for (size_t i = 0; i < g_dynamic_schema_count; i++) {
    if (g_dynamic_schema[i].toml_key && strcmp(g_dynamic_schema[i].toml_key, toml_key) == 0) {
      return &g_dynamic_schema[i];
    }
  }
 
  return NULL;
}

References ERROR_INVALID_PARAM, ERROR_INVALID_STATE, and SET_ERRNO.