clarity-pattern-parser 11.5.3 → 11.6.0

package/src/grammar/spec.md

@@ -1,331 +0,0 @@
-# Grammar Documentation
-
-This guide describes the syntax rules and composition patterns supported by cpat. Each section shows how to define reusable parsing rules.
-
----
-
-## Literals
-
-A **literal** matches an exact string.
-
-```grammar
-name = "Literal"
-```
-
----
-
-## Regex
-
-A **regex** pattern matches text using a regular expression.
-
-```grammar
-digits = /\d+/
-```
-
-### Regex Caveats
-Do **not** use `^` at the start or `$` at the end of your regex. If you want to constrain the beginning or end of the input, use a dedicated pattern instead.
-
----
-
-## Sequence
-
-A **sequence** succeeds only if all patterns match in the given order.
-
-```grammar
-space = " "
-first-name = "John"
-last-name = "Doe"
-full-name = first-name + space + last-name
-```
-
----
-
-## Optional Pattern
-
-Patterns in a sequence may be marked **optional**.
-
-```grammar
-space = " "
-first-name = /\w+/
-last-name = /\w+/
-middle-name = /\w+/
-middle-name-with-space = middle-name + space
-
-full-name = first-name + space + middle-name-with-space? + last-name
-```
-
----
-
-## Negative Lookahead
-
-Use `!` to prevent a specific pattern from matching.
-
-```grammar
-space = " "
-first-name = /\w+/
-last-name = /\w+/
-jack = "Jack"
-
-full-name = !jack + first-name + space + last-name
-```
-
-This ensures the first name is not `"Jack"`.
-
----
-
-## Options
-
-An **options** pattern succeeds if *any one* of the choices matches.
-
-```grammar
-multiply = "*"
-divide = "/"
-operators = multiply | divide
-```
-
----
-
-## Repeat
-
-### Zero or More
-
-```grammar
-digit = /\d/
-digits = (digit)*
-```
-
-### Zero or More with Delimiters
-
-```grammar
-digit = /\d/
-comma = ","
-digits = (digit, comma)*
-```
-
-### One or More with Trimmed Trailing Delimiter
-
-```grammar
-digit = /\d/
-comma = ","
-digits = (digit, comma trim)+
-```
-
-This prevents trailing commas from being accepted.
-
----
-
-### One or More
-
-```grammar
-digit = /\d/
-digits = (digit)+
-```
-
-### Exact Count
-
-```grammar
-digit = /\d/
-digits = (digit){2}
-```
-
-### Bounded Repeats
-
-```grammar
-digit = /\d/
-digits = (digit){1,3}   # between 1 and 3
-digits = (digit){,3}    # up to 3
-```
-
----
-
-## Expressions
-
-Expressions support **prefix**, **infix**, **postfix**, and **right-associative** notation, with operator precedence and recursion.
-
-- **Prefix**: Operator(s) come before the expression. The sequence must end with the name of the expression being made.  
-- **Infix**: Operator(s) come between expressions.  
-- **Postfix**: Operator(s) come after the expression.  
-- **Right-associative**: Operator(s) group toward the right.  
-
-### Prefix Expression
-
-```grammar
-increment = "++"
-integer = /[1-9][0-9]*/
-space = /\s+/
-
-prefix-expr = increment + space? + expr
-expr = prefix-expr | integer
-```
-
-Examples:  
-- `++5`  
-- `++ 10`
-
----
-
-### Infix Expression
-
-```grammar
-add-sub = "+" | "-"
-mul-div = "*" | "/"
-integer = /[1-9][0-9]*/
-space = /\s+/
-
-add-sub-expr = expr + space? + add-sub + space? + expr
-mul-div-expr = expr + space? + mul-div + space? + expr
-
-expr = mul-div-expr | add-sub-expr | integer
-```
-
-Examples:  
-- `4 * 2`  
-- `7 + 3`  
-
----
-
-### Postfix Expression
-
-```grammar
-factorial = "!"
-integer = /[1-9][0-9]?/
-space = /\s+/
-
-postfix-expr = expr + space? + factorial
-expr = postfix-expr | integer
-```
-
-Examples:  
-- `5!`  
-- `10 !`  
-
----
-
-### Combined Expressions
-
-By layering them into a single `expr` rule, you can combine prefix, infix, and postfix with precedence:
-
-```grammar
-increment = "++"
-factorial = "!"
-add-sub = "+" | "-"
-mul-div = "*" | "/"
-
-integer = /[1-9][0-9]*/
-space = /\s+/
-
-prefix-expr   = increment + space? + expr
-postfix-expr  = expr + space? + factorial
-mul-div-expr  = expr + space? + mul-div + space? + expr
-add-sub-expr  = expr + space? + add-sub + space? + expr
-
-expr = postfix-expr 
-     | prefix-expr 
-     | mul-div-expr 
-     | add-sub-expr 
-     | integer
-```
-
-Examples:  
-- `++5`  
-- `5!`  
-- `++5!`  
-- `2 + 3 * 4`  
-
----
-
-### Recursive Expressions
-
-Since each rule references `expr`, the grammar is recursive and can handle deeply nested inputs.
-
-Examples:  
-- `7++` → `postfix-expr`  
-- `7++ * 9` → `mul-div-expr`  
-- `7++ * 9 + 10` → `(7++) * 9 + 10` with correct precedence  
-
----
-
-### Right-Associative Expressions
-
-Some operators must associate to the **right**. Mark the operator with `right` to enforce this.
-
-```grammar
-power = "^"
-integer = /[1-9][0-9]*/
-space = /\s+/
-
-power-expr = expr + space? + power + space? + expr
-expr = power-expr right | integer
-```
-
-Examples:  
-- `2 ^ 3 ^ 2`  
-  - Right-associative → `2 ^ (3 ^ 2)` = `512`  
-  - Left-associative → `(2 ^ 3) ^ 2` = `64`  
-
----
-
-
-## Imports
-
-### Basic Import
-
-```grammar
-import { spaces } from "https://some.cdn.com/some/spaces.cpat"
-
-first-name = "John"
-last-name = "Doe"
-full-name = first-name + spaces + last-name
-```
-
-### Multiple Named Imports
-
-```grammar
-import { spaces, first-name } from "https://some.cdn.com/some/spaces.cpat"
-
-last-name = "Doe"
-full-name = first-name + spaces + last-name
-```
-
-### Multiple Imports
-
-```grammar
-import { spaces, first-name } from "https://some.cdn.com/some/patterns.cpat"
-import { last-name } from "https://some.cdn.com/some/last-name.cpat"
-
-full-name = first-name + spaces + last-name
-```
-
----
-
-## Import Parameters
-
-You can inject parameters into imported patterns.
-
-**File:** `main.ts`
-```ts
-const firstName = new Literal("first-name", "John");
-const lastName = new Literal("last-name", "Doe");
-const grammar = Grammar.import('file.cpat', { params: [firstName, LastName] });
-```
-
-**File:** `file.cpat`
-```grammar
-use params { first-name, last-name }
-
-full-name = first-name + spaces + last-name
-```
-
-### Imports with Params
-
-```grammar
-use params { other-pattern }
-import { first-names, last-names } from "some-file.cpat" with params {
-    some-pattern = "Some Pattern"
-    some-pattern2 = other-pattern
-}
-
-full-name = first-names + spaces + last-names
-```
-
----

