parsers.h File Reference

Custom option parsers for enum types. More...

Go to the source code of this file.

Functions
bool	parse_color_mode (const char *arg, void *dest, char **error_msg)
	Parse terminal color level option.
bool	parse_render_mode (const char *arg, void *dest, char **error_msg)
	Parse render mode option.
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.
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.

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_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 393 of file parsers.c.

                                                                                                               {
  (void)remaining;
  (void)num_remaining;
 
  if (!arg || !config) {
    if (error_msg) {
      *error_msg = strdup("Internal error: NULL argument or config");
    }
    return -1;
  }
 
  // Check if this is a session string (format: adjective-noun-noun)
  // Session strings have exactly 2 hyphens, only lowercase letters, length 1-47
  if (is_session_string(arg)) {
    // This is a session string, not a server address
    char *session_string = (char *)config + offsetof(struct options_state, session_string);
    SAFE_SNPRINTF(session_string, 64, "%s", arg);
    log_debug("Detected session string: %s", arg);
    return 1; // Consumed 1 arg
  }
 
  // Not a session string, parse as server address
  // Access address and port fields from options_state struct
  char *address = (char *)config + offsetof(struct options_state, address);
  char *port = (char *)config + offsetof(struct options_state, port);
 
  // 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 = 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 = SAFE_MALLOC(256, char *);
            if (msg) {
              snprintf(msg, 256, "Invalid port number '%s'. Must be 1-65535.", port_str);
              *error_msg = msg;
            }
          }
          return -1;
        }
        SAFE_SNPRINTF(port, OPTIONS_BUFF_SIZE, "%s", port_str);
      }
    } 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 = 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 = SAFE_MALLOC(256, char *);
            if (msg) {
              snprintf(msg, 256, "Invalid port number '%s'. Must be 1-65535.", port_str);
              *error_msg = msg;
            }
          }
          return -1;
        }
        SAFE_SNPRINTF(port, OPTIONS_BUFF_SIZE, "%s", port_str);
      } 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 that contain dots as potential IPv4 addresses
  // If it has a dot, it's either a valid IPv4 or a hostname with domain
  bool has_dot = strchr(address, '.') != NULL;
  bool starts_with_digit = address[0] >= '0' && address[0] <= '9';
 
  if (has_dot && starts_with_digit) {
    // Looks like an IPv4 attempt - validate strictly
    if (!is_valid_ipv4(address)) {
      if (error_msg) {
        char *msg = SAFE_MALLOC(512, char *);
        if (msg) {
          snprintf(msg, 512,
                   "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 = msg;
        }
      }
      return -1;
    }
  }
 
  // 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.
 
  return 1; // Consumed 1 arg
}

References is_session_string(), is_valid_ipv4(), log_debug, OPTIONS_BUFF_SIZE, SAFE_MALLOC, and SAFE_SNPRINTF.

