59 lines
2.9 KiB
Markdown
59 lines
2.9 KiB
Markdown
# Pattern formatting
|
|
|
|
Regex Tools includes a deliberately narrow, local ECMAScript formatter. It
|
|
canonicalizes representations that can be changed without inventing a visual
|
|
layout:
|
|
|
|
- an unescaped literal `/` becomes `\/`, making the pattern safe to copy into
|
|
an ECMAScript regex literal;
|
|
- raw NUL and control code units become fixed-width `\xNN` or their canonical
|
|
short escape (`\t`, `\n`, `\v`, `\f`, `\r`);
|
|
- raw U+2028 and U+2029 line separators become `\u2028` and `\u2029`;
|
|
- legacy escaped raw controls are replaced as one parser-reported literal
|
|
token, so the formatter does not introduce an extra backslash.
|
|
|
|
Existing explicit escape spellings, groups, alternatives, quantifiers, inline
|
|
flags and literal whitespace are otherwise preserved byte for byte. ECMAScript
|
|
regex whitespace is normally significant, so the tool does not insert
|
|
indentation, line breaks or comments and does not claim to be a structural
|
|
pretty-printer. The transform is idempotent.
|
|
|
|
## Eligibility
|
|
|
|
Formatting requires the exact current, accepted, non-recovered syntax snapshot
|
|
from the bundled `@eslint-community/regexpp` provider. Transformations are
|
|
derived from the provider's literal-token ranges rather than from a heuristic
|
|
text scan. A stale parse, a malformed pattern, a partial provider, PCRE2,
|
|
Python, Java or any other flavour is reported as unavailable and is never
|
|
silently rewritten.
|
|
|
|
## Mandatory validation before apply
|
|
|
|
The preview cannot be applied directly. Regex Tools first:
|
|
|
|
1. reparses source and candidate independently and checks capture numbering,
|
|
names, repetition and parent-capture shape;
|
|
2. compiles and runs the source and candidate in separate actual ECMAScript
|
|
engine workers against the current subject and replacement;
|
|
3. compares exact normalized match, capture and replacement output, including
|
|
the engine identity;
|
|
4. reruns every enabled unit test whose flavour, version, pattern, flags and
|
|
engine options exactly match the active source snapshot, and compares both
|
|
semantic output and assertion outcome.
|
|
|
|
A compile rejection, one-sided timeout, crash, worker error, cancellation,
|
|
truncated result, engine-identity change, incomplete test suite or semantic
|
|
difference blocks application. Matching fixed timeouts are comparable only for
|
|
an exact unit-test pair; two timeouts on the current interactive snapshot are
|
|
inconclusive. If no unit test is applicable, the UI says so and still requires
|
|
the current subject/replacement gate.
|
|
|
|
Validation is bounded to 1,000 tests, the normal worker/input limits and a
|
|
60-second aggregate test wall budget. A test is not started unless its complete
|
|
configured timeout still fits that budget. The user must explicitly confirm
|
|
the exact validated candidate before the Apply button is enabled.
|
|
|
|
Passing these gates is strong, reproducible evidence for the current snapshot
|
|
and exact tests. It is not a mathematical proof of equivalence for every
|
|
possible subject.
|