com.vadelabs.toon.utils — com.vadelabs/toon 2025.12.01-36

Utility functions for TOON encoding and decoding.

Provides:

• String search and parsing utilities
• String escaping/unescaping
• Value and key quoting logic

closing-quote clj/s

(closing-quote s)

(closing-quote s start-pos)

Finds the position of the closing quote, respecting escapes.

Parameters:

• s: String to search (should start after opening quote)
• start-pos: Position to start searching (default 0)

Returns: Position of closing quote, or nil if not found

escaped clj/s

(escaped value)

Returns an escaped version of the string using JSON-style backslash escaping.

Single-pass implementation for performance.

Escape rules:

• Backslash → \
• Double quote → "
• Newline → \n
• Carriage return → \r
• Tab → \t

Parameters:

• value: String to escape

Returns: Escaped string.

Examples: (escaped "say "hi"") ;=> "say \"hi\"" (escaped "line1\nline2") ;=> "line1\nline2" (escaped "C:\path") ;=> "C:\\path"

has-structural-chars? clj/s

(has-structural-chars? value)

Returns true if value contains structural characters: [ ] { } -

identifier-segment? clj/s

(identifier-segment? segment)

Returns true if a key segment is a valid identifier for safe collapsing/expansion.

Identifier segments are more restrictive than unquoted keys:

• Must start with a letter (A-Z, a-z) or underscore (_)
• Followed only by letters, digits, or underscores (no dots or slashes)
• Used for safe key collapsing and path expansion

Parameters:

• segment: String segment to check

Returns: Boolean indicating if segment is a valid identifier.

Examples: (identifier-segment? "name") ;=> true (identifier-segment? "user_id") ;=> true (identifier-segment? "user123") ;=> true (identifier-segment? "user.name") ;=> false (contains dot) (identifier-segment? "user/id") ;=> false (contains slash) (identifier-segment? "user name") ;=> false (contains space) (identifier-segment? "123") ;=> false (starts with digit)

maybe-quote clj/s

(maybe-quote value)

(maybe-quote value delimiter)

Quotes a string if it needs quoting, otherwise returns it unchanged.

Parameters:

• value: String value to potentially quote
• delimiter: Delimiter character being used (default: comma)

Returns: Original or quoted string.

Examples: (maybe-quote "simple") ;=> "simple" (maybe-quote "has, comma") ;=> ""has, comma"" (maybe-quote "true") ;=> ""true"" (reserved literal) (maybe-quote "42") ;=> ""42"" (numeric-like)

maybe-quote-key clj/s

(maybe-quote-key key)

Quotes a key if it cannot be used unquoted, otherwise returns it unchanged.

Keys need quoting if they don't match the valid unquoted key pattern.

Parameters:

• key: String key to potentially quote

Returns: Original or quoted key.

Examples: (maybe-quote-key "name") ;=> "name" (maybe-quote-key "user name") ;=> ""user name"" (maybe-quote-key "123") ;=> ""123"" (maybe-quote-key "key:value") ;=> ""key:value""

needs-quoting? clj/s

(needs-quoting? value)

(needs-quoting? value delimiter)

Returns true if a string value needs quoting in TOON format.

A string needs quoting if it:

• Is empty or blank
• Has leading/trailing whitespace
• Exactly matches reserved literals: 'true', 'false', 'null'
• Looks like a number (e.g., '42', '-3.14', '1e-6', '05')
• Contains the active delimiter
• Contains structural characters: [ ] { } -
• Contains colon (key-value separator)
• Contains double quotes or backslashes
• Contains control characters (newline, tab, carriage return)

Parameters:

• value: String value to check
• delimiter: Delimiter character being used (default: comma)

Returns: Boolean indicating if quoting is needed.

numeric-like? clj/s

(numeric-like? value)

Returns true if value looks like a number.

Matches standard numeric patterns (42, -3.14, 1e-6) and leading zero patterns (05, 007).

unescaped clj/s

(unescaped s)

(unescaped s strict)

Unescapes a string literal.

Supported escape sequences:

• \ → \
• " → "
• \n → newline
• \r → carriage return
• \t → tab

In strict mode, throws on invalid escape sequences.

Parameters:

• s: String to unescape
• strict: Validate escape sequences (default true)

Returns: Unescaped string

Throws: ex-info if invalid escape sequence in strict mode

unquoted-char clj/s

(unquoted-char s target-char)

(unquoted-char s target-char start-pos)

Finds the first occurrence of a character outside quoted sections.

Parameters:

• s: String to search
• target-char: Character to find
• start-pos: Position to start searching (default 0)

Returns: Position of character, or nil if not found

valid-unquoted-key? clj/s

(valid-unquoted-key? key)

Returns true if a key can be used without quotes.

Valid unquoted keys must match the pattern: /^[A-Z_][\w./]*$/i

• Start with a letter (A-Z, a-z) or underscore (_)
• Followed by letters, digits, underscores, dots, or forward slashes

Note: Forward slashes are allowed to support Clojure namespaced keywords.

Parameters:

• key: String key to check

Returns: Boolean indicating if key can be unquoted.

Examples: (valid-unquoted-key? "name") ;=> true (valid-unquoted-key? "user_id") ;=> true (valid-unquoted-key? "user.name") ;=> true (valid-unquoted-key? "user/id") ;=> true (namespaced) (valid-unquoted-key? "user name") ;=> false (space) (valid-unquoted-key? "123") ;=> false (starts with digit) (valid-unquoted-key? "key:value") ;=> false (colon)

wrap clj/s

(wrap value)

Wraps a string value in double quotes for safe encoding in TOON format.

Quoting rules:

1. Escape special characters using JSON-style backslash escaping
2. Wrap result in double quotes

Parameters:

• value: String value to quote

Returns: Quoted string safe for TOON encoding.

Examples: (quoted "hello") ;=> ""hello"" (quoted "say "hi"") ;=> ""say \"hi\""" (quoted "a,b") ;=> ""a,b"" (quoted "line1\nline2") ;=> ""line1\nline2""