tsPEG TypeScript Parser Generator

The calculator implementation consists of three main parts:

• grammar.peg: The tsPEG grammar specification defining the mathematical syntax.
• eval.ts: Logic for traversing and evaluating the generated parse tree.
• cli.ts: The CLI wrapper that handles user input and output.

Grammars use a syntax similar to EBNF. Rules are defined using :=.

Rule Definition: ruleName := expression

Capturing Data: By default, rules only return their kind. To capture specific parts of a match into the AST, use the = assignment operator within the rule description. Rules that are simple references to other rules are captured implicitly.

Example:

sum := left=num '\+' right=num
num := '[0-9]+'

This generates a sum interface/class:

interface sum {
    left: string;
    right: string;
}

You can add fields to your AST that are calculated during the parsing process by appending a computed property expression to a rule. This allows you to perform logic (like type conversion or arithmetic) directly within the grammar instead of post-processing the AST.

Syntax: .<propertyname> = <type> { <code to calculate property> }

Example of computing a sum and parsing integers:

sum := left=num '\+' right=num
       .sum = number { return this.left.value + this.right.value }
num := literal='[0-9]+'
       .value = number { return parseInt(this.literal); }

The & operator allows you to match a pattern without consuming the input. This is useful for parsing context-sensitive languages (languages that are not context-free) where you need to verify a pattern exists before proceeding with the actual consumption of tokens.

In this specific demo, the lookahead operator is used to ensure that the number of 'a's, 'b's, and 'c's are equal (e.g., matching aabbcc or aaabbbccc but rejecting aaaaabbc or aaabbb) by checking the sequence without advancing the parser position prematurely.

/* The demo logic uses the & operator to match but not consume input */

By default, a parser might succeed even if there is trailing unconsumed input. To ensure the parser only succeeds if the entire input is consumed, append the $ symbol (representing EOF) to your rule.

If the $ match fails, the parser will return a SyntaxErr containing an EOFMatch object in the expected matches.

hello := 'Hello World' $

You can install the tspeg CLI globally using npm to generate parsers from grammar files.

npm install -g tspeg

To run this specific demo, you must first generate the parser from the grammar file, compile the TypeScript project, and then execute the CLI. This demo demonstrates how to use computed properties within a grammar to handle expression evaluation logic directly in grammar.gram instead of using external evaluation functions.

# 1. Generate the parser
tspeg grammar.gram parser.ts

# 2. Compile the project
tsc -p .

# 3. Execute the CLI
node jsbuild/cli.js

To use external TypeScript types or functions within your computed properties, you can define a header at the top of your grammar file. Anything placed between two lines of three dashes --- is inserted directly into the generated parser file.

Example:

---
import { myFunc, myType } from "./mypackage";
---
rule := hello='Hello World'
        .value = myType { return myFunc(this.hello); }

The calculator demo is a CLI application that evaluates mathematical expressions (e.g., (10+2) / 4). To run the demo, you must first generate the parser from the grammar, compile the TypeScript project, and then execute the resulting JavaScript CLI.

# 1. Generate the parser from the grammar
tspeg grammar.peg parser.ts

# 2. Compile the project
tsc -p .

# 3. Execute the CLI
node jsbuild/cli.js

The JSON parser demo is an implementation of the RFC 4627 specification. It demonstrates advanced tspeg features such as computed properties, header modifiers, and regex modifiers.

To generate the parser from the grammar and execute the included tests, follow these steps:

# 1. Generate the parser from the grammar file
tspeg grammar.peg parser.ts

# 2. Compile the TypeScript project
tsc -p .

# 3. Run the test script
node jsbuild/test.js