common.h File Reference

Common utilities and helpers for option parsing across all modes. More...

Go to the source code of this file.

Macros
#define	OPTIONS_COMMON_H

Functions
const char *	find_similar_option (const char *unknown_opt, const struct option *options)
	Find a similar option name for typo suggestions.
const char *	format_available_modes (option_mode_bitmask_t mode_bitmask)
	Format all available modes for an option as comma-separated list.
int	strtoint_safe (const char *str)
	Safely parse string to integer with validation.
char *	validate_required_argument (const char *optarg, char *argbuf, size_t argbuf_size, const char *option_name, asciichat_mode_t mode)
	Validate and retrieve required argument for an option.
bool	validate_positive_int_opt (const char *value_str, int *out_value, const char *param_name)
	Validate a positive integer value.
bool	validate_port_opt (const char *value_str, uint16_t *out_port)
	Validate port number (1-65535).
bool	validate_fps_opt (const char *value_str, int *out_fps)
	Validate FPS value (0 for auto, otherwise 1-144).
bool	validate_webcam_index (const char *value_str, unsigned short int *out_index)
	Validate webcam index using the common device index validator.
asciichat_error_t	validate_options_and_report (const void *config, const void *opts)
	Validate options and report errors to stderr.
asciichat_error_t	detect_default_ssh_key (char *key_path, size_t path_size)
	Detect default SSH key path for the current user.
char *	strip_equals_prefix (const char *opt_value, char *buffer, size_t buffer_size)
	Strip equals sign prefix from option argument.
char *	get_required_argument (const char *opt_value, char *buffer, size_t buffer_size, const char *option_name, asciichat_mode_t mode)
	Handle required arguments with consistent error messages.
char *	read_password_from_stdin (const char *prompt)
	Read password from stdin with prompt.
asciichat_error_t	parse_color_mode_option (const char *value_str, options_t *opts)
	Parse –color-mode option and set opts->color_mode.
asciichat_error_t	parse_render_mode_option (const char *value_str, options_t *opts)
	Parse –render-mode option and set opts->render_mode.
asciichat_error_t	parse_palette_option (const char *value_str, options_t *opts)
	Parse –palette option and set opt_palette_type.
asciichat_error_t	parse_palette_chars_option (const char *value_str, options_t *opts)
	Parse –palette-chars option and set opt_palette_custom.
asciichat_error_t	parse_width_option (const char *value_str, options_t *opts)
	Parse –width option and set opts->width.
asciichat_error_t	parse_height_option (const char *value_str, options_t *opts)
	Parse –height option and set opts->height.
asciichat_error_t	parse_webcam_index_option (const char *value_str, options_t *opts)
	Parse –webcam-index option and set opts->webcam_index.
asciichat_error_t	parse_snapshot_delay_option (const char *value_str, options_t *opts)
	Parse –snapshot-delay option and set opts->snapshot_delay.
asciichat_error_t	parse_log_level_option (const char *value_str, options_t *opts)
	Parse –log-level option and set opt_log_level.
void	update_dimensions_for_full_height (options_t *opts)
	Update dimensions for full-height mode.
void	update_dimensions_to_terminal_size (options_t *opts)
	Update dimensions to current terminal size.
void	print_project_links (FILE *desc)
	Print project links with link emoji and colored styling.

Detailed Description

Common utilities and helpers for option parsing across all modes.

This module provides shared utilities used by the entire options system:

• Validators for numeric ranges, file existence, formats (IP, port, etc.)
• String parsing helpers (safe integer conversion, color mode parsing, etc.)
• Terminal dimension management functions
• Option lookup and typo suggestion (Levenshtein distance)
• SSH key detection and defaults

Design Philosophy:

• Single Responsibility: Each validator handles one specific type of validation
• Consistent Error Reporting: All validators provide helpful error messages
• No Side Effects: Validators are pure functions (no global state modification)
• Reusability: These functions are used by registry, builder, and parsers modules
• Cross-Cutting Concerns: Handles validation needs for all modes uniformly

Validator Functions:

Return conventions:

• Numeric validators: Return parsed value on success, INT_MIN/-1 on error
• Boolean validators: Return true/false with error message on failure
• String validators: Validate format, write to output buffer

Typical Usage:

// Validate port number
uint16_t port;
if (!validate_port_opt("8080", &port)) {
    fprintf(stderr, "Invalid port: 8080\\n");
    return false;
}
 
// Parse color mode from string
asciichat_error_t err = parse_color_mode_option("256", opts);
if (err != ASCIICHAT_OK) {
    fprintf(stderr, "Unknown color mode\\n");
    return false;
}
 
// Find similar option if user misspelled
const char *suggestion = find_similar_option("prot", all_options);
if (suggestion) {
    fprintf(stderr, "Did you mean: --%s?\\n", suggestion);
}

Option Parsing Helpers:

• strtoint_safe(): Safe integer parsing with range checking
• find_similar_option(): Typo detection using Levenshtein distance
• validate_positive_int_opt(): Validate positive integers
• validate_port_opt(): Validate port numbers (1-65535)
• validate_fps_opt(): Validate frame rates
• validate_webcam_index(): Validate webcam device indices

Display Option Parsers:

• parse_color_mode_option(): Parse color mode strings (auto, mono, 16, 256, truecolor)
• parse_render_mode_option(): Parse render mode (foreground, background, half-block)
• parse_palette_option(): Parse palette type selection
• parse_palette_chars_option(): Parse custom palette character set

Terminal Functions:

