feat: expose cts-dts-gen on root chevrotain package (#1713)

.prettierignore

@@ -12,6 +12,7 @@
 
 /examples/webpack/lib
 /examples/implementation_languages/typescript/*.js
+/examples/implementation_languages/typescript/*.d.ts
 /examples/implementation_languages/coffeescript/*.js
 /examples/parser/minification/gen/
 

examples/implementation_languages/README.md

@@ -12,6 +12,9 @@ The following examples all implement the same JSON parser using a variety of imp
 
 - [TypeScript](https://github.com/chevrotain/chevrotain/blob/master/examples/implementation_languages/typescript/typescript_json.ts)
 
+  - [Generated CST d.ts signatures](https://github.com/chevrotain/chevrotain/blob/master/examples/implementation_languages/typescript/json_cst.d.ts)
+  - [Script to generate CST d.ts signatures](https://github.com/chevrotain/chevrotain/blob/master/examples/implementation_languages/typescript/scripts/gen_dts_signatures.js)
+
 - [CoffeeScript](https://github.com/chevrotain/chevrotain/blob/master/examples/implementation_languages/coffeescript/coffeescript_json.coffee)
 
 To run all the implementation languages examples tests:

examples/implementation_languages/package.json

@@ -3,7 +3,7 @@
   "version": "9.1.0",
   "scripts": {
     "build": "npm-run-all build:ts build:coffee",
-    "build:ts": "tsc ./typescript/typescript_json.ts --types \" \"",
+    "build:ts": "tsc ./typescript/typescript_json.ts --types \" \" && node ./typescript/scripts/gen_dts_signatures.js",
     "build:coffee": "coffee -c ./coffeescript/coffeescript_json.coffee",
     "test": "npm-run-all test:*",
     "test:cjs": "mocha \"*spec.js\"",

examples/implementation_languages/typescript/json_cst.d.ts

@@ -0,0 +1,69 @@
+import type { CstNode, ICstVisitor, IToken } from "chevrotain";
+
+export interface JsonCstNode extends CstNode {
+  name: "json";
+  children: JsonCstChildren;
+}
+
+export type JsonCstChildren = {
+  object?: ObjectCstNode[];
+  array?: ArrayCstNode[];
+};
+
+export interface ObjectCstNode extends CstNode {
+  name: "object";
+  children: ObjectCstChildren;
+}
+
+export type ObjectCstChildren = {
+  LCurly: IToken[];
+  objectItem?: ObjectItemCstNode[];
+  Comma?: IToken[];
+  RCurly: IToken[];
+};
+
+export interface ObjectItemCstNode extends CstNode {
+  name: "objectItem";
+  children: ObjectItemCstChildren;
+}
+
+export type ObjectItemCstChildren = {
+  StringLiteral: IToken[];
+  Colon: IToken[];
+  value: ValueCstNode[];
+};
+
+export interface ArrayCstNode extends CstNode {
+  name: "array";
+  children: ArrayCstChildren;
+}
+
+export type ArrayCstChildren = {
+  LSquare: IToken[];
+  value?: ValueCstNode[];
+  Comma?: IToken[];
+  RSquare: IToken[];
+};
+
+export interface ValueCstNode extends CstNode {
+  name: "value";
+  children: ValueCstChildren;
+}
+
+export type ValueCstChildren = {
+  StringLiteral?: IToken[];
+  NumberLiteral?: IToken[];
+  object?: ObjectCstNode[];
+  array?: ArrayCstNode[];
+  True?: IToken[];
+  False?: IToken[];
+  Null?: IToken[];
+};
+
+export interface ICstNodeVisitor<IN, OUT> extends ICstVisitor<IN, OUT> {
+  json(children: JsonCstChildren, param?: IN): OUT;
+  object(children: ObjectCstChildren, param?: IN): OUT;
+  objectItem(children: ObjectItemCstChildren, param?: IN): OUT;
+  array(children: ArrayCstChildren, param?: IN): OUT;
+  value(children: ValueCstChildren, param?: IN): OUT;
+}

examples/implementation_languages/typescript/scripts/gen_dts_signatures.js

@@ -0,0 +1,12 @@
+/**
+ * This is a minimal script that generates TypeScript definitions
+ * from a Chevrotain parser.
+ */
+const { writeFileSync } = require("fs")
+const { resolve } = require("path")
+const { generateCstDts } = require("chevrotain")
+const { productions } = require("../typescript_json")
+
+const dtsString = generateCstDts(productions)
+const dtsPath = resolve(__dirname, "..", "json_cst.d.ts")
+writeFileSync(dtsPath, dtsString)

examples/implementation_languages/typescript/typescript_json.ts

@@ -1,4 +1,4 @@
-import { createToken, Lexer, CstParser } from "chevrotain"
+import { createToken, Lexer, CstParser, Rule } from "chevrotain"
 
 const True = createToken({ name: "True", pattern: /true/ })
 const False = createToken({ name: "False", pattern: /false/ })
@@ -102,6 +102,8 @@ class JsonParserTypeScript extends CstParser {
 // reuse the same parser instance.
 const parser = new JsonParserTypeScript()
 
+export const productions: Record<string, Rule> = parser.getGAstProductions()
+
 export function parseJson(text) {
   const lexResult = JsonLexer.tokenize(text)
   // setting a new input will RESET the parser instance's state.

packages/chevrotain/package.json

@@ -72,6 +72,8 @@
   },
   "dependencies": {
     "@chevrotain/types": "^9.1.0",
+    "@chevrotain/gast": "^9.1.0",
+    "@chevrotain/cst-dts-gen": "^9.1.0",
     "@chevrotain/utils": "^9.1.0",
     "regexp-to-ast": "0.5.0",
     "lodash": "4.17.21"

packages/chevrotain/src/api.ts

@@ -48,16 +48,17 @@ export {
   RepetitionWithSeparator,
   Rule,
   Terminal
-} from "./parse/grammar/gast/gast_public"
+} from "@chevrotain/gast"
 
 // GAST Utilities
 
 export {
   serializeGrammar,
-  serializeProduction
-} from "./parse/grammar/gast/gast_public"
+  serializeProduction,
+  GAstVisitor
+} from "@chevrotain/gast"
 
-export { GAstVisitor } from "./parse/grammar/gast/gast_visitor_public"
+export { generateCstDts } from "@chevrotain/cst-dts-gen"
 
 /* istanbul ignore next */
 export function clearCache() {

packages/chevrotain/src/parse/errors_public.ts

@@ -2,13 +2,8 @@ import { hasTokenLabel, tokenLabel } from "../scan/tokens_public"
 import first from "lodash/first"
 import map from "lodash/map"
 import reduce from "lodash/reduce"
-import {
-  Alternation,
-  NonTerminal,
-  Rule,
-  Terminal
-} from "./grammar/gast/gast_public"
-import { getProductionDslName } from "./grammar/gast/gast"
+import { Alternation, NonTerminal, Rule, Terminal } from "@chevrotain/gast"
+import { getProductionDslName } from "@chevrotain/gast"
 import {
   IParserErrorMessageProvider,
   IProductionWithOccurrence,

packages/chevrotain/src/parse/grammar/checks.ts

@@ -20,7 +20,7 @@ import {
   IParserEmptyAlternativeDefinitionError,
   ParserDefinitionErrorType
 } from "../parser/parser"
-import { getProductionDslName, isOptionalProd } from "./gast/gast"
+import { getProductionDslName, isOptionalProd } from "@chevrotain/gast"
 import {
   Alternative,
   containsPath,
@@ -41,8 +41,8 @@ import {
   RepetitionWithSeparator,
   Rule,
   Terminal
-} from "./gast/gast_public"
-import { GAstVisitor } from "./gast/gast_visitor_public"
+} from "@chevrotain/gast"
+import { GAstVisitor } from "@chevrotain/gast"
 import {
   IProduction,
   IProductionWithOccurrence,

packages/chevrotain/src/parse/grammar/first.ts

@@ -1,8 +1,12 @@
 import flatten from "lodash/flatten"
 import uniq from "lodash/uniq"
 import map from "lodash/map"
-import { AbstractProduction, NonTerminal, Terminal } from "./gast/gast_public"
-import { isBranchingProd, isOptionalProd, isSequenceProd } from "./gast/gast"
+import { NonTerminal, Terminal } from "@chevrotain/gast"
+import {
+  isBranchingProd,
+  isOptionalProd,
+  isSequenceProd
+} from "@chevrotain/gast"
 import { IProduction, TokenType } from "@chevrotain/types"
 
 export function first(prod: IProduction): TokenType[] {
@@ -20,15 +24,17 @@ export function first(prod: IProduction): TokenType[] {
   } else if (prod instanceof Terminal) {
     return firstForTerminal(<Terminal>prod)
   } else if (isSequenceProd(prod)) {
-    return firstForSequence(<AbstractProduction>prod)
+    return firstForSequence(prod)
   } else if (isBranchingProd(prod)) {
-    return firstForBranching(<AbstractProduction>prod)
+    return firstForBranching(prod)
   } else {
     throw Error("non exhaustive match")
   }
 }
 
-export function firstForSequence(prod: AbstractProduction): TokenType[] {
+export function firstForSequence(prod: {
+  definition: IProduction[]
+}): TokenType[] {
   let firstSet: TokenType[] = []
   const seq = prod.definition
   let nextSubProdIdx = 0
@@ -48,7 +54,9 @@ export function firstForSequence(prod: AbstractProduction): TokenType[] {
   return uniq(firstSet)
 }
 
-export function firstForBranching(prod: AbstractProduction): TokenType[] {
+export function firstForBranching(prod: {
+  definition: IProduction[]
+}): TokenType[] {
   const allAlternativesFirsts: TokenType[][] = map(
     prod.definition,
     (innerProd) => {

packages/chevrotain/src/parse/grammar/follow.ts

@@ -3,7 +3,7 @@ import { first } from "./first"
 import forEach from "lodash/forEach"
 import assign from "lodash/assign"
 import { IN } from "../constants"
-import { Alternative, NonTerminal, Rule, Terminal } from "./gast/gast_public"
+import { Alternative, NonTerminal, Rule, Terminal } from "@chevrotain/gast"
 import { IProduction, TokenType } from "@chevrotain/types"
 
 // This ResyncFollowsWalker computes all of the follows required for RESYNC