parsers.h File Reference

Custom option parsers for enum types. More...

Go to the source code of this file.

Functions
bool	parse_color_setting (const char *arg, void *dest, char **error_msg)
	Parse color setting option (–color flag)
bool	parse_utf8_setting (const char *arg, void *dest, char **error_msg)
	Parse UTF-8 setting option (–utf8 flag)
bool	parse_color_mode (const char *arg, void *dest, char **error_msg)
	Parse terminal color level option.
bool	parse_color_filter (const char *arg, void *dest, char **error_msg)
	Parse color filter option.
bool	parse_render_mode (const char *arg, void *dest, char **error_msg)
	Parse render mode option.
bool	parse_render_theme (const char *arg, void *dest, char **error_msg)
	Parse render theme option for pixel rendering.
bool	parse_palette_type (const char *arg, void *dest, char **error_msg)
	Parse palette type option.
bool	parse_palette_chars (const char *arg, void *dest, char **error_msg)
	Parse custom palette characters option.
bool	parse_log_level (const char *arg, void *dest, char **error_msg)
	Parse log level option.
bool	parse_port_option (const char *arg, void *dest, char **error_msg)
	Parse and validate port option for CLI.
int	parse_server_bind_address (const char *arg, void *config, char **remaining, int num_remaining, char **error_msg)
	Parse server bind address positional argument.
int	parse_client_address (const char *arg, void *config, char **remaining, int num_remaining, char **error_msg)
	Parse client address positional argument.
int	parse_mirror_media (const char *arg, void *config, char **remaining, int num_remaining, char **error_msg)
	Parse mirror mode media positional argument.
bool	parse_verbose_flag (const char *arg, void *dest, char **error_msg)
	Custom parser for –verbose flag.
bool	parse_timestamp (const char *arg, void *dest, char **error_msg)
	Custom parser for –timestamp flag.
bool	parse_volume (const char *arg, void *dest, char **error_msg)
	Custom parser for volume options (–volume, –speakers-volume, –microphone-volume)
bool	parse_log_file (const char *arg, void *dest, char **error_msg)
	Custom parser for log file paths (–log-file, -L)
bool	parse_audio_source (const char *arg, void *dest, char **error_msg)
	Parse visualization source option (–audio-source)
bool	parse_audio_capture_source (const char *arg, void *dest, char **error_msg)

Detailed Description

Custom option parsers for enum types.

This module provides custom callback parsers for enum-based options used by the options builder system. Each parser converts a string argument to the appropriate enum value.

Author

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

Date

December 2025

Definition in file parsers.h.

Function Documentation

parse_audio_capture_source()

bool parse_audio_capture_source	(	const char *	arg,
		void *	dest,
		char **	error_msg
	)

Parse local capture policy option (–audio-capture-source).

Definition at line 1197 of file parsers.c.

                                                                               {
  if (!arg || !dest) {
    if (error_msg)
      *error_msg = platform_strdup("Internal error: NULL argument or destination");
    return false;
  }
 
  audio_capture_source_t *source = (audio_capture_source_t *)dest;
  char lower[32];
  to_lower(arg, lower, sizeof(lower));
  if (strcmp(lower, OPT_AUDIO_CAPTURE_SOURCE_AUTO) == 0)
    *source = AUDIO_CAPTURE_SOURCE_AUTO;
  else if (strcmp(lower, OPT_AUDIO_CAPTURE_SOURCE_MIC) == 0)
    *source = AUDIO_CAPTURE_SOURCE_MIC;
  else if (strcmp(lower, OPT_AUDIO_CAPTURE_SOURCE_MEDIA) == 0)
    *source = AUDIO_CAPTURE_SOURCE_MEDIA;
  else if (strcmp(lower, OPT_AUDIO_CAPTURE_SOURCE_BOTH) == 0)
    *source = AUDIO_CAPTURE_SOURCE_BOTH;
  else if (strcmp(lower, OPT_AUDIO_CAPTURE_SOURCE_REMOTE) == 0)
    *source = AUDIO_CAPTURE_SOURCE_REMOTE;
  else {
    if (error_msg)
      *error_msg = platform_strdup("Audio capture source must be 'auto', 'mic', 'media', 'both', or 'remote'");
    return false;
  }
  return true;
}

References AUDIO_CAPTURE_SOURCE_AUTO, AUDIO_CAPTURE_SOURCE_BOTH, AUDIO_CAPTURE_SOURCE_MEDIA, AUDIO_CAPTURE_SOURCE_MIC, AUDIO_CAPTURE_SOURCE_REMOTE, OPT_AUDIO_CAPTURE_SOURCE_AUTO, OPT_AUDIO_CAPTURE_SOURCE_BOTH, OPT_AUDIO_CAPTURE_SOURCE_MEDIA, OPT_AUDIO_CAPTURE_SOURCE_MIC, OPT_AUDIO_CAPTURE_SOURCE_REMOTE, and platform_strdup().

parse_audio_source()

bool parse_audio_source	(	const char *	arg,
		void *	dest,
		char **	error_msg
	)

Parse visualization source option (–audio-source)

Parameters

arg	String argument (e.g., "all", "call", "mic", "media")
dest	Destination pointer (audio_source_t*)
error_msg	Optional error message output (set on failure)

Returns

true on success, false on error

Valid values: all (the default), call, mic, or media.

Definition at line 1161 of file parsers.c.

                                                                       {
  if (!arg || !dest) {
    if (error_msg) {
      *error_msg = platform_strdup("Internal error: NULL argument or destination");
    }
    return false;
  }
 
  audio_source_t *audio_source = (audio_source_t *)dest;
  char lower[32];
  to_lower(arg, lower, sizeof(lower));
 
  if (strcmp(lower, OPT_AUDIO_SOURCE_ALL) == 0 || strcmp(lower, OPT_AUDIO_SOURCE_AUTO) == 0 ||
      strcmp(lower, "both") == 0) {
    *audio_source = AUDIO_SOURCE_ALL;
    return true;
  }
  if (strcmp(lower, OPT_AUDIO_SOURCE_CALL) == 0 || strcmp(lower, "remote") == 0) {
    *audio_source = AUDIO_SOURCE_CALL;
    return true;
  }
  if (strcmp(lower, OPT_AUDIO_SOURCE_MIC) == 0) {
    *audio_source = AUDIO_SOURCE_MIC;
    return true;
  }
  if (strcmp(lower, OPT_AUDIO_SOURCE_MEDIA) == 0) {
    *audio_source = AUDIO_SOURCE_MEDIA;
    return true;
  }
 
  if (error_msg) {
    *error_msg = platform_strdup("Audio source must be 'all', 'call', 'mic', or 'media'");
  }
  return false;
}

References AUDIO_SOURCE_ALL, AUDIO_SOURCE_CALL, AUDIO_SOURCE_MEDIA, AUDIO_SOURCE_MIC, OPT_AUDIO_SOURCE_ALL, OPT_AUDIO_SOURCE_AUTO, OPT_AUDIO_SOURCE_CALL, OPT_AUDIO_SOURCE_MEDIA, OPT_AUDIO_SOURCE_MIC, and platform_strdup().

