first commit

docs/foundation/data/templates/src/utils/escape.md

@@ -0,0 +1,67 @@
+# escape
+
+## Purpose
+
+Provides three utility functions for handling escape sequences in template strings. These are low-level primitives used internally by the engine and exported for consumers who need to pre-process or post-process template content.
+
+The escape module is intentionally stateless and side-effect free — each function is a pure transformation of its input string with no I/O or global state.
+
+## Features
+
+- `escapeRegex(str)` — escapes all regex metacharacters for safe embedding in `RegExp` constructors.
+- `unescapeTemplate(str)` — removes backslash escapes from `\{` and `\}` sequences after rendering.
+- `isEscaped(str, pos)` — determines whether a character at a given position is preceded by an odd number of backslashes (i.e., is actually escaped).
+
+## Usage: Basic Example
+
+```ts
+import { escapeRegex, unescapeTemplate } from "@suaveplan/templates";
+
+const safe = escapeRegex("user.name"); // "user\\.name"
+const re = new RegExp(`\\{${safe}\\}`, "g");
+
+const result = unescapeTemplate("Say \\{hello\\}"); // "Say {hello}"
+```
+
+## Usage: Advanced Example
+
+```ts
+import { isEscaped, unescapeTemplate } from "@suaveplan/templates";
+
+// Custom pre-processing: skip escaped tokens
+function tokenize(template: string): string[] {
+    const tokens: string[] = [];
+    const re = /\{[^}]+\}/g;
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(template)) !== null) {
+        if (!isEscaped(template, m.index)) {
+            tokens.push(m[0]);
+        }
+    }
+    return tokens;
+}
+
+// After rendering, strip escape sequences
+const rendered = renderSomehow(template);
+const final = unescapeTemplate(rendered);
+```
+
+## API Reference
+
+### `escapeRegex(str: string): string`
+
+Escapes all characters that have special meaning in a regular expression: `. * + ? ^ $ { } ( ) | [ ] \`. Returns a string safe to pass to `new RegExp(str)`.
+
+### `unescapeTemplate(str: string): string`
+
+Replaces `\{` with `{` and `\}` with `}` throughout `str`. Other backslash sequences are left unchanged.
+
+### `isEscaped(str: string, pos: number): boolean`
+
+Returns `true` when the character at `pos` is preceded by an odd number of consecutive backslashes. An even count means the backslashes escape each other and the character at `pos` is not escaped.
+
+## Implementation Notes
+
+- `isEscaped` counts backslashes by walking backwards from `pos - 1` until a non-backslash character (or the start of the string) is found. The parity of the count determines whether the target character is escaped.
+- `unescapeTemplate` uses a single regex pass — O(n) regardless of the number of escape sequences.
+- `escapeRegex` uses the standard replace idiom which covers all metacharacters recognised by ECMAScript RegExp grammar.