![](\"https://raw.githubusercontent.com/prostojs/parser/main/docs/logo.png\"){kind=logo}
\n\n ![](\"https://img.shields.io/badge/License-MIT-cyan?style=for-the-badge\"){kind=icon}
\n\n\n\n\n
[\"'])/, omit: true },\n end: { token: (ctx) => ctx.node.data.quote, omit: true },\n data: { quote: '' },\n})\n\n// A key=value pair: key captured from regex, value from content\nconst pair = new Node<{ key: string; value: string }>({\n name: 'pair',\n start: { token: /(?\\w+)\\s*=\\s*/, omit: true },\n end: { token: /\\n|$/, omit: true },\n recognizes: [string],\n data: { key: '', value: '' },\n mapContent: 'value',\n})\n\n// Root: contains pairs, closes at EOF\nconst root = new Node({ name: 'root', eofClose: true, recognizes: [pair] })\n\nconst result = parse(root, 'name = \"Alice\"\\nage = \"30\"')\n// result.content → [ParsedNode{key:'name', value:'Alice'}, ...]\n```\n\nThat's a working config file parser. No grammar files, no build step, no code generation.\n\n## How It Works\n\n### 1. Define Nodes\n\nA node is a pattern with a start token, an end token, and typed data:\n\n```ts\nconst comment = new Node<{ text: string }>({\n name: 'comment',\n start: { token: '', omit: true },\n data: { text: '' },\n mapContent: 'text', // auto-joins text content into data.text\n})\n```\n\nTokens can be **strings**, **RegExps** (with named capture groups), or **dynamic functions**:\n\n```ts\n// String — exact match\nstart: '{'\n\n// RegExp — captures data automatically\nstart: { token: /<(? \\w+)/, omit: true }\n\n// Dynamic — computed from current node's data\nend: { token: (ctx) => ``, omit: true }\n```\n\nToken modifiers:\n- **`omit`** — strip the token from node content\n- **`eject`** — don't consume the match, let the parent handle it\n- **`backslash`** — ignore the token if preceded by `\\`\n\n### 2. Compose Them\n\nTell each node what children it can contain:\n\n```ts\nconst root = new Node({ name: 'root', eofClose: true })\nroot.recognize(comment, tag, cdata)\ntag.recognize(attribute, innerContent)\ninnerContent.recognize(comment, tag, cdata)\n```\n\nThat's your grammar. No separate DSL — it's just JavaScript.\n\n### 3. Add Hooks to Shape Output\n\nHooks fire during parsing — use them to build your output in its final format:\n\n```ts\ntag\n .onOpen((node, match) => {\n // start token matched — node.data is ready (named groups already mapped)\n // return false to reject this match\n })\n .onChild((child, node) => {\n // a child node was fully parsed\n // route its data wherever you need it\n if (child.node === attribute) {\n node.data.attrs[child.data.key] = child.data.value\n }\n })\n .onContent((text, node) => {\n // text is about to be added — transform or suppress it\n return text.trim()\n })\n .onClose((node) => {\n // end token matched — finalize the output\n })\n```\n\n### 4. Parse\n\n```ts\nimport { parse } from '@prostojs/parser'\n\nconst result = parse(root, sourceString)\n// result: ParsedNode with .content, .data, .start, .end\n```\n\n## Key Features\n\n### Named Group Auto-Mapping\n\nRegex named groups map directly to `data` fields — available *before* `onOpen` fires:\n\n```ts\nconst tag = new Node<{ tag: string }>({\n start: { token: /<(? \\w+)/ },\n data: { tag: '' },\n})\n.onOpen((node) => {\n console.log(node.data.tag) // already populated\n})\n```\n\n### Plain Data Templates\n\nNo factory functions. Just declare a plain object — it's auto-cloned per match with an optimized cloner:\n\n```ts\ndata: { tag: '', attrs: {}, children: [] }\n// primitives → spread clone\n// objects/arrays → shallow clone\n```\n\n### `mapContent`\n\nAuto-join all text content into a data field on node close. Replaces the most common `onClose` pattern:\n\n```ts\ndata: { text: '' },\nmapContent: 'text',\n// equivalent to: .onClose(node => { node.data.text = textContent(node) })\n```\n\n### Utilities\n\n```ts\nimport { textContent, children, findChild, findChildren, walk, printTree } from '@prostojs/parser'\n\ntextContent(node) // joined string content\nchildren(node) // child ParsedNodes (no strings)\nfindChild(node, targetNode) // first child of a specific node type\nfindChildren(node, targetNode) // all children of a specific node type\nwalk(node, (child, depth) => { ... }) // depth-first walk\nprintTree(node) // debug visualization\n```\n\n## Node Options Reference\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `name` | `string` | Identifier (for debugging / `printTree`) |\n| `start` | `TokenDef \\| TokenDef[]` | Start token(s) |\n| `end` | `TokenDef \\| TokenDef[]` | End token(s) |\n| `recognizes` | `Node[]` | Child nodes this node can contain |\n| `skip` | `Token \\| Token[]` | Tokens to silently skip (e.g. whitespace) |\n| `bad` | `Token \\| Token[]` | Tokens that trigger a parse error |\n| `eofClose` | `boolean` | Allow this node to close at end of input |\n| `data` | `T \\| () => T` | Data template (auto-cloned) or factory |\n| `mapContent` | `string` | Auto-join text content into this data field |\n| `hooks` | `NodeHooks ` | Inline hook definitions |\n\n## Error Handling\n\n```ts\nimport { ParseError } from '@prostojs/parser'\n\ntry {\n parse(root, source)\n} catch (e) {\n if (e instanceof ParseError) {\n console.log(e.message) // includes line, column, and context\n }\n}\n```\n\nThrows on unclosed nodes and bad tokens with precise source positions.\n\n## Examples\n\nEach example is a standalone parser showcasing different aspects of the API. All source is in the [examples/](https://github.com/prostojs/parser/tree/main/examples) directory on GitHub.\n\n| Example | What it parses | Highlights |\n|---------|---------------|------------|\n| [**XML-to-JSON**](https://github.com/prostojs/parser/tree/main/examples/xml-json) | Full XML → JSON (fast-xml-parser compatible) | Dynamic end tokens, hooks-based output, entity decoding, ~400 lines |\n| [**JSON**](https://github.com/prostojs/parser/tree/main/examples/json) | JSON strings → JS values | `onContent` for bare primitives, state tracking for key/value disambiguation |\n| [**Math Evaluator**](https://github.com/prostojs/parser/tree/main/examples/math-eval) | `2 + 3 * (4 - 1)` → `11` | Recursive `group` nodes, result computed during parsing — no AST |\n| [**Template String**](https://github.com/prostojs/parser/tree/main/examples/template-string) | `Hello, {{name}}!` → parts array | Minimal 2-node parser, `mapContent` for zero-hook data capture |\n| [**CSS Selector**](https://github.com/prostojs/parser/tree/main/examples/css-selector) | `div.cls > span:hover` → structured parts | Dynamic quote matching, regex tokenization in `onContent` |\n| [**URL Parser**](https://github.com/prostojs/parser/tree/main/examples/url-parser) | URLs → protocol/host/path/query/hash | Named group auto-mapping, `eject` for boundary detection |\n| [**ESM Analyzer**](https://github.com/prostojs/parser/tree/main/examples/esm-analyzer) | JS/TS source → imports, exports, unused | String/comment nodes as \"shields\" against false positives |\n\n## Migration from v0.5\n\nSee [MIGRATION.md](https://github.com/prostojs/parser/blob/main/MIGRATION.md) for a comprehensive guide.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}