Referenced by options_preset_client().

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 75 of file parsers.c.

                                                                     {
  if (!arg || !dest) {
    if (error_msg) {
      *error_msg = 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, "auto") == 0 || strcmp(lower, "a") == 0) {
    *color_mode = TERM_COLOR_AUTO;
    return true;
  }
 
  // Monochrome/None
  if (strcmp(lower, "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, "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, "256") == 0 || strcmp(lower, "256color") == 0 || strcmp(lower, "2") == 0) {
    *color_mode = TERM_COLOR_256;
    return true;
  }
 
  // Truecolor
  if (strcmp(lower, "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
  if (error_msg) {
    char *msg = SAFE_MALLOC(256, char *);
    if (msg) {
      snprintf(msg, 256, "Invalid color mode '%s'. Valid values: auto, none, 16, 256, truecolor", arg);
      *error_msg = msg;
    }
  }
  return false;
}

References SAFE_MALLOC, TERM_COLOR_16, TERM_COLOR_256, TERM_COLOR_AUTO, TERM_COLOR_NONE, and TERM_COLOR_TRUECOLOR.

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 233 of file parsers.c.

                                                                    {
  if (!arg || !dest) {
    if (error_msg) {
      *error_msg = strdup("Internal error: NULL argument or destination");
    }
    return false;
  }
 
  log_level_t *log_level = (log_level_t *)dest;
  char lower[32];
  to_lower(arg, lower, sizeof(lower));
 
  // Development level
  if (strcmp(lower, "dev") == 0 || strcmp(lower, "development") == 0 || strcmp(lower, "0") == 0) {
    *log_level = LOG_DEV;
    return true;
  }
 
  // Debug level
  if (strcmp(lower, "debug") == 0 || strcmp(lower, "dbg") == 0 || strcmp(lower, "1") == 0) {
    *log_level = LOG_DEBUG;
    return true;
  }
 
  // Info level
  if (strcmp(lower, "info") == 0 || strcmp(lower, "information") == 0 || strcmp(lower, "2") == 0) {
    *log_level = LOG_INFO;
    return true;
  }
 
  // Warning level
  if (strcmp(lower, "warn") == 0 || strcmp(lower, "warning") == 0 || strcmp(lower, "3") == 0) {
    *log_level = LOG_WARN;
    return true;
  }
 
  // Error level
  if (strcmp(lower, "error") == 0 || strcmp(lower, "err") == 0 || strcmp(lower, "4") == 0) {
    *log_level = LOG_ERROR;
    return true;
  }
 
  // Fatal level
  if (strcmp(lower, "fatal") == 0 || strcmp(lower, "5") == 0) {
    *log_level = LOG_FATAL;
    return true;
  }
 
  // Invalid value
  if (error_msg) {
    char *msg = SAFE_MALLOC(256, char *);
    if (msg) {
      snprintf(msg, 256, "Invalid log level '%s'. Valid values: dev, debug, info, warn, error, fatal", arg);
      *error_msg = msg;
    }
  }
  return false;
}

References LOG_DEBUG, LOG_DEV, LOG_ERROR, LOG_FATAL, LOG_INFO, LOG_WARN, and SAFE_MALLOC.

Referenced by options_preset_acds().

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 534 of file parsers.c.

                                                                        {
  if (!arg || !dest) {
    if (error_msg) {
      *error_msg = 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;
 
  if (strlen(arg) >= 256) {
    if (error_msg) {
      char *msg = SAFE_MALLOC(256, char *);
      if (msg) {
        snprintf(msg, 256, "Invalid palette-chars: too long (%zu chars, max 255)", strlen(arg));
        *error_msg = msg;
      }
    }
    return false;
  }
 
  // Copy the palette characters
  SAFE_STRNCPY(palette_custom, arg, 256);
  palette_custom[255] = '\0';
 
  // Also set the palette type to custom
  // Note: This is a simplification - ideally we'd have access to the full options_t struct
  // to set palette_custom_set and palette_type, but the callback interface doesn't provide that.
  // The palette_type should be handled separately or via a dependency.
 
  return true;
}

References SAFE_MALLOC, 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 173 of file parsers.c.

                                                                       {
  if (!arg || !dest) {
    if (error_msg) {
      *error_msg = 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, "standard") == 0 || strcmp(lower, "std") == 0 || strcmp(lower, "0") == 0) {
    *palette_type = PALETTE_STANDARD;
    return true;
  }
 
  // Blocks palette
  if (strcmp(lower, "blocks") == 0 || strcmp(lower, "block") == 0 || strcmp(lower, "1") == 0) {
    *palette_type = PALETTE_BLOCKS;
    return true;
  }
 
  // Digital palette
  if (strcmp(lower, "digital") == 0 || strcmp(lower, "dig") == 0 || strcmp(lower, "2") == 0) {
    *palette_type = PALETTE_DIGITAL;
    return true;
  }
 
  // Minimal palette
  if (strcmp(lower, "minimal") == 0 || strcmp(lower, "min") == 0 || strcmp(lower, "3") == 0) {
    *palette_type = PALETTE_MINIMAL;
    return true;
  }
 
  // Cool palette
  if (strcmp(lower, "cool") == 0 || strcmp(lower, "4") == 0) {
    *palette_type = PALETTE_COOL;
    return true;
  }
 
  // Custom palette
  if (strcmp(lower, "custom") == 0 || strcmp(lower, "5") == 0) {
    *palette_type = PALETTE_CUSTOM;
    return true;
  }
 
  // Invalid value
  if (error_msg) {
    char *msg = SAFE_MALLOC(256, char *);
    if (msg) {
      snprintf(msg, 256, "Invalid palette type '%s'. Valid values: standard, blocks, digital, minimal, cool, custom",
               arg);
      *error_msg = msg;
    }
  }
  return false;
}

References PALETTE_BLOCKS, PALETTE_COOL, PALETTE_CUSTOM, PALETTE_DIGITAL, PALETTE_MINIMAL, PALETTE_STANDARD, and SAFE_MALLOC.

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 131 of file parsers.c.

                                                                      {
  if (!arg || !dest) {
    if (error_msg) {
      *error_msg = 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, "foreground") == 0 || strcmp(lower, "fg") == 0 || strcmp(lower, "0") == 0) {
    *render_mode = RENDER_MODE_FOREGROUND;
    return true;
  }
 
  // Background mode
  if (strcmp(lower, "background") == 0 || strcmp(lower, "bg") == 0 || strcmp(lower, "1") == 0) {
    *render_mode = RENDER_MODE_BACKGROUND;
    return true;
  }
 
  // Half-block mode
  if (strcmp(lower, "half-block") == 0 || strcmp(lower, "half") == 0 || strcmp(lower, "hb") == 0 ||
      strcmp(lower, "2") == 0) {
    *render_mode = RENDER_MODE_HALF_BLOCK;
    return true;
  }
 
  // Invalid value
  if (error_msg) {
    char *msg = SAFE_MALLOC(256, char *);
    if (msg) {
      snprintf(msg, 256, "Invalid render mode '%s'. Valid values: foreground, background, half-block", arg);
      *error_msg = msg;
    }
  }
  return false;
}

References RENDER_MODE_BACKGROUND, RENDER_MODE_FOREGROUND, RENDER_MODE_HALF_BLOCK, and SAFE_MALLOC.

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 306 of file parsers.c.

                                                                                                                    {
  (void)remaining; // Unused - we consume one arg at a time
  (void)num_remaining;
 
  if (!arg || !config) {
    if (error_msg) {
      *error_msg = 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);
 
  // Parse IPv6 address (remove brackets if present)
  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 (127.0.0.1, localhost)
    if (address[0] != '\0' && strcmp(address, "127.0.0.1") != 0 && strcmp(address, "localhost") != 0) {
      if (error_msg) {
        char *msg = SAFE_MALLOC(256, char *);
        if (msg) {
          snprintf(msg, 256,
                   "Cannot specify multiple IPv4 addresses.\n"
                   "Already have: %s\n"
                   "Cannot add: %s",
                   address, addr_to_check);
          *error_msg = msg;
        }
      }
      return -1;
    }
    SAFE_SNPRINTF(address, OPTIONS_BUFF_SIZE, "%s", addr_to_check);
    return 1; // Consumed 1 arg
  } 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' && strcmp(address6, "::1") != 0) {
      if (error_msg) {
        char *msg = SAFE_MALLOC(256, char *);
        if (msg) {
          snprintf(msg, 256,
                   "Cannot specify multiple IPv6 addresses.\n"
                   "Already have: %s\n"
                   "Cannot add: %s",
                   address6, addr_to_check);
          *error_msg = msg;
        }
      }
      return -1;
    }
    SAFE_SNPRINTF(address6, OPTIONS_BUFF_SIZE, "%s", addr_to_check);
    return 1; // Consumed 1 arg
  } else {
    if (error_msg) {
      char *msg = SAFE_MALLOC(512, char *);
      if (msg) {
        snprintf(msg, 512,
                 "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 = msg;
      }
    }
    return -1;
  }
}

References is_valid_ipv4(), is_valid_ipv6(), OPTIONS_BUFF_SIZE, parse_ipv6_address(), SAFE_MALLOC, and SAFE_SNPRINTF.

Referenced by options_preset_acds(), and options_preset_server().