API reference
regexToSvg
(source, flags?) → string | null
One call from a regex source and optional flags to a standalone, themeable SVG string. Returns null when the regex fails to parse or has a semantic issue (e.g. a never-matching assertion or an empty character class).
parseRegex
(source, flags?) → ParseResult
Parses the source to a regexpp AST and validates it. The result carries
ok, the ast (null on failure) and an issues array covering both syntax errors and semantic problems.lintRegex
(source, flags?) → RegexIssue[]
Runs only the semantic checks and returns the issues array — never-matching assertions, empty character classes and the like. Empty for a clean regex.
explainRegex
(source, flags?) → ExplainItem[] | null
Returns a flat list of steps, each with its depth, syntax category, token slice and a plain-language description. Null when the regex is invalid.
formatExplain
(desc, messages?) → string
Renders one ExplainDesc to a string using a message table. Pass a partial table to localize — any key you omit falls back to the built-in English (see the Localization page).
buildDiagram
(ast) → Diagram
Lays out a parsed AST into a positioned railroad-diagram model with coordinates, ready to render.
renderToSvg
(diagram, flags?) → string
Renders a diagram model to a self-contained SVG string; pass the flags to show them after the pattern.
sourceColors
(source, flags?) → Array<SyntaxCategory | null> | null
Returns the syntax category of each source character (or null), for highlighting the raw pattern text.
sourceRanges
(source, flags?) → Array<[number, number] | null> | null
Returns, per source character, the start and end offsets of the smallest diagram node covering it — used to sync caret and hover with the diagram.
toRegexLiteral
(source, flags?) → string
Assembles a valid regex literal from a source and flags, escaping slashes and handling the empty pattern.
Types
// Returned in parseRegex().issues and by lintRegex()
interface RegexIssue {
rule?: 'assertionNeverMatches' | 'emptyCharClass' // stable id; absent for syntax errors
message: string // human-readable (the parser's text for syntax errors)
start?: number // pattern offsets of the offending token, when known
end?: number
}
// One line of explainRegex()
interface ExplainItem {
depth: number // nesting level, for indentation
cat: SyntaxCategory // the token's syntax category (drives the shared color)
token: string // the source slice this line describes
desc: ExplainDesc // language-neutral description — render this to localize
text: string // English rendering of desc, for zero-config use
start?: number
end?: number
}
// Color-category keys — also the --rr-syntax-* variable suffixes
type SyntaxCategory =
| 'literal' | 'charset' | 'class' | 'anchor' | 'quantifier'
| 'group' | 'lookaround' | 'backref' | 'alternation'