parse_client_address()

int parse_client_address	(	const char *	arg,
		void *	config,
		char **	remaining,
		int	num_remaining,
		char **	error_msg
	)

Parse client address positional argument.

Parameters

arg	Address argument in format [address][:port]
config	Pointer to options struct (must contain address and port fields)
remaining	Remaining positional args (unused for client)
num_remaining	Count of remaining args
error_msg	Error message output (set on failure)

Returns

Number of args consumed (always 1), or -1 on error

Client address parsing rules:

• Parses single argument: [address][:port]
• IPv6 with brackets and port: [::1]:8080
• IPv4/hostname with port: 192.168.1.1:8080 or example.com:8080
• Bare IPv6: ::1 (detected by multiple colons)
• Bare hostname/IPv4: 192.168.1.1 or example.com
• IPv4 addresses starting with digit are validated strictly
• Detects port conflict if –port flag was already used

This parser handles the complex logic of separating address from optional port while correctly handling IPv6 addresses that contain colons.

Example usage with options_builder_add_positional():

options_builder_add_positional(
    builder,
    "address",
    "[address][:port] - Server address (IPv4, IPv6, or hostname) with optional port",
    false,  // Not required (defaults to localhost:27224)
    parse_client_address
);

Implements the client address parsing logic from client.c. Parses [address][:port] with complex IPv6 handling.

Definition at line 685 of file parsers.c.

                                                                                                               {
  (void)remaining;
  (void)num_remaining;
 
  if (!arg || !config) {
    if (error_msg) {
      *error_msg = platform_strdup("Internal error: NULL argument or config");
    }
    return -1;
  }
 
  log_debug("parse_client_address: Processing argument: '%s'", arg);
 
  // Access address and port fields from options_state struct
  char *address = (char *)config + offsetof(struct options_state, address);
  int *port = (int *)((char *)config + offsetof(struct options_state, port));
 
  // Check for WebSocket URL (ws:// or wss://) FIRST before session string validation
  // WebSocket URLs are passed through without validation or port extraction
  if (strncmp(arg, "ws://", 5) == 0 || strncmp(arg, "wss://", 6) == 0) {
    log_debug("Detected WebSocket URL: %s", arg);
    SAFE_SNPRINTF(address, OPTIONS_BUFF_SIZE, "%s", arg);
    // For wss://, TLS handles transport encryption - allow ACIP to handle auth independently
    // For ws://, default to ACIP encryption (no TLS)
    if (strncmp(arg, "wss://", 6) == 0) {
      bool *no_encrypt = (bool *)config + offsetof(struct options_state, no_encrypt);
      *no_encrypt = true;
      log_debug("Auto-detected wss:// - setting no_encrypt=true (TLS handles transport encryption, ACIP handles auth)");
    }
    // Don't set port - WebSocket transport handles URL parsing internally
    return 1; // Consumed 1 argument
  }
 
  // Check for TCP URL (tcp://) - passed through directly to FFmpeg
  // TCP URLs are used for streaming media from custom TCP servers
  if (strncmp(arg, "tcp://", 6) == 0) {
    log_debug("Detected TCP URL: %s", arg);
    SAFE_SNPRINTF(address, OPTIONS_BUFF_SIZE, "%s", arg);
    // Don't set port - TCP transport handles URL parsing internally
    return 1; // Consumed 1 argument
  }
 
  // Check if this is a session string (format: adjective-noun-noun)
  // Session strings have exactly 2 hyphens, only lowercase letters, length 5-47
  bool is_session = is_session_string(arg);
  log_debug("parse_client_address: is_session_string('%s') = %s", arg, is_session ? "true" : "false");
 
  if (is_session) {
    // This is a session string, not a server address
    char *session_string = (char *)config + offsetof(struct options_state, session_string);
    SAFE_SNPRINTF(session_string, SESSION_STRING_BUFFER_SIZE, "%s", arg);
    log_debug("parse_client_address: Stored session string: %s", arg);
    return 1; // Consumed 1 arg
  }
 
  // Not a session string, parse as server address
  log_debug("parse_client_address: Parsing as server address (not a session string)");
 
  // Check for port in address (format: address:port or [ipv6]:port)
  const char *colon = strrchr(arg, ':');
 
  if (colon != NULL) {
    // Check if this is IPv6 with port [::1]:port or plain hostname:port
    if (arg[0] == '[') {
      // IPv6 with brackets: [address]:port
      const char *closing_bracket = strchr(arg, ']');
      if (closing_bracket && closing_bracket < colon) {
        // Extract address (remove brackets)
        size_t addr_len = (size_t)(closing_bracket - arg - 1);
        if (addr_len >= OPTIONS_BUFF_SIZE) {
          if (error_msg) {
            *error_msg = platform_strdup("IPv6 address too long");
          }
          return -1;
        }
        SAFE_SNPRINTF(address, OPTIONS_BUFF_SIZE, "%.*s", (int)addr_len, arg + 1);
 
        // Extract and validate port
        const char *port_str = colon + 1;
        char *endptr;
        long port_num = strtol(port_str, &endptr, 10);
        if (*endptr != '\0' || port_num < 1 || port_num > 65535) {
          if (error_msg) {
            char msg[256];
            safe_snprintf(msg, sizeof(msg), "Invalid port number '%s'. Must be 1-65535.", port_str);
            *error_msg = platform_strdup(msg);
          }
          return -1;
        }
        *port = (int)port_num;
      }
    } else {
      // Check if it's IPv6 without brackets (no port allowed)
      // or hostname/IPv4:port
      size_t colon_count = 0;
      for (const char *p = arg; *p; p++) {
        if (*p == ':')
          colon_count++;
      }
 
      if (colon_count == 1) {
        // Likely hostname:port or IPv4:port
        size_t addr_len = (size_t)(colon - arg);
        if (addr_len >= OPTIONS_BUFF_SIZE) {
          if (error_msg) {
            *error_msg = platform_strdup("Address too long");
          }
          return -1;
        }
        SAFE_SNPRINTF(address, OPTIONS_BUFF_SIZE, "%.*s", (int)addr_len, arg);
 
        // Extract and validate port
        const char *port_str = colon + 1;
        char *endptr;
        long port_num = strtol(port_str, &endptr, 10);
        if (*endptr != '\0' || port_num < 1 || port_num > 65535) {
          if (error_msg) {
            char msg[256];
            safe_snprintf(msg, sizeof(msg), "Invalid port number '%s'. Must be 1-65535.", port_str);
            *error_msg = platform_strdup(msg);
          }
          return -1;
        }
        *port = (int)port_num;
      } else {
        // Multiple colons - likely bare IPv6 address
        SAFE_SNPRINTF(address, OPTIONS_BUFF_SIZE, "%s", arg);
      }
    }
  } else {
    // No colon - just an address
    SAFE_SNPRINTF(address, OPTIONS_BUFF_SIZE, "%s", arg);
  }
 
  // Validate addresses using comprehensive IPv4/IPv6 detection
  bool has_dot = strchr(address, '.') != NULL;
  bool has_colon = strchr(address, ':') != NULL;
  bool starts_with_digit = address[0] >= '0' && address[0] <= '9';
 
  // Potential IPv6 address (has colons) - validate as IPv6
  if (has_colon) {
    if (!is_valid_ipv6(address)) {
      if (error_msg) {
        char msg[512];
        safe_snprintf(msg, sizeof(msg),
                      "Invalid IPv6 address '%s'.\n"
                      "IPv6 addresses must be valid hex notation with colons.\n"
                      "Examples: ::1, 2001:db8::1, fe80::1\n"
                      "Or use hostnames like example.com",
                      address);
        *error_msg = platform_strdup(msg);
      }
      return -1;
    }
  } else if (has_dot && starts_with_digit) {
    // Potential IPv4 address (has dots and starts with digit) - validate strictly
    if (!is_valid_ipv4(address)) {
      if (error_msg) {
        char msg[512];
        safe_snprintf(msg, sizeof(msg),
                      "Invalid IPv4 address '%s'.\n"
                      "IPv4 addresses must have exactly 4 octets (0-255) separated by dots.\n"
                      "Examples: 127.0.0.1, 192.168.1.1\n"
                      "For hostnames, use letters: example.com, localhost",
                      address);
        *error_msg = platform_strdup(msg);
      }
      return -1;
    }
  }
  // Otherwise treat as valid hostname (no validation needed)
 
  // Note: Port conflict checking would require additional state
  // (checking if --port flag was used). For now, this is a simplified version.
  // Full implementation would need to track whether port was set via flag.
 
  log_debug("parse_client_address: Set address='%s', port=%d", address[0] ? address : "(empty)", *port);
 
  return 1; // Consumed 1 arg
}

