Parsing Library for Typescript and Javascript.
npm install clarity-pattern-parserA powerful pattern matching and parsing library that provides a flexible grammar for defining complex patterns. Perfect for building parsers, validators, and text processing tools.
> Try it online! 🚀 Open in Playground
- 🎯 Flexible pattern matching with both grammar and direct API
- 🔄 Support for recursive patterns and expressions
- 🎨 Customizable pattern composition
- 🚀 High performance parsing
- 🔍 Built-in debugging support
- 📝 Rich AST manipulation capabilities
- 🔌 Extensible through custom patterns and decorators
``bash`
npm install clarity-pattern-parser
`typescript
import { patterns } from "clarity-pattern-parser";
// Define patterns using grammar
const { fullName } = patterns
first-name = "John"
last-name = "Doe"
space = /\s+/
full-name = first-name + space + last-name;
// Execute pattern
const result = fullName.exec("John Doe");
console.log(result.ast?.value); // "John Doe"
`
`typescript
import { Literal, Sequence } from "clarity-pattern-parser";
// Create patterns directly
const firstName = new Literal("first-name", "John");
const space = new Literal("space", " ");
const lastName = new Literal("last-name", "Doe");
const fullName = new Sequence("full-name", [firstName, space, lastName]);
// Execute pattern
const result = fullName.exec("John Doe");
console.log(result.ast?.value); // "John Doe"
`
Try Clarity Pattern Parser in your browser with our interactive playground:
The playground allows you to:
- Write and test patterns in real-time
- See the AST visualization
- Debug pattern execution
- Share patterns with others
- Try out different examples
1. Grammar Documentation
- Basic Patterns
- Pattern Operators
- Repetition
- Imports and Parameters
- Decorators
- Comments
- Pattern References
- Pattern Aliasing
- String Template Patterns
2. Direct Pattern Usage
- Basic Patterns
- Composite Patterns
- Pattern Context
- Pattern Reference
- Pattern Execution
- AST Manipulation
3. Advanced Topics
- Custom Patterns
- Performance Tips
- Debugging
- Error Handling
This document describes the grammar features supported by the Clarity Pattern Parser.
#### Literal Strings
Define literal string patterns using double quotes:
``
name = "John"
Escaped characters are supported in literals:
- \n - newline\r
- - carriage return\t
- - tab\b
- - backspace\f
- - form feed\v
- - vertical tab\0
- - null character\x00
- - hex character\u0000
- - unicode character\"
- - escaped quote\\
- - escaped backslash
#### Regular Expressions
Define regex patterns using forward slashes:
``
name = /\w/
#### Options (|)
Match one of multiple patterns using the | operator. This is used for simple alternatives where order doesn't matter:``
names = john | jane
#### Expression (|)
Expression patterns also use the | operator but are used for defining operator precedence in expressions. The order of alternatives determines precedence, with earlier alternatives having higher precedence. By default, operators are left-associative.
Example of an arithmetic expression grammar:
``
prefix-operators = "+" | "-"
prefix-expression = prefix-operators + expression
postfix-operators = "++" | "--"
postfix-expression = expression + postfix-operators
add-sub-operators = "+" | "-"
add-sub-expression = expression + add-sub-operators + expression
mul-div-operators = "*" | "/"
mul-div-expression = expression + mul-div-operators + expression
expression = prefix-expression | mul-div-expression | add-sub-expression | postfix-expression
#### Basic Repeat
Repeat a pattern one or more times using +:``
digits = (digit)+
#### Zero or More
Repeat a pattern zero or more times using *:``
digits = (digit)*
#### Bounded Repetition
Specify exact repetition counts using curly braces:
- {n} - Exactly n times: (pattern){3}{n,}
- - At least n times: (pattern){1,}{,n}
- - At most n times: (pattern){,3}{n,m}
- - Between n and m times: (pattern){1,3}
#### Repetition with Divider
Repeat patterns with a divider between occurrences:
``
digits = (digit, comma){3}
Add trim keyword to trim the divider from the end:``
digits = (digit, comma trim)+
#### Basic Import
Import patterns from other files:
``
import { pattern-name } from "path/to/file.cpat"
#### Import with Parameters
Import with custom parameters:
``
import { pattern } from "file.cpat" with params {
custom-param = "value"
}
#### Parameter Declaration
Declare parameters that can be passed to the grammar:
``
use params {
param-name
}
#### Default Parameters
Specify default values for parameters:
``
use params {
param = default-value
}
#### Token Decorator
Specify tokens for a pattern:
``
@tokens([" "])
spaces = /\s+/
#### Custom Decorators
Support for custom decorators with various argument types:
``
@decorator() // No arguments
@decorator(["value"]) // Array argument
@decorator({"prop": value}) // Object argument
symbol:
`
This is a comment
pattern = "value"
`$3
Reference other patterns by name:
`
pattern1 = "value"
pattern2 = pattern1
`$3
Import patterns with aliases:
`
import { original as alias } from "file.cpat"
`$3
Patterns can be defined inline using string templates. This allows for quick pattern definition and testing without creating separate files.
#### Basic Example
`typescript
const { fullName } = patterns;const result = fullName.exec("John Doe");
// result.ast.value will be "John Doe"
`#### Complex Example (HTML-like Markup)
`typescript
const { body } = patterns;const result = body.exec(
, true);// Clean up spaces from the AST
result?.ast?.findAll(n => n.name.includes("ws")).forEach(n => n.remove());
// result.ast.value will be "
"
`Direct Pattern Usage
While the grammar provides a convenient way to define patterns, you can also use the Pattern classes directly for more control and flexibility.
$3
#### Literal
`typescript
import { Literal } from "clarity-pattern-parser";const firstName = new Literal("first-name", "John");
const result = firstName.exec("John");
// result.ast.value will be "John"
`#### Regex
`typescript
import { Regex } from "clarity-pattern-parser";const digits = new Regex("digits", "\\d+");
const result = digits.exec("123");
// result.ast.value will be "123"
`$3
#### Sequence
`typescript
import { Sequence, Literal } from "clarity-pattern-parser";const firstName = new Literal("first-name", "John");
const space = new Literal("space", " ");
const lastName = new Literal("last-name", "Doe");
const fullName = new Sequence("full-name", [firstName, space, lastName]);
const result = fullName.exec("John Doe");
// result.ast.value will be "John Doe"
`#### Options
`typescript
import { Options, Literal } from "clarity-pattern-parser";const john = new Literal("john", "John");
const jane = new Literal("jane", "Jane");
const names = new Options("names", [john, jane]);
const result = names.exec("Jane");
// result.ast.value will be "Jane"
`#### Expression
`typescript
import { Expression, Literal } from "clarity-pattern-parser";const a = new Literal("a", "a");
const b = new Literal("b", "b");
const c = new Literal("c", "c");
const expression = new Expression("expression", [a, b, c]);
const result = expression.exec("a ? b : c");
// result.ast.value will be "a ? b : c"
`$3
`typescript
import { Context, Literal } from "clarity-pattern-parser";const name = new Literal("name", "John");
const context = new Context("name-context", name);
const result = context.exec("John");
// result.ast.value will be "John"
`$3
`typescript
import { Reference, Literal, Sequence } from "clarity-pattern-parser";const name = new Literal("name", "John");
const reference = new Reference("name-ref", name);
const pattern = new Sequence("pattern", [reference]);
const result = pattern.exec("John");
// result.ast.value will be "John"
`$3
Pattern execution returns a
ParseResult that includes the AST and any error information:`typescript
const result = pattern.exec("some text");
if (result.error) {
console.error(result.error.message);
console.error(result.error.expected);
console.error(result.error.position);
} else {
console.log(result.ast?.value);
}
`$3
The AST (Abstract Syntax Tree) returned by pattern execution can be manipulated:
`typescript
const result = pattern.exec("some text");
if (result.ast) {
// Find all nodes with a specific name
const nodes = result.ast.findAll(n => n.name === "space");
// Remove nodes
nodes.forEach(n => n.remove());
// Get the final value
const value = result.ast.value;
}
`Advanced Topics
$3
You can create custom patterns by extending the base
Pattern class:`typescript
import { Pattern } from "clarity-pattern-parser";class CustomPattern extends Pattern {
constructor(name: string) {
super(name);
}
exec(text: string) {
// Custom pattern implementation
}
}
`$3
1. Use
test() instead of exec() when you only need to check if a pattern matches
2. Cache frequently used patterns
3. Use Reference for recursive patterns instead of direct recursion
4. Minimize the use of optional patterns in sequences
5. Use bounded repetition when possible$3
Enable debug mode to get detailed information about pattern execution:
`typescript
const result = pattern.exec("some text", true);
// Debug information will be available in result.debug
`$3
Pattern execution returns a
ParseResult that includes error information:`typescript
const result = pattern.exec("invalid text");
if (result.error) {
console.error(result.error.message);
console.error(result.error.expected);
console.error(result.error.position);
}
`Examples
$3
`typescript
const { json } = patterns;
`$3
`typescript
const { html } = patterns;
``This project is licensed under the MIT License - see the LICENSE file for details.