Generate syntax railroad diagrams

.github/workflows/publish.yml

@@ -34,9 +34,10 @@ jobs:
       shell: bash
       env:
         NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-      # Update the following list when a new package is added
+      # Update the following list when a new npm package is added
       run: |
         npm run publish:latest --provenance --workspace=langium
+        npm run publish:latest --provenance --workspace=langium-railroad
         npm run publish:latest --provenance --workspace=langium-cli
         npm run publish:latest --provenance --workspace=langium-sprotty
         npm run publish:latest --provenance --workspace=generator-langium

examples/arithmetics/package.json

@@ -66,7 +66,7 @@
         "langium:generate": "langium generate",
         "langium:watch": "langium generate --watch",
         "publish:next": "npm --no-git-tag-version version \"$(semver $npm_package_version -i minor)-next.$(git rev-parse --short HEAD)\" && npm publish --tag next",
-        "publish:latest": "npm publish --tag latest"
+        "publish:latest": "npm publish --tag latest --access public"
     },
     "dependencies": {
         "chalk": "~4.1.2",

examples/domainmodel/package.json

@@ -55,7 +55,7 @@
         "langium:generate": "langium generate",
         "langium:watch": "langium generate --watch",
         "publish:next": "npm --no-git-tag-version version \"$(semver $npm_package_version -i minor)-next.$(git rev-parse --short HEAD)\" && npm publish --tag next",
-        "publish:latest": "npm publish --tag latest"
+        "publish:latest": "npm publish --tag latest --access public"
     },
     "dependencies": {
         "chalk": "~4.1.2",

examples/statemachine/package.json

@@ -56,7 +56,7 @@
         "langium:generate": "langium generate",
         "langium:watch": "langium generate --watch",
         "publish:next": "npm --no-git-tag-version version \"$(semver $npm_package_version -i minor)-next.$(git rev-parse --short HEAD)\" && npm publish --tag next",
-        "publish:latest": "npm publish --tag latest"
+        "publish:latest": "npm publish --tag latest --access public"
     },
     "dependencies": {
         "chalk": "~4.1.2",

packages/generator-langium/package.json

@@ -30,7 +30,7 @@
     "test": "vitest run",
     "debug": "npx --node-arg=--inspect yo langium",
     "publish:next": "npm --no-git-tag-version version \"$(semver $npm_package_version -i minor)-next.$(git rev-parse --short HEAD)\" && npm publish --tag next",
-    "publish:latest": "npm publish --tag latest"
+    "publish:latest": "npm publish --tag latest --access public"
   },
   "dependencies": {
     "chalk": "~4.1.2",

packages/langium-cli/README.md

@@ -44,17 +44,22 @@ Schema:
         caseInsensitive: boolean
         // Enable generating a TextMate syntax highlighting file
         textMate: {
-            // Output path to syntax highlighting file
+            // Output path to syntax highlighting file (json)
             out: string
         }
         // Enable generating a monarch syntax highlighting file
         monarch: {
-            // Output path to syntax highlighting file
+            // Output path to syntax highlighting file (js)
             out: string
         }
         // Enable generating a prism syntax highlighting file
         prism: {
-            // Output path to syntax highlighting file
+            // Output path to syntax highlighting file (js)
+            out: string
+        }
+        // Enable generating railroad syntax diagram
+        railroad: {
+            // Output path to syntax diagram file (html)
             out: string
         }
         // Configure the chevrotain parser for a single language
@@ -79,6 +84,9 @@ Example:
         "fileExtensions": [".dmodel"],
         "textMate": {
             "out": "syntaxes/domain-model.tmLanguage.json"
+        },
+        "railroad": {
+            "out": "docs/syntax-diagram.html"
         }
     }],
     "out": "src/language-server/generated",

packages/langium-cli/langium-config-schema.json

@@ -99,6 +99,19 @@
                         "out"
                     ]
                 },
+                "railroad": {
+                    "description": "An object to describe railroad syntax diagram properties",
+                    "type": "object",
+                    "properties": {
+                        "out": {
+                            "description": "The output file path to the generated railroad html file",
+                            "type": "string"
+                        }
+                    },
+                    "required": [
+                        "out"
+                    ]
+                },
                 "chevrotainParserConfig": {
                     "$ref": "#/$defs/chevrotainParserConfig"
                 }

packages/langium-cli/package.json