package/src/grammar_v2/patterns/Grammar.ts

@@ -1,170 +0,0 @@
-import { Node } from "../../ast/Node";
-import { tokens } from "../../grammar/decorators/tokens";
-import { GrammarFile } from "../../grammar/Grammar";
-import { generateErrorMessage } from "../../patterns/generate_error_message";
-import { Pattern } from "../../patterns/Pattern";
-import { grammar } from "./patterns/grammar"
-
-let anonymousIndexId = 0;
-
-function defaultImportResolver(_path: string, _basePath: string | null): Promise<GrammarFile> {
-    throw new Error("No import resolver supplied.");
-}
-
-function defaultImportResolverSync(_path: string, _basePath: string | null): GrammarFile {
-    throw new Error("No import resolver supplied.");
-}
-
-export type Decorator = (pattern: Pattern, arg?: string | boolean | number | null | Record<string, any> | any[]) => void;
-
-const defaultDecorators = {
-    tokens: tokens
-};
-
-export interface GrammarOptions {
-    resolveImport?: (resource: string, originResource: string | null) => Promise<GrammarFile>;
-    resolveImportSync?: (resource: string, originResource: string | null) => GrammarFile;
-    originResource?: string | null;
-    params?: Pattern[];
-    decorators?: Record<string, Decorator>;
-}
-
-class ParseContext {
-    patternsByName = new Map<string, Pattern>();
-    importedPatternsByName = new Map<string, Pattern>();
-    paramsByName = new Map<string, Pattern>();
-    decorators: Record<string, Decorator>;
-
-    constructor(params: Pattern[], decorators: Record<string, Decorator> = {}) {
-        params.forEach(p => this.paramsByName.set(p.name, p));
-        this.decorators = { ...decorators, ...defaultDecorators };
-    }
-
-    getImportedPatterns() {
-        return Array.from(this.importedPatternsByName.values());
-    }
-
-    getParams() {
-        return Array.from(this.paramsByName.values());
-    }
-
-}
-
-export class Grammar {
-    private _options: GrammarOptions;
-    private _parseContext: ParseContext;
-    private _resolveImportSync: (resource: string, originResource: string | null) => GrammarFile;
-
-    constructor(options: GrammarOptions) {
-        this._options = options;
-        this._parseContext = new ParseContext(options.params || [], options.decorators || {});
-        this._resolveImportSync = options.resolveImportSync == null ? defaultImportResolverSync : options.resolveImportSync;
-    }
-
-    // parse(cpat: string): Promise<Pattern> { }
-    // import(path: string): Promise<Pattern> { }
-
-    // parseString(cpat: string): Pattern {
-    //     const ast = this._tryToParse(cpat);
-
-    //     this._flattenExpressions(ast);
-
-    // }
-
-    private _resolveImportsSync(ast: Node) {
-        const importStatements = ast.findAll(n => {
-            return n.name === "importStatement" || n.name === "useParamsStatement";
-        });
-
-        for (const importStatement of importStatements) {
-            if (importStatement.name === "importStatement") {
-                this._processImportSync(importStatement);
-            } else {
-                this._processUseParams(importStatement);
-            }
-        }
-    }
-
-    private _processImportSync(importStatement: Node) {
-        const parseContext = this._parseContext;
-        const resourceNode = importStatement.find(n => n.name === "resource") as Node;
-        const params = this._getWithParams(importStatement);
-        const resource = resourceNode.value.slice(1, -1);
-        const grammarFile = this._resolveImportSync(resource, this._options.originResource || null);
-
-
-        if (resourceNode == null) {
-            throw new Error("Invalid import statement: resource is required");
-        }
-
-
-    }
-
-    private _getWithParams(importStatement: Node) {
-        const withParamsStatements = importStatement.find(n => n.name === "withParamsStatements");
-
-        if (withParamsStatements == null) {
-            return [];
-        }
-
-        const expression = withParamsStatements.toString();
-        const importedValues = this._parseContext.getImportedPatterns();
-
-        const grammar = new Grammar({
-            params: [...importedValues, ...this._parseContext.paramsByName.values()],
-            originResource: this._options.originResource,
-            resolveImport: this._options.resolveImport,
-            decorators: this._parseContext.decorators
-        });
-
-        // const patterns = grammar.parseString(expression);
-        // return Array.from(Object.values(patterns));
-        return[]
-    }
-
-
-    private _processUseParams(useParamsStatement: Node) {
-    }
-
-    private _tryToParse(cpat: string): Node {
-        const { ast, cursor } = grammar.exec(cpat, true);
-
-        if (ast == null) {
-            const message = generateErrorMessage(grammar, cursor);
-            throw new Error(`[Invalid Grammar] ${message}`);
-        }
-
-        return ast;
-    }
-
-
-    private _flattenExpressions(node: Node) {
-        switch (node.name) {
-            case "sequenceExpr":
-                return this._unwrapNode("sequenceExpr", node);
-            case "optionsExpr":
-                return this._unwrapNode("optionsExpr", node);
-            case "greedyOptionsExpr":
-                return this._unwrapNode("greedyOptionsExpr", node);
-            default:
-                return node;
-        }
-    }
-
-    private _unwrapNode(type: string, node: Node) {
-        if (node.name !== type) {
-            return node;
-        }
-
-        for (let x = 0; x < node.children.length; x++) {
-            const child = node.children[x];
-
-            if (child.name === type) {
-                node.spliceChildren(x, 1, ...child.children);
-                x--;
-            }
-        }
-
-        return node;
-    }
-}