References is_session_string(), is_valid_ipv4(), is_valid_ipv6(), log_debug, OPTIONS_BUFF_SIZE, platform_strdup(), SAFE_SNPRINTF, safe_snprintf(), and SESSION_STRING_BUFFER_SIZE.

Referenced by options_preset_unified().

parse_color_filter()

bool parse_color_filter	(	const char *	arg,
		void *	dest,
		char **	error_msg
	)

Parse color filter option.

Parameters

arg	String argument (e.g., "green", "cyan", "pink")
dest	Destination pointer (color_filter_t*)
error_msg	Optional error message output (set on failure)

Returns

true on success, false on error

Valid values: none, black, white, green, magenta, fuchsia, orange, teal, cyan, pink, red, yellow

Definition at line 269 of file parsers.c.

                                                                       {
  if (!arg || !dest) {
    if (error_msg) {
      *error_msg = platform_strdup("Internal error: NULL argument or destination");
    }
    return false;
  }
 
  color_filter_t *color_filter = (color_filter_t *)dest;
  char lower[32];
  to_lower(arg, lower, sizeof(lower));
 
  // Try to match against all known color filters
  *color_filter = color_filter_from_cli_name(lower);
  if (*color_filter != COLOR_FILTER_NONE || strcmp(lower, OPT_COLOR_FILTER_NONE) == 0) {
    return true;
  }
 
  // Invalid value
  if (error_msg) {
    char msg[256];
    safe_snprintf(msg, sizeof(msg),
                  "Invalid color filter '%s'. Valid values: none, black, white, green, magenta, fuchsia, "
                  "orange, teal, cyan, pink, red, yellow",
                  arg);
    *error_msg = platform_strdup(msg);
  }
  return false;
}

References color_filter_from_cli_name(), COLOR_FILTER_NONE, OPT_COLOR_FILTER_NONE, platform_strdup(), and safe_snprintf().

parse_color_mode()

bool parse_color_mode	(	const char *	arg,
		void *	dest,
		char **	error_msg
	)

Parse terminal color level option.

Parameters

arg	String argument (e.g., "auto", "none", "16", "256", "truecolor")
dest	Destination pointer (terminal_color_mode_t*)
error_msg	Optional error message output (set on failure)

Returns

true on success, false on error

Valid values:

• "auto", "a" - Auto-detect from terminal
• "none", "mono", "monochrome", "0" - No color (TERM_COLOR_NONE)
• "16", "16color", "ansi" - 16-color mode (TERM_COLOR_16)
• "256", "256color" - 256-color mode (TERM_COLOR_256)
• "truecolor", "true", "tc", "rgb", "24bit" - Truecolor mode (TERM_COLOR_TRUECOLOR)

Definition at line 210 of file parsers.c.

                                                                     {
  if (!arg || !dest) {
    if (error_msg) {
      *error_msg = platform_strdup("Internal error: NULL argument or destination");
    }
    return false;
  }
 
  terminal_color_mode_t *color_mode = (terminal_color_mode_t *)dest;
  char lower[32];
  to_lower(arg, lower, sizeof(lower));
 
  // Auto-detect
  if (strcmp(lower, OPT_COLOR_MODE_AUTO) == 0 || strcmp(lower, "a") == 0) {
    *color_mode = TERM_COLOR_AUTO;
    return true;
  }
 
  // Monochrome/None
  if (strcmp(lower, OPT_COLOR_MODE_NONE) == 0 || strcmp(lower, "mono") == 0 || strcmp(lower, "monochrome") == 0 ||
      strcmp(lower, "0") == 0) {
    *color_mode = TERM_COLOR_NONE;
    return true;
  }
 
  // 16-color
  if (strcmp(lower, OPT_COLOR_MODE_16) == 0 || strcmp(lower, "16color") == 0 || strcmp(lower, "ansi") == 0 ||
      strcmp(lower, "1") == 0) {
    *color_mode = TERM_COLOR_16;
    return true;
  }
 
  // 256-color
  if (strcmp(lower, OPT_COLOR_MODE_256) == 0 || strcmp(lower, "256color") == 0 || strcmp(lower, "2") == 0) {
    *color_mode = TERM_COLOR_256;
    return true;
  }
 
  // Truecolor
  if (strcmp(lower, OPT_COLOR_MODE_TRUECOLOR) == 0 || strcmp(lower, "true") == 0 || strcmp(lower, "tc") == 0 ||
      strcmp(lower, "rgb") == 0 || strcmp(lower, "24bit") == 0 || strcmp(lower, "3") == 0) {
    *color_mode = TERM_COLOR_TRUECOLOR;
    return true;
  }
 
  // Invalid value - suggest closest match
  if (error_msg) {
    char msg[256];
    const char *suggestion = asciichat_suggest_enum_value("color-mode", arg);
    if (suggestion) {
      safe_snprintf(msg, sizeof(msg), "Invalid color mode '%s'. Did you mean '%s'?", arg, suggestion);
    } else {
      safe_snprintf(msg, sizeof(msg), "Invalid color mode '%s'. Valid values: auto, none, 16, 256, truecolor", arg);
    }
    *error_msg = platform_strdup(msg);
  }
  return false;
}

References asciichat_suggest_enum_value(), OPT_COLOR_MODE_16, OPT_COLOR_MODE_256, OPT_COLOR_MODE_AUTO, OPT_COLOR_MODE_NONE, OPT_COLOR_MODE_TRUECOLOR, platform_strdup(), safe_snprintf(), TERM_COLOR_16, TERM_COLOR_256, TERM_COLOR_AUTO, TERM_COLOR_NONE, and TERM_COLOR_TRUECOLOR.