• update_dimensions_for_full_height(): Adjust dimensions to use full terminal height
• update_dimensions_to_terminal_size(): Sync dimensions with current terminal size
• print_project_links(): Print ascii-chat project links and info

Cryptography Helpers:

• detect_default_ssh_key(): Find default SSH key if not specified
• validate_options_and_report(): Cross-field validation with error reporting

See also

options.h - Main Options Module module

registry.h - Central registry of all Options Module

builder.h - Builder API using these validators

validation.h - Additional Validation Helpers functions

Author

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

Date

January 2026

Definition in file options/common.h.

Macro Definition Documentation

OPTIONS_COMMON_H

#define OPTIONS_COMMON_H

Definition at line 91 of file options/common.h.

Function Documentation

detect_default_ssh_key()

asciichat_error_t detect_default_ssh_key	(	char *	key_path,
		size_t	path_size )

Detect default SSH key path for the current user.

Checks if ~/.ssh/id_ed25519 exists and is a regular file. Only supports Ed25519 keys (modern, secure, fast).

Parameters

key_path	Buffer to store detected key path
path_size	Size of key_path buffer

Returns

ASCIICHAT_OK if found, ERROR_CRYPTO_KEY with helpful message otherwise

Note

Uses expand_path() to resolve tilde (~) in path

Prints message to stderr suggesting key generation if not found

Example:

char key_path[OPTIONS_BUFF_SIZE];
if (detect_default_ssh_key(key_path, sizeof(key_path)) == ASCIICHAT_OK) {
    log_debug("Using default SSH key: %s", key_path);
    SAFE_SNPRINTF(opt_encrypt_key, OPTIONS_BUFF_SIZE, "%s", key_path);
}

Definition at line 275 of file options/common.c.

                                                                           {
  // Use expand_path utility to resolve ~/.ssh/id_ed25519
  char *full_path = expand_path("~/.ssh/id_ed25519");
  if (!full_path) {
    return SET_ERRNO(ERROR_CONFIG, "Could not expand SSH key path");
  }
 
  // Check if the Ed25519 private key file exists
  struct stat st;
  bool found = (stat(full_path, &st) == 0 && S_ISREG(st.st_mode));
 
  if (found) {
    SAFE_SNPRINTF(key_path, path_size, "%s", full_path);
    log_debug("Found default SSH key: %s", full_path);
    SAFE_FREE(full_path);
    return ASCIICHAT_OK;
  }
 
  log_error("No Ed25519 SSH key found at %s", full_path);
  SAFE_FREE(full_path);
  return SET_ERRNO(
      ERROR_CRYPTO_KEY,
      "Only Ed25519 keys are supported (modern, secure, fast). Generate a new key with: ssh-keygen -t ed25519");
}

References ASCIICHAT_OK, ERROR_CONFIG, ERROR_CRYPTO_KEY, expand_path(), log_debug, log_error, SAFE_FREE, SAFE_SNPRINTF, and SET_ERRNO.

find_similar_option()

const char * find_similar_option	(	const char *	unknown_opt,
		const struct option *	options )

Find a similar option name for typo suggestions.

Uses Levenshtein distance to find the most similar option name from the provided options array. Only suggests options within a reasonable edit distance.

Parameters

unknown_opt	The unknown/misspelled option name
options	Array of valid option structures (must be NULL-terminated)

Returns

Suggested option name, or NULL if no good match found

Note

Uses LEVENSHTEIN_SUGGESTION_THRESHOLD to filter poor matches

Example:

const char *suggestion = find_similar_option("--colr", client_options);
if (suggestion) {
    fprintf(stderr, "Did you mean '--%s'?\n", suggestion);
}

Definition at line 43 of file options/common.c.

                                                                                       {
  if (!unknown_opt || !options) {
    return NULL;
  }
 
  const char *best_match = NULL;
  size_t best_distance = SIZE_MAX;
 
  for (int i = 0; options[i].name != NULL; i++) {
    size_t dist = levenshtein(unknown_opt, options[i].name);
    if (dist < best_distance) {
      best_distance = dist;
      best_match = options[i].name;
    }
  }
 
  // Only suggest if the distance is within our threshold
  if (best_distance <= LEVENSHTEIN_SUGGESTION_THRESHOLD) {
    return best_match;
  }
 
  return NULL;
}

References levenshtein(), and LEVENSHTEIN_SUGGESTION_THRESHOLD.

format_available_modes()

const char * format_available_modes

(

option_mode_bitmask_t

mode_bitmask

)

Format all available modes for an option as comma-separated list.

Converts a mode bitmask to a human-readable comma-separated list of mode names. Used in error messages to show which modes support a given option.

Parameters

mode_bitmask

Bitmask of modes (OPTION_MODE_SERVER | OPTION_MODE_CLIENT, etc.)

Returns

Formatted string like "server, client, mirror" or "global options"

Note

Returns pointer to static buffer - not thread-safe

Example:

option_mode_bitmask_t bitmask = OPTION_MODE_SERVER | OPTION_MODE_CLIENT;
const char *modes = format_available_modes(bitmask);
// modes == "server, client"

