Clarity Pattern Parser

A 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

Features

- 🎯 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

Installation

``bash
npm install clarity-pattern-parser
`

Quick Start

$3

`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"
`

$3

`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"
`

Online Playground

Try Clarity Pattern Parser in your browser with our interactive playground:

Open in 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

Table of Contents

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

Grammar Documentation

This document describes the grammar features supported by the Clarity Pattern Parser.

$3

#### 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/
`

$3

#### 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
`

$3

#### 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)+
`

$3

#### 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
}
`

$3

#### 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
`

$3


Add comments using the # 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
first-name = "John"
last-name = "Doe"
space = /\s+/
full-name = first-name + space + last-name
;

const result = fullName.exec("John Doe");
// result.ast.value will be "John Doe"
`

#### Complex Example (HTML-like Markup)
`typescript
const { body } = patterns
tag-name = /[a-zA-Z_-]+[a-zA-Z0-9_-]*/
ws = /\s+/
opening-tag = "<" + tag-name + ws? + ">"
closing-tag = ""
child = ws? + element + ws?
children = (child)*
element = opening-tag + children + closing-tag
body = ws? + element + ws?
;

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
# Basic JSON grammar
ws = /\s+/
string = /"[^"]*"/
number = /-?\d+(\.\d+)?/
boolean = "true" | "false"
null = "null"
value = string | number | boolean | null | array | object
array-items = (value, /\s,\s/)+
array = "[" +ws? + array-items? + ws? + "]"
object-property = string + ws? + ":" + ws? + value
object-properties = (object-property, /\s,\s/ trim)+
object = "{" + ws? + object-properties? + ws? + "}"
json = ws? + value + ws?
;
`

$3

`typescript
const { html } = patterns
# Basic HTML grammar
ws = /\s+/
tag-name = /[a-zA-Z_-]+[a-zA-Z0-9_-]*/
attribute-name = /[a-zA-Z_-]+[a-zA-Z0-9_-]*/
attribute-value = /"[^"]*"/
value-attribute = attribute-name + "=" + attribute-value
bool-attribute = attribute-name
attribute = value-attribute | bool-attribute
attributes = (attribute, ws)*
opening-tag = "<" + ws? + tag-name + ws? + attributes? + ">"
closing-tag = ""
text = /[^<]+/
child = text | element
children = (child, /\s*/)+
element = opening-tag + children? + closing-tag
html = ws? + element + ws?
;
``

License

This project is licensed under the MIT License - see the LICENSE file for details.