@@ -30,14 +30,15 @@
     "watch": "tsc --watch",
     "lint": "eslint src test --ext .ts",
     "publish:next": "npm --no-git-tag-version version \"$(semver $npm_package_version -i minor)-next.$(git rev-parse --short HEAD)\" && npm publish --tag next",
-    "publish:latest": "npm publish --tag latest"
+    "publish:latest": "npm publish --tag latest --access public"
   },
   "dependencies": {
     "chalk": "~4.1.2",
     "commander": "~10.0.0",
     "fs-extra": "~11.1.0",
     "jsonschema": "~1.4.1",
     "langium": "~1.2.0",
+    "langium-railroad": "~1.2.0",
     "lodash": "~4.17.21"
   },
   "devDependencies": {

packages/langium-cli/src/generate.ts

@@ -19,6 +19,7 @@ import { getUserChoice, log } from './generator/util';
 import { getFilePath, RelativePath } from './package';
 import { validateParser } from './parser-validation';
 import { generateTypesFile } from './generator/types-generator';
+import { createGrammarDiagramHtml } from 'langium-railroad';
 import chalk from 'chalk';
 import path from 'path';
 import fs from 'fs-extra';
@@ -257,6 +258,7 @@ export async function generate(config: LangiumConfig, options: GenerateOptions):
 
     for (const grammar of grammars) {
         const languageConfig = configMap.get(grammar);
+
         if (languageConfig?.textMate) {
             const genTmGrammar = generateTextMate(grammar, languageConfig);
             const textMatePath = path.resolve(relPath, languageConfig.textMate.out);
@@ -277,6 +279,13 @@ export async function generate(config: LangiumConfig, options: GenerateOptions):
             log('log', options, `Writing prism grammar to ${chalk.white.bold(prismPath)}`);
             await writeHighlightGrammar(genPrismGrammar, prismPath, options);
         }
+
+        if (languageConfig?.railroad) {
+            const diagram = createGrammarDiagramHtml(grammar);
+            const diagramPath = path.resolve(relPath, languageConfig.railroad.out);
+            log('log', options, `Writing railroad syntax diagram to ${chalk.white.bold(diagramPath)}`);
+            await writeWithFail(diagramPath, diagram, options);
+        }
     }
 
     return buildResult(true);

packages/langium-cli/src/package.ts

@@ -63,6 +63,11 @@ export interface LangiumLanguageConfig {
         /** Output path to syntax highlighting file */
         out: string
     }
+    /** Enable generating a railroad syntax diagram */
+    railroad?: {
+        /** Output path to the railroad diagram file */
+        out: string
+    }
     /** Configure the chevrotain parser for a single language */
     chevrotainParserConfig?: IParserConfig
 }

packages/langium-railroad/LICENSE

@@ -0,0 +1,16 @@
+Copyright 2023 TypeFox GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

packages/langium-railroad/README.md

@@ -0,0 +1,5 @@
+# Langium Railroad Diagrams
+
+This package provides the ability to build railroad syntax diagrams for [Langium](https://langium.org) grammars.
+
+It is reused by the [langium-cli](https://www.npmjs.com/package/langium-cli) package and the [Langium VSCode extension](https://marketplace.visualstudio.com/items?itemName=langium.langium-vscode).

packages/langium-railroad/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "langium-railroad",
+  "version": "1.2.0",
+  "description": "Use Langium as source for railroad syntax diagrams",
+  "homepage": "https://langium.org",
+  "keywords": [
+    "language",
+    "dsl",
+    "diagram",
+    "lsp",
+    "language-server",
+    "vscode",
+    "visualization",
+    "modeling"
+  ],
+  "license": "MIT",
+  "files": [
+    "lib",
+    "src"
+  ],
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "clean": "shx rm -rf lib coverage",
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "lint": "eslint src --ext .ts",
+    "publish:next": "npm --no-git-tag-version version \"$(semver $npm_package_version -i minor)-next.$(git rev-parse --short HEAD)\" && npm publish --tag next",
+    "publish:latest": "npm publish --tag latest --access public"
+  },
+  "dependencies": {
+    "langium": "~1.2.0",
+    "railroad-diagrams": "^1.0.0"
+  },
+  "volta": {
+    "node": "16.19.0",
+    "npm": "8.19.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/langium/langium",
+    "directory": "packages/langium-railroad"
+  },
+  "bugs": "https://github.com/langium/langium/issues",
+  "author": {
+    "name": "TypeFox",
+    "url": "https://www.typefox.io"
+  }
+}