parse_color_setting()

bool parse_color_setting	(	const char *	arg,
		void *	dest,
		char **	error_msg
	)

Parse color setting option (–color flag)

Parameters

arg	String argument (e.g., "auto", "true", "false")
dest	Destination pointer (int*, will store color_setting_t value)
error_msg	Optional error message output (set on failure)

Returns

true on success, false on error

Valid values:

• "auto", "a", "0" - Smart detection (COLOR_SETTING_AUTO, default)
• "true", "yes", "1", "on" - Force colors ON (COLOR_SETTING_TRUE)
• "false", "no", "-1", "off" - Force colors OFF (COLOR_SETTING_FALSE)

This controls whether colors are enabled ("auto"), always on ("true"), or always off ("false") regardless of TTY detection or environment variables.

Definition at line 160 of file parsers.c.

                                                                        {
  if (!dest) {
    if (error_msg) {
      *error_msg = platform_strdup("Internal error: NULL destination");
    }
    return false;
  }
 
  // Use generic parser with color setting lookup table
  // Default to TRUE if no arg provided
  if (!arg || arg[0] == '\0') {
    int *color_setting = (int *)dest;
    *color_setting = COLOR_SETTING_TRUE;
    return true;
  }
 
  return parse_setting_generic(arg, dest, g_color_setting_map, error_msg);
}

References COLOR_SETTING_TRUE, and platform_strdup().

Referenced by options_init().

parse_log_file()

bool parse_log_file	(	const char *	arg,
		void *	dest,
		char **	error_msg
	)

Custom parser for log file paths (–log-file, -L)

Validates that the log file path is safe:

• Rejects attempts to write to protected system directories (/etc, /System, /Windows, etc.)
• Allows overwriting existing ascii-chat log files
• Allows paths in safe locations (/tmp, /var/log, home directory, cwd, etc.)
• Returns error message if validation fails

Definition at line 1127 of file parsers.c.

                                                                   {
  if (!arg || !dest) {
    if (error_msg) {
      *error_msg = platform_strdup("Internal error: NULL argument or destination");
    }
    return false;
  }
 
  // Validate and normalize the log file path
  char *normalized = NULL;
  asciichat_error_t result = path_validate_user_path(arg, PATH_ROLE_LOG_FILE, &normalized);
 
  if (result != ASCIICHAT_OK) {
    if (error_msg) {
      asciichat_error_context_t err_ctx;
      if (HAS_ERRNO(&err_ctx)) {
        *error_msg = platform_strdup(err_ctx.context_message);
      } else {
        *error_msg = platform_strdup("Log file path validation failed");
      }
    }
    return false;
  }
 
  // Copy validated path to destination
  char *log_file_buf = (char *)dest;
  const size_t max_size = 256;
  SAFE_STRNCPY(log_file_buf, normalized, max_size - 1);
  log_file_buf[max_size - 1] = '\0';
 
  SAFE_FREE(normalized);
  return true;
}

References ASCIICHAT_OK, asciichat_error_context_t::context_message, HAS_ERRNO, PATH_ROLE_LOG_FILE, path_validate_user_path(), platform_strdup(), SAFE_FREE, and SAFE_STRNCPY.

parse_log_level()

bool parse_log_level	(	const char *	arg,
		void *	dest,
		char **	error_msg
	)

Parse log level option.

Parameters

arg	String argument (e.g., "debug", "info", "warn")
dest	Destination pointer (log_level_t*)
error_msg	Optional error message output (set on failure)

Returns

true on success, false on error

Valid values:

• "dev", "development", "0" - Development level (LOG_DEV)
• "debug", "dbg", "1" - Debug level (LOG_DEBUG)
• "info", "information", "2" - Info level (LOG_INFO)
• "warn", "warning", "3" - Warning level (LOG_WARN)
• "error", "err", "4" - Error level (LOG_ERROR)
• "fatal", "5" - Fatal level (LOG_FATAL)

Definition at line 448 of file parsers.c.

                                                                    {
  if (!dest) {
    if (error_msg) {
      *error_msg = platform_strdup("Internal error: NULL destination");
    }
    return false;
  }
 
  log_level_t *log_level = (log_level_t *)dest;
 
  // If no argument provided, use the default log level (based on build type)
  if (!arg || arg[0] == '\0') {
    *log_level = DEFAULT_LOG_LEVEL;
    return true;
  }
 
  char lower[32];
  to_lower(arg, lower, sizeof(lower));
 
  // Development level
  if (strcmp(lower, OPT_LOG_LEVEL_DEV) == 0 || strcmp(lower, "development") == 0 || strcmp(lower, "0") == 0) {
    *log_level = LOG_DEV;
    return true;
  }
 
  // Debug level
  if (strcmp(lower, OPT_LOG_LEVEL_DEBUG) == 0 || strcmp(lower, "dbg") == 0 || strcmp(lower, "1") == 0) {
    *log_level = LOG_DEBUG;
    return true;
  }
 
  // Info level
  if (strcmp(lower, OPT_LOG_LEVEL_INFO) == 0 || strcmp(lower, "information") == 0 || strcmp(lower, "2") == 0) {
    *log_level = LOG_INFO;
    return true;
  }
 
  // Warning level
  if (strcmp(lower, OPT_LOG_LEVEL_WARN) == 0 || strcmp(lower, "warning") == 0 || strcmp(lower, "3") == 0) {
    *log_level = LOG_WARN;
    return true;
  }
 
  // Error level
  if (strcmp(lower, OPT_LOG_LEVEL_ERROR) == 0 || strcmp(lower, "err") == 0 || strcmp(lower, "4") == 0) {
    *log_level = LOG_ERROR;
    return true;
  }
 
  // Fatal level
  if (strcmp(lower, OPT_LOG_LEVEL_FATAL) == 0 || strcmp(lower, "5") == 0) {
    *log_level = LOG_FATAL;
    return true;
  }
 
  // Invalid value
  if (error_msg) {
    char msg[256];
    safe_snprintf(msg, sizeof(msg), "Invalid log level '%s'. Valid values: dev, debug, info, warn, error, fatal", arg);
    *error_msg = platform_strdup(msg);
  }
  return false;
}

References DEFAULT_LOG_LEVEL, LOG_DEBUG, LOG_DEV, LOG_ERROR, LOG_FATAL, LOG_INFO, LOG_WARN, OPT_LOG_LEVEL_DEBUG, OPT_LOG_LEVEL_DEV, OPT_LOG_LEVEL_ERROR, OPT_LOG_LEVEL_FATAL, OPT_LOG_LEVEL_INFO, OPT_LOG_LEVEL_WARN, platform_strdup(), and safe_snprintf().

Referenced by options_init().

parse_mirror_media()

int parse_mirror_media	(	const char *	arg,
		void *	config,
		char **	remaining,
		int	num_remaining,
		char **	error_msg
	)

Parse mirror mode media positional argument.

Parameters

arg	File path or URL argument
config	Pointer to options struct (must contain media_file and media_url fields)
remaining	Remaining positional args (unused)
num_remaining	Count of remaining args
error_msg	Error message output (set on failure, caller must free)