package/src/grammar_v2/patterns/patterns/cpat.cpat

@@ -1,91 +0,0 @@
-# syntax
-syntax = "syntax"
-import = "import"
-useParams = "use params"
-withParams = "with params"
-from = "from"
-right = "right"
-ws = /\s+/
-ls = /[ \t]+/
-assign = "="
-bar = "|"
-concat = "+"
-colon = ":"
-openParen = "("
-closeParen = ")"
-openSquareBracket = "["
-closeSquareBracket = "]"
-openBracket = "{"
-closeBracket = "}"
-comma = /\s*[,]\s*/
-trim = "trim"
-not = "!"
-optional = "?"
-newLine = /\s*(\r\n|\r|\n)\s*/
-syntaxVersion = /\S*/
-at = "@"
-
-literal = /"(?:\\.|[^"\\])*"/
-regexLiteral = /\/(\\/|[^\n\r])*\//
-
-integer = /[1-9][0-9]*|[0]/ 
-name = /[a-zA-Z_-]+[a-zA-Z0-9_-]*/
-patternName = name
-patternIdentifier = name
-resource = literal
-
-comment = /#[^\n\r]*/
-
-# JSON
-jsonString = literal
-jsonNumber = /-?\d+(\.\d+)?/
-jsonBoolean = "true" | "false"
-jsonNull = "null"
-jsonValue = jsonString | jsonNumber | jsonBoolean | jsonNull | jsonArray | jsonObject
-jsonArrayItems = (jsonValue, comma trim)+
-jsonArray = openSquareBracket +ws? + jsonArrayItems? + ws? + closeSquareBracket
-jsonObjectPropertyName = literal
-jsonObjectProperty = jsonObjectPropertyName + ws? + colon + ws? + jsonValue
-jsonObjectProperties = (jsonObjectProperty, comma trim)+
-jsonObject = openBracket + ws? + jsonObjectProperties? + ws? + closeBracket
-
-syntaxStatement = syntax + ws? + syntaxVersion
-
-decorationName = name
-decorationStatement = at + ws? + decorationName + ws? + openParen + ws? + jsonValue? + ws? + closeParen
-
-useParamPatterns = (patternName, comma trim)+
-useParamsStatement = useParams + ls? + openBracket + ws? + useParamPatterns + ws? + closeBracket
-
-withParamStatements = (patternAssignment, newLine trim)+
-withParamsExpr = withParams + ls? + openBracket + ws? + withParamStatements + ws? + closeBracket
-
-patternNames = (patternName, comma trim)+
-importedPatterns = openBracket + ws? + patternNames + ws? + closeBracket 
-importStatement = import + ls? + importedPatterns + ls? + from + ls? + resource + ls? + withParamsExpr?
-
-notExpr = not + ls? + unaryPatternExpr
-optionalExpr = unaryPatternExpr + ls? + optional
-rightAssociationExpr = unaryPatternExpr + ls? + right
-
-unaryPatternExpr = notExpr | optionalExpr | rightAssociationExpr | patternIdentifier
-
-repeatBounds = openBracket + integer? + comma? + integer? + closeBracket
-oneOrMore = "+"
-zeroOrMore = "*"
-repeatOptions = oneOrMore | zeroOrMore | repeatBounds
-delimiter = comma + patternExpr + ws? + trim?
-repeatExpr = openParen + ws? + patternExpr + ws? + delimiter? + ws? + closeParen + repeatOptions
-
-sequenceExpr = patternExpr + ws? + "+" + ws? + patternExpr 
-optionsExpr = patternExpr + ws? + "|" + ws? + patternExpr
-greedyOptionsExpr = patternExpr + ws? + "<|>" + ws? + patternExpr
-patternGroupExpr = openParen + ws? + patternExpr + ws? + closeParen
-
-exportPattern = patternName
-patternExpr =  sequenceExpr | optionsExpr | greedyOptionsExpr |  repeatExpr | patternGroupExpr | literal | regexLiteral | unaryPatternExpr 
-patternAssignment = patternName + ws? + assign + ws? + patternExpr
-statement = useParamsStatement | importStatement  | patternAssignment | decorationStatement | exportPattern | comment 
-statements = (statement, newLine)+
-cpat = ws? + syntaxStatement? + ws? + statements?
-