Package dev.toonformat.jtoon.util

package dev.toonformat.jtoon.util
Utility classes for string validation, escaping, and shared constants.

Overview

This package provides low-level utility functions used throughout the JToon library. These classes handle string processing, validation rules, and shared constants.

Core Components

StringValidator

Validates whether strings and keys can be used unquoted in TOON format. Implements TOON's smart quoting rules to minimize token usage while avoiding ambiguity.

String Validation Rules:

Strings must be quoted if they:

  • Are empty
  • Have leading or trailing whitespace
  • Look like keywords (true, false, null)
  • Look like numbers (123, 3.14, 1e-6)
  • Contain special characters (colon, quotes, backslash)
  • Contain structural characters (brackets, braces)
  • Contain control characters (newline, tab, etc.)
  • Contain the active delimiter
  • Start with "- " (list marker)

Key Validation Rules:

Object keys can be unquoted if they match:

^[A-Z_][\\w.]*$

(Start with letter or underscore, contain only word characters and dots)

StringEscaper

Handles character escaping for quoted strings. Escapes special characters that would otherwise cause parsing issues:

  • \ → \\
  • " → \"
  • Newline → \n
  • Carriage return → \r
  • Tab → \t

Constants

Shared string constants used throughout the encoding process:

  • Structural: COLON, COMMA, SPACE, brackets, braces
  • Literals: NULL_LITERAL, TRUE_LITERAL, FALSE_LITERAL
  • List markers: LIST_ITEM_MARKER, LIST_ITEM_PREFIX
  • Escape characters: BACKSLASH, DOUBLE_QUOTE

Delimiter-Aware Validation

StringValidator implements delimiter-aware validation: strings containing the active delimiter must be quoted, while other delimiters are safe. This allows the same data to be encoded with different delimiters without unnecessary quoting.

Example:

// With comma delimiter
StringValidator.isSafeUnquoted("a,b", ",")  → false (must quote)
StringValidator.isSafeUnquoted("a|b", ",")  → true  (pipe is safe)

// With pipe delimiter
StringValidator.isSafeUnquoted("a,b", "|")  → true  (comma is safe)
StringValidator.isSafeUnquoted("a|b", "|")  → false (must quote)

Design Principles

Utility Class Pattern

All classes in this package follow the utility class pattern:

  • Final classes (cannot be extended)
  • Private constructors (cannot be instantiated)
  • Static methods only (no instance state)

Performance Optimization

  • Precompiled Patterns: Regex patterns compiled once at class load
  • Guard Clauses: Fast-fail checks before expensive operations
  • No Allocation: Methods operate on existing strings without copying

Thread Safety

All utility methods are stateless and thread-safe. Precompiled Pattern instances are immutable and safe to share across threads.

Testing

These utilities have comprehensive test coverage including:

  • StringEscaperTest: 62 tests covering all escape scenarios
  • StringValidatorTest: 48 tests covering all validation rules
Since:
0.1.0