Returns

1 if consumed the argument, -1 on error

Mirror mode media argument parsing rules:

• Cannot be used together with –file or –url flags (mutually exclusive)
• Attempts to access argument as a file path first (using platform_access)
• If file doesn't exist or isn't readable, treats as URL
• Sets either media_file or media_url field depending on what's detected

Example usage with options_builder_add_positional():

options_builder_add_positional(
    builder,
    "file|url",
    "(optional) Media file path or URL to stream",
    false,  // Not required (defaults to webcam)
    parse_mirror_media
);

Parse mirror mode media positional argument.

Logic:

1. Enforce mutual exclusion with –file and –url flags
2. Check if argument is an accessible file path first
3. If not a file, treat as URL (yt-dlp/ffmpeg will handle errors)
4. Set media_file or media_url accordingly

Definition at line 879 of file parsers.c.

                                                                                                             {
  (void)remaining;
  (void)num_remaining;
 
  if (!arg || !config) {
    if (error_msg) {
      *error_msg = platform_strdup("Internal error: NULL argument or config");
    }
    return -1;
  }
 
  log_debug("parse_mirror_media: Processing argument: '%s'", arg);
 
  // Access media_file and media_url fields from options_state struct (same as other positional parsers)
  char *media_file = (char *)config + offsetof(struct options_state, media_file);
  char *media_url = (char *)config + offsetof(struct options_state, media_url);
 
  // Enforce mutual exclusion with --file flag
  if (media_file[0] != '\0') {
    if (error_msg) {
      *error_msg = platform_strdup("cannot use both --file and a positional argument");
    }
    return -1;
  }
 
  // Enforce mutual exclusion with --url flag
  if (media_url[0] != '\0') {
    if (error_msg) {
      *error_msg = platform_strdup("cannot use both --url and a positional argument");
    }
    return -1;
  }
 
  // Check if it's an accessible file path (priority 1)
  if (platform_access(arg, PLATFORM_ACCESS_READ) == 0) {
    log_debug("Argument '%s' is an accessible file", arg);
    SAFE_SNPRINTF(media_file, OPTIONS_BUFF_SIZE, "%s", arg);
    return 1; // Consumed 1 argument
  }
 
  // Not a file; treat as URL (yt-dlp/ffmpeg will handle any errors)
  log_debug("Argument '%s' not found as file; treating as URL", arg);
  SAFE_SNPRINTF(media_url, OPTIONS_BUFF_SIZE, "%s", arg);
  return 1; // Consumed 1 argument
}

References log_debug, OPTIONS_BUFF_SIZE, platform_access(), PLATFORM_ACCESS_READ, platform_strdup(), and SAFE_SNPRINTF.

Referenced by options_preset_unified().

parse_palette_chars()

bool parse_palette_chars	(	const char *	arg,
		void *	dest,
		char **	error_msg
	)

Parse custom palette characters option.

Parameters

arg	String of characters ordered from darkest to brightest
dest	Destination pointer (char[256])
error_msg	Optional error message output (set on failure)

Returns

true on success, false on error

The characters should be ordered from darkest (leftmost) to brightest (rightmost). Maximum length is 255 characters.

Example: " .:-=+*#%@"

Definition at line 929 of file parsers.c.

                                                                        {
  if (!arg || !dest) {
    if (error_msg) {
      *error_msg = platform_strdup("Internal error: NULL argument or destination");
    }
    return false;
  }
 
  // The dest pointer points to the palette_custom field in options_t
  // We need to get the full options_t struct to call parse_palette_chars_option
  // Since we only have the field pointer, we need to handle this directly
 
  char *palette_custom = (char *)dest;
 
  size_t len = strlen(arg);
  if (len == 0) {
    if (error_msg) {
      *error_msg = platform_strdup("Invalid palette-chars: value cannot be empty");
    }
    return false;
  }
 
  if (len >= 256) {
    if (error_msg) {
      char msg[256];
      safe_snprintf(msg, sizeof(msg), "Invalid palette-chars: too long (%zu chars, max 255)", len);
      *error_msg = platform_strdup(msg);
    }
    return false;
  }
 
  // Copy the palette characters
  SAFE_STRNCPY(palette_custom, arg, 256);
  palette_custom[255] = '\0';
 
  // Also set the palette type to custom by calculating back to options_t pointer
  // dest points to options_t.palette_custom, so we can get options_t* using offset arithmetic
  options_t *opts = (options_t *)((char *)dest - offsetof(options_t, palette_custom));
  opts->palette_type = PALETTE_CUSTOM;
 
  return true;
}

References PALETTE_CUSTOM, options_state::palette_type, platform_strdup(), safe_snprintf(), and SAFE_STRNCPY.

parse_palette_type()

bool parse_palette_type	(	const char *	arg,
		void *	dest,
		char **	error_msg
	)

Parse palette type option.

Parameters

arg	String argument (e.g., "standard", "blocks", "custom")
dest	Destination pointer (palette_type_t*)
error_msg	Optional error message output (set on failure)

Returns

true on success, false on error

Valid values:

• "standard", "std", "0" - Standard palette (PALETTE_STANDARD)
• "blocks", "block", "1" - Blocks palette (PALETTE_BLOCKS)
• "digital", "dig", "2" - Digital palette (PALETTE_DIGITAL)
• "minimal", "min", "3" - Minimal palette (PALETTE_MINIMAL)
• "cool", "4" - Cool palette (PALETTE_COOL)
• "custom", "5" - Custom palette (PALETTE_CUSTOM)

Definition at line 385 of file parsers.c.

                                                                       {
  if (!arg || !dest) {
    if (error_msg) {
      *error_msg = platform_strdup("Internal error: NULL argument or destination");
    }
    return false;
  }
 
  palette_type_t *palette_type = (palette_type_t *)dest;
  char lower[32];
  to_lower(arg, lower, sizeof(lower));
 
  // Standard palette
  if (strcmp(lower, OPT_PALETTE_STANDARD) == 0 || strcmp(lower, "std") == 0 || strcmp(lower, "0") == 0) {
    *palette_type = PALETTE_STANDARD;
    return true;
  }
 
  // Blocks palette
  if (strcmp(lower, OPT_PALETTE_BLOCKS) == 0 || strcmp(lower, "block") == 0 || strcmp(lower, "1") == 0) {
    *palette_type = PALETTE_BLOCKS;
    return true;
  }
 
  // Digital palette
  if (strcmp(lower, OPT_PALETTE_DIGITAL) == 0 || strcmp(lower, "dig") == 0 || strcmp(lower, "2") == 0) {
    *palette_type = PALETTE_DIGITAL;
    return true;
  }
 
  // Minimal palette
  if (strcmp(lower, OPT_PALETTE_MINIMAL) == 0 || strcmp(lower, "min") == 0 || strcmp(lower, "3") == 0) {
    *palette_type = PALETTE_MINIMAL;
    return true;
  }
 
  // Cool palette
  if (strcmp(lower, OPT_PALETTE_COOL) == 0 || strcmp(lower, "4") == 0) {
    *palette_type = PALETTE_COOL;
    return true;
  }
 
  // Custom palette
  if (strcmp(lower, OPT_PALETTE_CUSTOM) == 0 || strcmp(lower, "5") == 0) {
    *palette_type = PALETTE_CUSTOM;
    return true;
  }
 
  // Invalid value - suggest closest match
  if (error_msg) {
    char msg[256];
    const char *suggestion = asciichat_suggest_enum_value("palette", arg);
    if (suggestion) {
      safe_snprintf(msg, sizeof(msg), "Invalid palette type '%s'. Did you mean '%s'?", arg, suggestion);
    } else {
      safe_snprintf(msg, sizeof(msg),
                    "Invalid palette type '%s'. Valid values: standard, blocks, digital, minimal, cool, custom", arg);
    }
    *error_msg = platform_strdup(msg);
  }
  return false;
}