Definition at line 69 of file options/common.c.

                                                                       {
  static char buffer[OPTIONS_COMMON_BUFFER_BUFFER_SIZE];
  buffer[0] = '\0';
 
  bool first = true;
 
  // Check if it's a global/binary option
  if (mode_bitmask & OPTION_MODE_BINARY) {
    SAFE_SNPRINTF(buffer, sizeof(buffer), "global options");
    return buffer;
  }
 
  // Build comma-separated list of modes (ordered: default, client, server, mirror, discovery-service)
  if (mode_bitmask & OPTION_MODE_DISCOVERY) {
    safe_snprintf(buffer + strlen(buffer), sizeof(buffer) - strlen(buffer), "%sdefault", first ? "" : ", ");
    first = false;
  }
  if (mode_bitmask & OPTION_MODE_CLIENT) {
    safe_snprintf(buffer + strlen(buffer), sizeof(buffer) - strlen(buffer), "%sclient", first ? "" : ", ");
    first = false;
  }
  if (mode_bitmask & OPTION_MODE_SERVER) {
    safe_snprintf(buffer + strlen(buffer), sizeof(buffer) - strlen(buffer), "%sserver", first ? "" : ", ");
    first = false;
  }
  if (mode_bitmask & OPTION_MODE_MIRROR) {
    safe_snprintf(buffer + strlen(buffer), sizeof(buffer) - strlen(buffer), "%smirror", first ? "" : ", ");
    first = false;
  }
  if (mode_bitmask & OPTION_MODE_DISCOVERY_SVC) {
    safe_snprintf(buffer + strlen(buffer), sizeof(buffer) - strlen(buffer), "%sdiscovery-service", first ? "" : ", ");
    first = false;
  }
 
  if (mode_bitmask & OPTION_MODE_MCP_SERVER) {
    safe_snprintf(buffer + strlen(buffer), sizeof(buffer) - strlen(buffer), "%smcp-server", first ? "" : ", ");
    first = false;
  }
  if (mode_bitmask & OPTION_MODE_API_SERVER) {
    safe_snprintf(buffer + strlen(buffer), sizeof(buffer) - strlen(buffer), "%sapi-server", first ? "" : ", ");
  }
 
  // Fallback if no modes matched
  if (buffer[0] == '\0') {
    SAFE_SNPRINTF(buffer, sizeof(buffer), "unknown mode");
  }
 
  return buffer;
}

References OPTION_MODE_API_SERVER, OPTION_MODE_BINARY, OPTION_MODE_CLIENT, OPTION_MODE_DISCOVERY, OPTION_MODE_DISCOVERY_SVC, OPTION_MODE_MCP_SERVER, OPTION_MODE_MIRROR, OPTION_MODE_SERVER, OPTIONS_COMMON_BUFFER_BUFFER_SIZE, SAFE_SNPRINTF, and safe_snprintf().

Referenced by find_similar_option_with_mode().

get_required_argument()

char * get_required_argument	(	const char *	opt_value,
		char *	buffer,
		size_t	buffer_size,
		const char *	option_name,
		asciichat_mode_t	mode )

Handle required arguments with consistent error messages.

Validates that an option has a non-empty argument and processes it. Returns NULL on error with appropriate error message printed.

Handles edge cases:

• NULL or empty opt_value
• getopt_long bug where option name is returned as argument
• Arguments with '=' prefix (GNU-style –option=value)

Parameters

opt_value	Argument value from getopt_long
buffer	Buffer for storing processed argument
buffer_size	Size of buffer
option_name	Name of the option (for error messages)
mode	Current mode (client/server/mirror) for error messages

Returns

Pointer to processed argument string in buffer, or NULL on error

Note

Prints "option '--<name>' requires an argument" to stderr on error

Used internally by validate_required_argument()

Example:

char argbuf[OPTIONS_BUFF_SIZE];
char *value = get_required_argument(optarg, argbuf, sizeof(argbuf), "key", MODE_CLIENT);
if (!value) {
    return option_error_invalid();
}
SAFE_SNPRINTF(opt_encrypt_key, OPTIONS_BUFF_SIZE, "%s", value);

Definition at line 325 of file options/common.c.

                                                   {
  // Check if opt_value is NULL or empty
  if (!opt_value || strlen(opt_value) == 0) {
    goto error;
  }
 
  // Check if getopt_long returned the option name itself as the argument
  // This happens when a long option requiring an argument is at the end of argv
  if (opt_value && option_name && strcmp(opt_value, option_name) == 0) {
    goto error;
  }
 
  // Process the argument normally
  char *value_str = strip_equals_prefix(opt_value, buffer, buffer_size);
  if (!value_str) {
    goto error;
  }
 
  return value_str;
 
error:
  (void)0;
  const char *mode_name = (mode == MODE_SERVER ? "server" : (mode == MODE_MIRROR ? "mirror" : "client"));
  log_error("%s: option '--%s' requires an argument", mode_name, option_name);
  return NULL; // Signal error to caller
}

References buffer_size, log_error, MODE_MIRROR, MODE_SERVER, and strip_equals_prefix().

Referenced by validate_required_argument().

parse_color_mode_option()

asciichat_error_t parse_color_mode_option	(	const char *	value_str,
		options_t *	opts )

Parse –color-mode option and set opts->color_mode.

Validates color mode string and sets opts->color_mode field. Accepts: "auto", "none", "mono", "16", "16color", "256", "256color", "truecolor", "24bit"

Parameters

value_str	Color mode string from command line
opts	Options struct to update

Returns

ASCIICHAT_OK on success, ERROR_INVALID_PARAM on invalid mode

Note

Prints error message to stderr on failure

Sets opts->color_mode on success

