Function: splitEscapeAware()

splitEscapeAware(text, delimiter, escape): string[]

Split text on delimiter, treating an escape sequence (escape, one body character, escape) as an opaque atom so a delimiter that appears inside an escape body never causes a split. Returns the raw (still-encoded) segments: decoding is the caller's next step, per the escape-aware-split-then-decode contract.

For the four canonical mnemonics the opacity is belt-and-suspenders (their bodies are letters, not delimiters), but it makes the "an escaped delimiter is one token" guarantee hold for any declared delimiter set, including adversarial input. A single body character is all that guarantee needs.

An escape character that heads no sequence is not an escape: it is ordinary text, and it opens no atom. Reading it as the opening of a sequence that never closes is what used to merge the whole remainder of a record into one field. Decoding the resulting leaf is what reports it, so this function stays a pure split. Note the two rules together: a delimiter after such a character does split, and a delimiter sitting inside a real three-character atom does not.

Parameters

text

string

The field or repeat string to split.

delimiter

string

The delimiter to split on.

escape

string

The active escape character.

Returns

string[]

The raw segments, in order.

Example

import { splitEscapeAware } from "@cosyte/astm";
splitEscapeAware("a^b^c", "^", "&"); // ["a", "b", "c"]
splitEscapeAware("1&S&40", "^", "&"); // ["1&S&40"]  (escape body is opaque)
splitEscapeAware("O&Brien^John", "^", "&"); // ["O&Brien", "John"]  (unpaired: literal)