References asciichat_suggest_enum_value(), 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, platform_strdup(), and safe_snprintf().

Referenced by set_palette().

parse_port_option()

bool parse_port_option	(	const char *	arg,
		void *	dest,
		char **	error_msg
	)

Parse and validate port option for CLI.

Parameters

arg	Port string to parse
dest	Destination pointer (int* for port storage)
error_msg	Error message output (set on failure, caller must free)

Returns

true on success, false on error

Validates port is a number in the range 1-65535.

Definition at line 512 of file parsers.c.

                                                                      {
  if (!arg || !dest) {
    if (error_msg) {
      *error_msg = platform_strdup("Internal error: NULL argument or destination");
    }
    return false;
  }
 
  int *port_value = (int *)dest;
  uint16_t port_num;
 
  // Use the existing parse_port function for validation
  asciichat_error_t err = parse_port(arg, &port_num);
  if (err != ASCIICHAT_OK) {
    if (error_msg) {
      char msg[256];
      safe_snprintf(msg, sizeof(msg), "Invalid port '%s'. Port must be a number between 0 and 65535 (0 = auto-assign).",
                    arg);
      *error_msg = platform_strdup(msg);
    }
    return false;
  }
 
  // Port zero is useful to low-level socket APIs for ephemeral binding, but
  // it is not a valid ascii-chat user-facing port and conflicts with the
  // option registry's 1-65535 contract.
  if (port_num == 0) {
    if (error_msg) {
      *error_msg = platform_strdup("Port must be between 1 and 65535");
    }
    return false;
  }
 
  *port_value = (int)port_num;
  return true;
}

References ASCIICHAT_OK, parse_port(), platform_strdup(), and safe_snprintf().

parse_render_mode()

bool parse_render_mode	(	const char *	arg,
		void *	dest,
		char **	error_msg
	)

Parse render mode option.

Parameters

arg	String argument (e.g., "foreground", "background", "half-block")
dest	Destination pointer (render_mode_t*)
error_msg	Optional error message output (set on failure)

Returns

true on success, false on error

Valid values:

• "foreground", "fg", "0" - Foreground mode (RENDER_MODE_FOREGROUND)
• "background", "bg", "1" - Background mode (RENDER_MODE_BACKGROUND)
• "half-block", "half", "hb", "2" - Half-block mode (RENDER_MODE_HALF_BLOCK)

Definition at line 299 of file parsers.c.

                                                                      {
  if (!arg || !dest) {
    if (error_msg) {
      *error_msg = platform_strdup("Internal error: NULL argument or destination");
    }
    return false;
  }
 
  render_mode_t *render_mode = (render_mode_t *)dest;
  char lower[32];
  to_lower(arg, lower, sizeof(lower));
 
  // Foreground mode
  if (strcmp(lower, OPT_RENDER_MODE_FOREGROUND) == 0 || strcmp(lower, OPT_RENDER_MODE_FG) == 0 ||
      strcmp(lower, "0") == 0) {
    *render_mode = RENDER_MODE_FOREGROUND;
    return true;
  }
 
  // Background mode
  if (strcmp(lower, OPT_RENDER_MODE_BACKGROUND) == 0 || strcmp(lower, OPT_RENDER_MODE_BG) == 0 ||
      strcmp(lower, "1") == 0) {
    *render_mode = RENDER_MODE_BACKGROUND;
    return true;
  }
 
  // Half-block mode
  if (strcmp(lower, OPT_RENDER_MODE_HALF_BLOCK) == 0 || strcmp(lower, "hb") == 0 || strcmp(lower, "2") == 0) {
    *render_mode = RENDER_MODE_HALF_BLOCK;
    return true;
  }
 
  // Invalid value - suggest closest match
  if (error_msg) {
    char msg[256];
    const char *suggestion = asciichat_suggest_enum_value("render-mode", arg);
    if (suggestion) {
      safe_snprintf(msg, sizeof(msg), "Invalid render mode '%s'. Did you mean '%s'?", arg, suggestion);
    } else {
      safe_snprintf(msg, sizeof(msg), "Invalid render mode '%s'. Valid values: foreground, background, half-block",
                    arg);
    }
    *error_msg = platform_strdup(msg);
  }
  return false;
}

References asciichat_suggest_enum_value(), OPT_RENDER_MODE_BACKGROUND, OPT_RENDER_MODE_BG, OPT_RENDER_MODE_FG, OPT_RENDER_MODE_FOREGROUND, OPT_RENDER_MODE_HALF_BLOCK, platform_strdup(), RENDER_MODE_BACKGROUND, RENDER_MODE_FOREGROUND, RENDER_MODE_HALF_BLOCK, and safe_snprintf().

parse_render_theme()

bool parse_render_theme	(	const char *	arg,
		void *	dest,
		char **	error_msg
	)

Parse render theme option for pixel rendering.

Parameters

arg	String argument (e.g., "dark", "light", "auto")
dest	Destination pointer (int*, will store term_renderer_theme_t value)
error_msg	Optional error message output (set on failure)

Returns

true on success, false on error

Controls the rendering theme when using pixel output. The theme determines color palette for ANSI text rendering.

Valid values:

• "dark", "0" - Dark theme: dark background, light text (TERM_RENDERER_THEME_DARK)
• "light", "1" - Light theme: light background, dark text (TERM_RENDERER_THEME_LIGHT)
• "auto", "2" - Auto-detect theme from terminal (TERM_RENDERER_THEME_AUTO, default)

Definition at line 346 of file parsers.c.

                                                                       {
  if (!arg || !dest) {
    if (error_msg) {
      *error_msg = platform_strdup("Internal error: NULL argument or destination");
    }
    return false;
  }
 
  int *theme = (int *)dest;
  char lower[32];
  to_lower(arg, lower, sizeof(lower));
 
  // Dark theme
  if (strcmp(lower, "dark") == 0 || strcmp(lower, "0") == 0) {
    *theme = 0; // TERM_RENDERER_THEME_DARK
    return true;
  }
 
  // Light theme
  if (strcmp(lower, "light") == 0 || strcmp(lower, "1") == 0) {
    *theme = 1; // TERM_RENDERER_THEME_LIGHT
    return true;
  }
 
  // Auto theme
  if (strcmp(lower, "auto") == 0 || strcmp(lower, "2") == 0) {
    *theme = 2; // TERM_RENDERER_THEME_AUTO
    return true;
  }
 
  // Invalid value
  if (error_msg) {
    char msg[256];
    safe_snprintf(msg, sizeof(msg), "Invalid render theme '%s'. Valid values: dark, light, auto", arg);
    *error_msg = platform_strdup(msg);
  }
  return false;
}