Definition at line 398 of file options/common.c.

                                                                                  {
  if (!value_str || !opts) {
    return ERROR_INVALID_PARAM;
  }
 
  if (strcmp(value_str, OPT_VALUE_AUTO) == 0 || strcmp(value_str, "a") == 0) {
    opts->color_mode = COLOR_MODE_AUTO;
  } else if (strcmp(value_str, OPT_COLOR_MODE_NONE) == 0 || strcmp(value_str, OPT_COLOR_MODE_MONO) == 0) {
    opts->color_mode = COLOR_MODE_NONE;
  } else if (strcmp(value_str, OPT_COLOR_MODE_16) == 0 || strcmp(value_str, "16color") == 0 ||
             strcmp(value_str, "ansi") == 0) {
    opts->color_mode = COLOR_MODE_16_COLOR;
  } else if (strcmp(value_str, OPT_COLOR_MODE_256) == 0 || strcmp(value_str, "256color") == 0) {
    opts->color_mode = COLOR_MODE_256_COLOR;
  } else if (strcmp(value_str, OPT_COLOR_MODE_TRUECOLOR) == 0 || strcmp(value_str, "24bit") == 0 ||
             strcmp(value_str, "tc") == 0 || strcmp(value_str, "rgb") == 0 || strcmp(value_str, OPT_VALUE_TRUE) == 0) {
    opts->color_mode = COLOR_MODE_TRUECOLOR;
  } else {
    log_error("Invalid color mode '%s'. Valid modes: auto, none, 16, 256, truecolor", value_str);
    return ERROR_INVALID_PARAM;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, options_state::color_mode, COLOR_MODE_16_COLOR, COLOR_MODE_256_COLOR, COLOR_MODE_AUTO, COLOR_MODE_NONE, COLOR_MODE_TRUECOLOR, ERROR_INVALID_PARAM, log_error, OPT_COLOR_MODE_16, OPT_COLOR_MODE_256, OPT_COLOR_MODE_MONO, OPT_COLOR_MODE_NONE, OPT_COLOR_MODE_TRUECOLOR, OPT_VALUE_AUTO, and OPT_VALUE_TRUE.

parse_height_option()

asciichat_error_t parse_height_option	(	const char *	value_str,
		options_t *	opts )

Parse –height option and set opts->height.

Validates height value and sets opts->height and opts->auto_height fields.

Parameters

value_str	Height value from command line
opts	Options struct to update

Returns

ASCIICHAT_OK on success, ERROR_INVALID_PARAM if invalid

Note

Prints error message to stderr on failure

Sets opts->height and opts->auto_height = false on success

Definition at line 502 of file options/common.c.

                                                                              {
  if (!opts) {
    return ERROR_INVALID_PARAM;
  }
 
  int height_val;
  if (!validate_positive_int_opt(value_str, &height_val, "height")) {
    return ERROR_INVALID_PARAM;
  }
 
  opts->height = height_val;
  opts->auto_height = false;
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, options_state::auto_height, ERROR_INVALID_PARAM, options_state::height, and validate_positive_int_opt().

parse_log_level_option()

asciichat_error_t parse_log_level_option	(	const char *	value_str,
		options_t *	opts )

Parse –log-level option and set opt_log_level.

Validates log level string and sets global opt_log_level variable. Accepts: "dev", "debug", "info", "warn", "error", "fatal" (case-insensitive)

Parameters

value_str

Log level string from command line

Returns

ASCIICHAT_OK on success, ERROR_INVALID_PARAM if invalid

Note

Prints error message to stderr on failure

Sets opt_log_level global variable on success

Uses validate_opt_log_level() from validation.h

Definition at line 550 of file options/common.c.

                                                                                 {
  if (!opts) {
    return ERROR_INVALID_PARAM;
  }
 
  char error_msg[BUFFER_SIZE_SMALL];
  int log_level = validate_opt_log_level(value_str, error_msg, sizeof(error_msg));
 
  if (log_level == -1) {
    log_error("%s", error_msg);
    return ERROR_INVALID_PARAM;
  }
 
  opts->log_level = (log_level_t)log_level;
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, BUFFER_SIZE_SMALL, ERROR_INVALID_PARAM, log_error, options_state::log_level, and validate_opt_log_level().

parse_palette_chars_option()

asciichat_error_t parse_palette_chars_option	(	const char *	value_str,
		options_t *	opts )

Parse –palette-chars option and set opt_palette_custom.

Validates custom palette characters and sets global opt_palette_custom, opt_palette_custom_set, and opt_palette_type variables.

Parameters

value_str

Custom palette characters from command line

Returns

ASCIICHAT_OK on success, ERROR_INVALID_PARAM if too long

Note

Prints error message to stderr on failure

Sets opt_palette_custom, opt_palette_custom_set, and opt_palette_type on success

Maximum length is 255 characters (sizeof(opt_palette_custom) - 1)

Definition at line 467 of file options/common.c.

                                                                                     {
  if (!value_str || !opts) {
    return ERROR_INVALID_PARAM;
  }
 
  if (strlen(value_str) >= sizeof(opts->palette_custom)) {
    log_error("Invalid palette-chars: too long (%zu chars, max %zu)", strlen(value_str),
              sizeof(opts->palette_custom) - 1);
    return ERROR_INVALID_PARAM;
  }
 
  SAFE_STRNCPY(opts->palette_custom, value_str, sizeof(opts->palette_custom));
  opts->palette_custom[sizeof(opts->palette_custom) - 1] = '\0';
  opts->palette_custom_set = true;
  opts->palette_type = PALETTE_CUSTOM;
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, log_error, PALETTE_CUSTOM, options_state::palette_custom, options_state::palette_custom_set, options_state::palette_type, and SAFE_STRNCPY.

parse_palette_option()

asciichat_error_t parse_palette_option	(	const char *	value_str,
		options_t *	opts )

Parse –palette option and set opt_palette_type.

Validates palette type string and sets global opt_palette_type variable. Accepts: "standard", "blocks", "digital", "minimal", "cool", "custom"

Parameters

value_str

Palette type string from command line

Returns

ASCIICHAT_OK on success, ERROR_INVALID_PARAM on invalid palette

Note

Prints error message to stderr on failure

Sets opt_palette_type global variable on success

Definition at line 442 of file options/common.c.

                                                                               {
  if (!value_str || !opts) {
    return ERROR_INVALID_PARAM;
  }
 
  if (strcmp(value_str, OPT_PALETTE_STANDARD) == 0) {
    opts->palette_type = PALETTE_STANDARD;
  } else if (strcmp(value_str, OPT_PALETTE_BLOCKS) == 0) {
    opts->palette_type = PALETTE_BLOCKS;
  } else if (strcmp(value_str, OPT_PALETTE_DIGITAL) == 0) {
    opts->palette_type = PALETTE_DIGITAL;
  } else if (strcmp(value_str, OPT_PALETTE_MINIMAL) == 0) {
    opts->palette_type = PALETTE_MINIMAL;
  } else if (strcmp(value_str, OPT_PALETTE_COOL) == 0) {
    opts->palette_type = PALETTE_COOL;
  } else if (strcmp(value_str, OPT_PALETTE_CUSTOM) == 0) {
    opts->palette_type = PALETTE_CUSTOM;
  } else {
    log_error("Invalid palette '%s'. Valid palettes: standard, blocks, digital, minimal, cool, custom", value_str);
    return ERROR_INVALID_PARAM;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, log_error, OPT_PALETTE_BLOCKS, OPT_PALETTE_COOL, OPT_PALETTE_CUSTOM, OPT_PALETTE_DIGITAL, OPT_PALETTE_MINIMAL, OPT_PALETTE_STANDARD, PALETTE_BLOCKS, PALETTE_COOL, PALETTE_CUSTOM, PALETTE_DIGITAL, PALETTE_MINIMAL, PALETTE_STANDARD, and options_state::palette_type.

parse_render_mode_option()

asciichat_error_t parse_render_mode_option	(	const char *	value_str,
		options_t *	opts )

Parse –render-mode option and set opts->render_mode.

Validates render mode string and sets opts->render_mode field. Accepts: "foreground", "fg", "background", "bg", "half-block", "halfblock"

Parameters

value_str	Render mode string from command line
opts	Options struct to update

Returns

ASCIICHAT_OK on success, ERROR_INVALID_PARAM on invalid mode

Note

Prints error message to stderr on failure

Sets opts->render_mode on success

Definition at line 423 of file options/common.c.

                                                                                   {
  if (!value_str || !opts) {
    return ERROR_INVALID_PARAM;
  }
 
  if (strcmp(value_str, OPT_RENDER_MODE_FOREGROUND) == 0 || strcmp(value_str, OPT_RENDER_MODE_FG) == 0) {
    opts->render_mode = RENDER_MODE_FOREGROUND;
  } else if (strcmp(value_str, OPT_RENDER_MODE_BACKGROUND) == 0 || strcmp(value_str, OPT_RENDER_MODE_BG) == 0) {
    opts->render_mode = RENDER_MODE_BACKGROUND;
  } else if (strcmp(value_str, OPT_RENDER_MODE_HALF_BLOCK) == 0 || strcmp(value_str, "halfblock") == 0) {
    opts->render_mode = RENDER_MODE_HALF_BLOCK;
  } else {
    log_error("Invalid render mode '%s'. Valid modes: foreground, background, half-block", value_str);
    return ERROR_INVALID_PARAM;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, log_error, OPT_RENDER_MODE_BACKGROUND, OPT_RENDER_MODE_BG, OPT_RENDER_MODE_FG, OPT_RENDER_MODE_FOREGROUND, OPT_RENDER_MODE_HALF_BLOCK, and options_state::render_mode.

parse_snapshot_delay_option()

asciichat_error_t parse_snapshot_delay_option	(	const char *	value_str,
		options_t *	opts )

Parse –snapshot-delay option and set opts->snapshot_delay.

Validates snapshot delay (non-negative float) and sets opts->snapshot_delay field.

Parameters

value_str	Snapshot delay in seconds from command line
opts	Options struct to update

Returns

ASCIICHAT_OK on success, ERROR_INVALID_PARAM if invalid

Note

Prints error message to stderr on failure

Sets opts->snapshot_delay on success

Definition at line 533 of file options/common.c.

                                                                                      {
  if (!value_str || !opts) {
    return ERROR_INVALID_PARAM;
  }
 
  char *endptr;
  float delay = strtof(value_str, &endptr);
  if (endptr == value_str || *endptr != '\0' || delay < 0.0f) {
    log_error("Invalid snapshot delay '%s'. Must be a non-negative number.", value_str);
    return ERROR_INVALID_PARAM;
  }
 
  opts->snapshot_delay = delay;
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, log_error, and options_state::snapshot_delay.

parse_webcam_index_option()

asciichat_error_t parse_webcam_index_option	(	const char *	value_str,
		options_t *	opts )

Parse –webcam-index option and set opts->webcam_index.

Validates webcam index and sets opts->webcam_index field.

Parameters

value_str	Webcam index from command line
opts	Options struct to update

Returns

ASCIICHAT_OK on success, ERROR_INVALID_PARAM if invalid

Note

Prints error message to stderr on failure

Sets opts->webcam_index on success

Definition at line 518 of file options/common.c.

                                                                                    {
  if (!opts) {
    return ERROR_INVALID_PARAM;
  }
 
  unsigned short int index_val;
  if (!validate_webcam_index(value_str, &index_val)) {
    return ERROR_INVALID_PARAM;
  }
 
  opts->webcam_index = index_val;
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, validate_webcam_index(), and options_state::webcam_index.

parse_width_option()

asciichat_error_t parse_width_option	(	const char *	value_str,
		options_t *	opts )

Parse –width option and set opts->width.

Validates width value and sets opts->width and opts->auto_width fields.

Parameters

value_str	Width value from command line
opts	Options struct to update

Returns

ASCIICHAT_OK on success, ERROR_INVALID_PARAM if invalid

Note

Prints error message to stderr on failure

Sets opts->width and opts->auto_width = false on success

Definition at line 486 of file options/common.c.

                                                                             {
  if (!opts) {
    return ERROR_INVALID_PARAM;
  }
 
  int width_val;
  if (!validate_positive_int_opt(value_str, &width_val, "width")) {
    return ERROR_INVALID_PARAM;
  }
 
  opts->width = width_val;
  opts->auto_width = false;
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, options_state::auto_width, ERROR_INVALID_PARAM, validate_positive_int_opt(), and options_state::width.

print_project_links()

void print_project_links

(

FILE *

desc

)

Print project links with link emoji and colored styling.

Parameters

desc	Output file stream (typically stdout)

Definition at line 773 of file options/common.c.

                                     {
  if (!desc) {
    return;
  }
 
  (void)fprintf(desc, "🔗 %s\n", colored_string(LOG_COLOR_GREY, "https://ascii-chat.com"));
  (void)fprintf(desc, "🔗 %s\n", colored_string(LOG_COLOR_GREY, "https://github.com/zfogg/ascii-chat"));
}

References colored_string(), and LOG_COLOR_GREY.

read_password_from_stdin()

char * read_password_from_stdin

(

const char *

prompt

)

Read password from stdin with prompt.

Parameters

prompt

Prompt message to display to user

Returns

Allocated password string (caller must free), or NULL on error

Prompts user for password input using prompt_password_simple() from util/password.h. Returns dynamically allocated string that must be freed by caller.

Note

Returns NULL if password input fails or if not running in a TTY.

Caller must use SAFE_FREE() to deallocate returned string.

Definition at line 354 of file options/common.c.

                                                   {
  char *password_buf = SAFE_MALLOC(PASSWORD_MAX_LEN, char *);
  if (!password_buf) {
    return NULL;
  }
 
  if (prompt_password_simple(prompt, password_buf, PASSWORD_MAX_LEN) != 0) {
    SAFE_FREE(password_buf);
    return NULL;
  }
 
  return password_buf; // Caller must free
}

References PASSWORD_MAX_LEN, prompt_password_simple(), SAFE_FREE, and SAFE_MALLOC.

strip_equals_prefix()

char * strip_equals_prefix	(	const char *	opt_value,
		char *	buffer,
		size_t	buffer_size )

Strip equals sign prefix from option argument.

Internal helper that handles GNU-style long options with = syntax (–option=value). Copies argument to buffer and returns pointer past the '=' if present.

Parameters

opt_value	Raw option value from getopt_long
buffer	Buffer to store processed value
buffer_size	Size of buffer

Returns

Pointer to value in buffer (past '=' if present), or NULL if empty

Note

Returns NULL for empty strings after stripping '='

Buffer is always null-terminated via SAFE_SNPRINTF

Example:

char argbuf[OPTIONS_BUFF_SIZE];
char *value = strip_equals_prefix("=1234", argbuf, sizeof(argbuf));
// value points to "1234" in argbuf

Definition at line 305 of file options/common.c.

                                                                                   {
  if (!opt_value)
    return NULL;
 
  SAFE_SNPRINTF(buffer, buffer_size, "%s", opt_value);
  char *value_str = buffer;
  if (value_str[0] == '=') {
    value_str++; // Skip the equals sign
  }
 
  // Return NULL for empty strings (treat as missing argument)
  if (strlen(value_str) == 0) {
    return NULL;
  }
 
  return value_str;
}

References buffer_size, and SAFE_SNPRINTF.

Referenced by get_required_argument().

strtoint_safe()

int strtoint_safe

(

const char *

str

)

Safely parse string to integer with validation.

Parses a string to integer using parse_int32() with full range checking. Returns INT_MIN on error (NULL input, empty string, invalid format, out of range).

Parameters

str	String to parse

Returns

Parsed integer value, or INT_MIN on error

Warning

INT_MIN is used as error sentinel, so cannot represent INT_MIN value

Example:

int val = strtoint_safe(optarg);
if (val == INT_MIN) {
    fprintf(stderr, "Invalid integer: %s\n", optarg);
    return ERROR_INVALID_PARAM;
}

Definition at line 177 of file options/common.c.

                                   {
  if (!str || *str == '\0') {
    return INT_MIN; // Error: NULL or empty string
  }
 
  int32_t result = 0;
  // Use safe parsing utility with full int32 range validation
  if (parse_int32(str, &result, INT_MIN, INT_MAX) != ASCIICHAT_OK) {
    return INT_MIN; // Error: invalid input or out of range
  }
 
  return (int)result;
}

update_dimensions_for_full_height()

void update_dimensions_for_full_height

(

options_t *

opts

)

Update dimensions for full-height mode.

Sets opt_height to terminal height when auto-detected. Used during initialization to maximize vertical space usage.

Behavior:

• Both auto: Set both width and height to terminal size
• Only height auto: Set height to terminal height
• Only width auto: Set width to terminal width
• Neither auto: No change

Note

Does not use log_debug because logging may not be initialized yet

Fails silently if terminal size detection fails (keeps defaults)

Example:

// During options_init():
if (auto_height || auto_width) {
    update_dimensions_for_full_height();
}

Definition at line 620 of file options/common.c.

                                                        {
  if (!opts) {
    return;
  }
 
  unsigned short int term_width, term_height;
 
  // Note: Logging is not available during options_init, so we can't use log_debug here
  asciichat_error_t result = get_terminal_size(&term_width, &term_height);
 
  if (result == ASCIICHAT_OK) {
    // If both dimensions are auto, set height to terminal height and let
    // aspect_ratio calculate width
    if (opts->auto_height && opts->auto_width) {
      opts->height = term_height;
      opts->width = term_width; // Also set width when both are auto
    }
    // If only height is auto, use full terminal height
    else if (opts->auto_height) {
      opts->height = term_height;
    }
    // If only width is auto, use full terminal width
    else if (opts->auto_width) {
      opts->width = term_width;
    }
  } else {
    // Terminal size detection failed, but we can still continue with defaults
  }
}

update_dimensions_to_terminal_size()

void update_dimensions_to_terminal_size

(

options_t *

opts

)

Update dimensions to current terminal size.

Updates opt_width and opt_height to current terminal size for auto-detected dimensions. Used after logging is initialized (can use log_debug).

Behavior:

• auto_width: Set width to terminal width
• auto_height: Set height to terminal height
• Neither: No change

Note

Logs debug messages about dimension updates

Logs debug message if terminal size detection fails

Example:

// After logging initialization:
update_dimensions_to_terminal_size();
log_info("Terminal dimensions: %dx%d", opt_width, opt_height);

Definition at line 650 of file options/common.c.

                                                         {
  if (!opts) {
    return;
  }
 
  unsigned short int term_width, term_height;
  // Get current terminal size (get_terminal_size already handles ioctl first, then $COLUMNS/$LINES fallback)
  asciichat_error_t terminal_result = get_terminal_size(&term_width, &term_height);
  if (terminal_result == ASCIICHAT_OK) {
    // Use INFO level so this is visible without -v flag (important for debugging dimension issues)
    log_dev("Terminal size detected: %ux%u (auto_width=%d, auto_height=%d)", term_width, term_height, opts->auto_width,
            opts->auto_height);
    if (opts->auto_width) {
      opts->width = term_width;
      log_debug("Auto-width: set width to %u", opts->width);
    }
    if (opts->auto_height) {
      opts->height = term_height;
      log_debug("Auto-height: set height to %u", opts->height);
    }
    log_debug("Final dimensions: %ux%u", opts->width, opts->height);
  } else {
    // Terminal detection failed - keep the default values set in options_init()
    log_warn("TERMINAL_DETECT_FAIL: Could not detect terminal size, using defaults: %ux%u", opts->width, opts->height);
  }
}

validate_fps_opt()

bool validate_fps_opt	(	const char *	value_str,
		int *	out_fps )

Validate FPS value (0 for auto, otherwise 1-144).

Internal option parsing helper that validates FPS is in reasonable range. Range chosen to support 1 FPS (slideshows) to 144 FPS (high refresh monitors).

Parameters

value_str	String to validate
out_fps	Output parameter for validated FPS

Returns

true if valid, false otherwise

Example:

int fps;
if (!validate_fps_opt(optarg, &fps)) {
    return option_error_invalid();
}
opt_fps = fps;

Definition at line 237 of file options/common.c.

                                                           {
  if (!value_str || !out_fps) {
    return false;
  }
 
  int fps_val = strtoint_safe(value_str);
  if (fps_val == INT_MIN || fps_val < 0 || fps_val > 144) {
    log_error("Invalid FPS value '%s'. FPS must be between 0 and 144.", value_str);
    return false;
  }
 
  *out_fps = fps_val;
  return true;
}

References log_error, and strtoint_safe().

validate_options_and_report()

asciichat_error_t validate_options_and_report	(	const void *	config,
		const void *	opts )

Validate options and report errors to stderr.

Calls options_config_validate() and handles error message display and cleanup. Validates all option dependencies, conflicts, and custom validators.

Parameters

config	Options configuration (opaque pointer, defined in builder.h)
opts	Options struct to validate

Returns

ASCIICHAT_OK if valid, error code otherwise

Note

Prints error message to stderr if validation fails

Frees error message internally

Example:

asciichat_error_t result = validate_options_and_report(config, opts);
if (result != ASCIICHAT_OK) {
    options_config_destroy(config);
    return result;
}

Definition at line 735 of file options/common.c.

                                                                                    {
  if (!config || !opts) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Config or options is NULL");
  }
 
  char *error_message = NULL;
  // Cast opaque config pointer to actual type
  const options_config_t *config_typed = (const options_config_t *)config;
  const options_t *options = (const options_t *)opts;
  if (options->webrtc_relay_only && options->detected_mode == MODE_CLIENT) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Relay only requires discovery mode; connect using a session name");
  }
  if (options->webrtc_relay_only && options->detected_mode == MODE_SERVER && !options->discovery) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Server relay only requires --discovery");
  }
  if (options->webrtc_relay_only && (options->no_webrtc || options->webrtc_disable_turn)) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "--webrtc-relay-only conflicts with --no-webrtc or --webrtc-disable-turn");
  }
  if ((options->turn_username[0] != '\0') != (options->turn_credential[0] != '\0')) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Provide both --turn-username and --turn-credential, or leave both blank");
  }
  if (strlen(options->turn_username) > 127 || strlen(options->turn_credential) > 127) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "TURN username and credential must each fit 127 bytes");
  }
  asciichat_error_t result = options_config_validate(config_typed, opts, &error_message);
  if (result != ASCIICHAT_OK) {
    if (error_message) {
      log_error("%s", error_message);
      SAFE_FREE(error_message);
    }
  }
  return result;
}

References ASCIICHAT_OK, options_state::detected_mode, options_state::discovery, ERROR_INVALID_PARAM, log_error, MODE_CLIENT, MODE_SERVER, options_state::no_webrtc, options_config_validate(), SAFE_FREE, SET_ERRNO, options_state::turn_credential, options_state::turn_username, options_state::webrtc_disable_turn, and options_state::webrtc_relay_only.

validate_port_opt()

bool validate_port_opt	(	const char *	value_str,
		uint16_t *	out_port )

Validate port number (1-65535).

Internal option parsing helper that validates a port number is in valid range. Uses parse_port() for robust validation.

Parameters

value_str	String to validate
out_port	Output parameter for validated port

Returns

true if valid, false otherwise

Example:

uint16_t port;
if (!validate_port_opt(optarg, &port)) {
    return option_error_invalid();
}
opt_port = port;

Definition at line 222 of file options/common.c.

                                                                  {
  if (!value_str || !out_port) {
    return false;
  }
 
  // Use safe integer parsing with range validation
  if (parse_port(value_str, out_port) != ASCIICHAT_OK) {
    log_error("Invalid port value '%s'. Port must be a number between 1 and 65535.", value_str);
    return false;
  }
 
  return true;
}

References ASCIICHAT_OK, log_error, and parse_port().

validate_positive_int_opt()

bool validate_positive_int_opt	(	const char *	value_str,
		int *	out_value,
		const char *	param_name )

Validate a positive integer value.

Internal option parsing helper that validates a string represents a positive integer (> 0). Prints error message on failure.

Parameters

value_str	String to validate
out_value	Output parameter for validated integer
param_name	Parameter name for error messages

Returns

true if valid, false otherwise

Example:

int fps;
if (!validate_positive_int_opt(optarg, &fps, "FPS")) {
    return option_error_invalid();
}

Definition at line 206 of file options/common.c.

                                                                                              {
  if (!value_str || !out_value) {
    return false;
  }
 
  int val = strtoint_safe(value_str);
  if (val == INT_MIN || val <= 0) {
    log_error("Invalid %s value '%s'. %s must be a positive integer.", param_name, value_str, param_name);
    return false;
  }
 
  *out_value = val;
  return true;
}

References log_error, and strtoint_safe().

Referenced by parse_height_option(), and parse_width_option().

validate_required_argument()

char * validate_required_argument	(	const char *	optarg,
		char *	argbuf,
		size_t	argbuf_size,
		const char *	option_name,
		asciichat_mode_t	mode )

Validate and retrieve required argument for an option.

Wrapper around get_required_argument() that also sets error code on failure. Used for options that must have an argument.

Parameters

optarg	Argument value from getopt_long
argbuf	Buffer for storing processed argument
argbuf_size	Size of argbuf
option_name	Name of the option (for error messages)
mode	Current mode (client/server/mirror) for error messages

Returns

Pointer to processed argument string in argbuf, or NULL on error

Note

On error, prints message to stderr and calls option_error_invalid()

Example:

char argbuf[OPTIONS_BUFF_SIZE];
char *value = validate_required_argument(optarg, argbuf, sizeof(argbuf), "port", MODE_CLIENT);
if (!value) {
    return option_error_invalid();
}

Definition at line 196 of file options/common.c.

                                                        {
  char *value = get_required_argument(optarg, argbuf, argbuf_size, option_name, mode);
  if (!value) {
    (void)option_error_invalid();
  }
  return value;
}

References get_required_argument().

validate_webcam_index()

bool validate_webcam_index	(	const char *	value_str,
		unsigned short int *	out_index )

Validate webcam index using the common device index validator.

Validates webcam index is a non-negative integer. Unlike audio device indices, webcam indices do not support -1 (default).

Parameters

value_str	String to validate
out_index	Output parameter for validated index

Returns

true if valid, false otherwise

Example:

unsigned short int webcam_idx;
if (!validate_webcam_index(optarg, &webcam_idx)) {
    return option_error_invalid();
}
opt_webcam_index = webcam_idx;

Definition at line 253 of file options/common.c.

                                                                                 {
  if (!value_str || !out_index) {
    return false;
  }
 
  char error_msg[BUFFER_SIZE_SMALL];
  int parsed_index = validate_opt_device_index(value_str, error_msg, sizeof(error_msg));
  if (parsed_index == INT_MIN) {
    log_error("Invalid webcam index: %s", error_msg);
    return false;
  }
  // Webcam index doesn't support -1 (default), must be >= 0
  if (parsed_index < 0) {
    log_error("Invalid webcam index '%s'. Webcam index must be a non-negative integer.", value_str);
    return false;
  }
 
  *out_index = (unsigned short int)parsed_index;
  return true;
}

References BUFFER_SIZE_SMALL, log_error, and validate_opt_device_index().

Referenced by parse_webcam_index_option().