References platform_strdup(), and safe_snprintf().

parse_server_bind_address()

int parse_server_bind_address	(	const char *	arg,
		void *	config,
		char **	remaining,
		int	num_remaining,
		char **	error_msg
	)

Parse server bind address positional argument.

Parameters

arg	Current bind address argument
config	Pointer to options struct (must contain address/address6 fields)
remaining	Remaining positional args (for multi-arg parsing)
num_remaining	Count of remaining args
error_msg	Error message output (set on failure)

Returns

Number of args consumed (0-2), or -1 on error

Server bind address parsing rules:

• 0 args total: Uses defaults (127.0.0.1 + ::1 for dual-stack localhost)
• 1 arg: Single IPv4 OR IPv6 bind address
• 2 args: One IPv4 AND one IPv6 bind address (order-independent)
• Cannot specify multiple addresses of the same type
• IPv6 addresses can be wrapped in brackets (e.g., [::1])

This parser can consume 0-2 arguments depending on what's provided. It tracks internal state to ensure only one IPv4 and one IPv6 are specified.

Example usage with options_builder_add_positional():

options_builder_add_positional(
    builder,
    "bind-address",
    "IPv4 or IPv6 bind address (can specify 0-2 addresses)",
    false,  // Not required (defaults to localhost)
    parse_server_bind_address
);

Implements the server bind address parsing logic from server.c. Can consume 1 argument per call, handling IPv4 or IPv6 bind addresses. The positional arg system will call this multiple times for multiple args.

Definition at line 563 of file parsers.c.

                                                                                                                    {
  if (!arg || !config) {
    if (error_msg) {
      *error_msg = platform_strdup("Internal error: NULL argument or config");
    }
    return -1;
  }
 
  // Assume config struct has address and address6 fields (OPTIONS_BUFF_SIZE each)
  // This is a simplified version that assumes standard options_state layout
  char *address = (char *)config + offsetof(struct options_state, address);
  char *address6 = (char *)config + offsetof(struct options_state, address6);
 
  int consumed = 0;
 
  // Parse first argument (IPv4 or IPv6)
  char parsed_addr[OPTIONS_BUFF_SIZE];
  const char *addr_to_check = arg;
  if (parse_ipv6_address(arg, parsed_addr, sizeof(parsed_addr)) == 0) {
    addr_to_check = parsed_addr;
  }
 
  // Check if it's IPv4 or IPv6
  if (is_valid_ipv4(addr_to_check)) {
    // Check if we already have a non-default IPv4 address
    // Allow overwriting defaults (localhost, 0.0.0.0)
    if (address[0] != '\0' && !is_localhost_ipv4(address) && strcmp(address, "localhost") != 0 &&
        strcmp(address, "0.0.0.0") != 0) {
      if (error_msg) {
        char msg[256];
        safe_snprintf(msg, sizeof(msg),
                      "Cannot specify multiple IPv4 addresses.\n"
                      "Already have: %s\n"
                      "Cannot add: %s",
                      address, addr_to_check);
        *error_msg = platform_strdup(msg);
      }
      return -1;
    }
    SAFE_SNPRINTF(address, OPTIONS_BUFF_SIZE, "%s", addr_to_check);
    consumed = 1;
  } else if (is_valid_ipv6(addr_to_check)) {
    // Check if we already have a non-default IPv6 address
    // Allow overwriting default (::1)
    if (address6[0] != '\0' && !is_localhost_ipv6(address6)) {
      if (error_msg) {
        char msg[256];
        safe_snprintf(msg, sizeof(msg),
                      "Cannot specify multiple IPv6 addresses.\n"
                      "Already have: %s\n"
                      "Cannot add: %s",
                      address6, addr_to_check);
        *error_msg = platform_strdup(msg);
      }
      return -1;
    }
    SAFE_SNPRINTF(address6, OPTIONS_BUFF_SIZE, "%s", addr_to_check);
    consumed = 1;
  } else {
    if (error_msg) {
      char msg[512];
      safe_snprintf(msg, sizeof(msg),
                    "Invalid IP address '%s'.\n"
                    "Server bind addresses must be valid IPv4 or IPv6 addresses.\n"
                    "Examples:\n"
                    "  ascii-chat server 0.0.0.0\n"
                    "  ascii-chat server ::1\n"
                    "  ascii-chat server 0.0.0.0 ::1",
                    arg);
      *error_msg = platform_strdup(msg);
    }
    return -1;
  }
 
  // Try to parse second address if available
  if (remaining && num_remaining > 0 && remaining[0]) {
    const char *second_arg = remaining[0];
    memset(parsed_addr, 0, sizeof(parsed_addr));
    addr_to_check = second_arg;
    if (parse_ipv6_address(second_arg, parsed_addr, sizeof(parsed_addr)) == 0) {
      addr_to_check = parsed_addr;
    }
 
    if (is_valid_ipv4(addr_to_check)) {
      // Second is IPv4
      if (address[0] != '\0' && !is_localhost_ipv4(address) && strcmp(address, "localhost") != 0 &&
          strcmp(address, "0.0.0.0") != 0) {
        // Already have an IPv4, can't add another
        return consumed;
      }
      if (is_valid_ipv4(arg)) {
        // First was also IPv4, can't have two IPv4s
        return consumed;
      }
      // First was IPv6, second is IPv4 - accept both
      SAFE_SNPRINTF(address, OPTIONS_BUFF_SIZE, "%s", addr_to_check);
      consumed = 2;
    } else if (is_valid_ipv6(addr_to_check)) {
      // Second is IPv6
      if (address6[0] != '\0' && !is_localhost_ipv6(address6)) {
        // Already have an IPv6, can't add another
        return consumed;
      }
      if (is_valid_ipv6(arg)) {
        // First was also IPv6, can't have two IPv6s
        return consumed;
      }
      // First was IPv4, second is IPv6 - accept both
      SAFE_SNPRINTF(address6, OPTIONS_BUFF_SIZE, "%s", addr_to_check);
      consumed = 2;
    }
  }
 
  return consumed;
}

References is_localhost_ipv4(), is_localhost_ipv6(), is_valid_ipv4(), is_valid_ipv6(), OPTIONS_BUFF_SIZE, parse_ipv6_address(), platform_strdup(), SAFE_SNPRINTF, and safe_snprintf().

Referenced by options_preset_unified().

parse_timestamp()

bool parse_timestamp	(	const char *	arg,
		void *	dest,
		char **	error_msg
	)

Custom parser for –timestamp flag.

Allows –timestamp to work both as a flag with an argument. Sets media_seek_timestamp to the provided timestamp in seconds.

Custom parser for –timestamp flag.

Accepts both "hh:mm:ss.ms" format and plain seconds format. Examples:

• "30" = 30 seconds
• "30.5" = 30.5 seconds
• "1:30" = 1 minute 30 seconds (90 seconds)
• "1:30.5" = 1 minute 30.5 seconds (90.5 seconds)
• "0:1:30.5" = 1 minute 30.5 seconds (90.5 seconds)
• "1:2:30.5" = 1 hour 2 minutes 30.5 seconds (3750.5 seconds)

Definition at line 1010 of file parsers.c.

                                                                    {
  if (!arg || arg[0] == '\0') {
    if (error_msg) {
      *error_msg = platform_strdup("--seek requires a timestamp argument");
    }
    return false;
  }
 
  double *timestamp = (double *)dest;
  char *endptr;
  long strtol_result;
 
  // Count colons to determine format
  int colon_count = 0;
  for (const char *p = arg; *p; p++) {
    if (*p == ':')
      colon_count++;
  }
 
  if (colon_count == 0) {
    // Plain seconds format: "30" or "30.5"
    *timestamp = strtod(arg, &endptr);
    if (*endptr != '\0' || *timestamp < 0.0) {
      if (error_msg) {
        *error_msg = platform_strdup("Invalid timestamp: expected non-negative seconds");
      }
      return false;
    }
    return true;
  } else if (colon_count == 1) {
    // MM:SS or MM:SS.ms format
    strtol_result = strtol(arg, &endptr, 10);
    if (*endptr != ':' || strtol_result < 0) {
      if (error_msg) {
        *error_msg = platform_strdup("Invalid timestamp: expected MM:SS or MM:SS.ms format");
      }
      return false;
    }
    long minutes = strtol_result;
    double seconds = strtod(endptr + 1, &endptr);
    if (*endptr != '\0' && *endptr != '.' && *endptr != '\0') {
      if (error_msg) {
        *error_msg = platform_strdup("Invalid timestamp: expected MM:SS or MM:SS.ms format");
      }
      return false;
    }
    *timestamp = minutes * 60.0 + seconds;
    return true;
  } else if (colon_count == 2) {
    // HH:MM:SS or HH:MM:SS.ms format
    strtol_result = strtol(arg, &endptr, 10);
    if (*endptr != ':' || strtol_result < 0) {
      if (error_msg) {
        *error_msg = platform_strdup("Invalid timestamp: expected HH:MM:SS or HH:MM:SS.ms format");
      }
      return false;
    }
    long hours = strtol_result;
 
    strtol_result = strtol(endptr + 1, &endptr, 10);
    if (*endptr != ':' || strtol_result < 0 || strtol_result >= 60) {
      if (error_msg) {
        *error_msg = platform_strdup("Invalid timestamp: minutes must be 0-59");
      }
      return false;
    }
    long minutes = strtol_result;
 
    double seconds = strtod(endptr + 1, &endptr);
    if (*endptr != '\0') {
      if (error_msg) {
        *error_msg = platform_strdup("Invalid timestamp: expected HH:MM:SS or HH:MM:SS.ms format");
      }
      return false;
    }
    *timestamp = hours * (double)SEC_PER_HOUR + minutes * (double)SEC_PER_MIN + seconds;
    return true;
  } else {
    if (error_msg) {
      *error_msg = platform_strdup("Invalid timestamp format: too many colons");
    }
    return false;
  }
}

References platform_strdup(), SEC_PER_HOUR, and SEC_PER_MIN.

parse_utf8_setting()

bool parse_utf8_setting	(	const char *	arg,
		void *	dest,
		char **	error_msg
	)

Parse UTF-8 setting option (–utf8 flag)

Parameters

arg	String argument (e.g., "auto", "true", "false"), or NULL/empty for default
dest	Destination pointer (int*, will store utf8_setting_t value)
error_msg	Optional error message output (set on failure)

Returns

true on success, false on error

Valid values:

• "auto", "a", "0" - Smart detection (UTF8_SETTING_AUTO, default)
• "true", "yes", "1", "on" - Force UTF-8 ON (UTF8_SETTING_TRUE)
• "false", "no", "-1", "off" - Force UTF-8 OFF (UTF8_SETTING_FALSE)

When no argument is provided (–utf8 with no value), defaults to UTF8_SETTING_TRUE. This controls whether UTF-8 is auto-detected ("auto"), always on ("true"), or always off ("false") regardless of terminal capability detection.

Definition at line 191 of file parsers.c.

                                                                       {
  if (!dest) {
    if (error_msg) {
      *error_msg = platform_strdup("Internal error: NULL destination");
    }
    return false;
  }
 
  // Use generic parser with UTF-8 setting lookup table
  // Default to TRUE if no arg provided
  if (!arg || arg[0] == '\0') {
    int *utf8_setting = (int *)dest;
    *utf8_setting = UTF8_SETTING_TRUE;
    return true;
  }
 
  return parse_setting_generic(arg, dest, g_utf8_setting_map, error_msg);
}

References platform_strdup(), and UTF8_SETTING_TRUE.

parse_verbose_flag()

bool parse_verbose_flag	(	const char *	arg,
		void *	dest,
		char **	error_msg
	)

Custom parser for –verbose flag.

Allows –verbose to work both as a flag (without argument) and with an optional count argument. Increments verbose_level each time called.

Definition at line 972 of file parsers.c.

                                                                       {
  (void)error_msg; // Unused but required by function signature
 
  // If arg is NULL or starts with a flag, just increment
  // Otherwise try to parse as integer count
  unsigned short int *verbose_level = (unsigned short int *)dest;
 
  if (!arg || arg[0] == '\0') {
    // No argument provided, just increment
    (*verbose_level)++;
    return true;
  }
 
  // Try to parse as integer count
  char *endptr;
  long value = strtol(arg, &endptr, 10);
  if (*endptr == '\0' && value >= 0 && value <= 100) {
    *verbose_level = (unsigned short int)value;
    return true;
  }
 
  // If it didn't parse as int, treat as flag increment
  (*verbose_level)++;
  return true;
}

parse_volume()

bool parse_volume	(	const char *	arg,
		void *	dest,
		char **	error_msg
	)

Custom parser for volume options (–volume, –speakers-volume, –microphone-volume)

Validates that the volume is a float value between 0.0 and 1.0. Sets the destination float to the parsed volume value.

Definition at line 1095 of file parsers.c.

                                                                 {
  if (!arg || !dest) {
    if (error_msg) {
      *error_msg = platform_strdup("Internal error: NULL argument or destination");
    }
    return false;
  }
 
  float *volume = (float *)dest;
  char *endptr;
  float val = strtof(arg, &endptr);
 
  if (*endptr != '\0' || arg == endptr) {
    if (error_msg) {
      *error_msg = platform_strdup("Invalid volume value. Must be a number between 0.0 and 1.0");
    }
    return false;
  }
 
  if (val < 0.0f || val > 1.0f) {
    if (error_msg) {
      char buf[256];
      SAFE_SNPRINTF(buf, sizeof(buf), "Volume must be between 0.0 and 1.0 (got %.2f)", val);
      *error_msg = platform_strdup(buf);
    }
    return false;
  }
 
  *volume = val;
  return true;
}

References platform_strdup(), and SAFE_SNPRINTF.