@mpeggroup/mpeg-sdl-parser 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Flowscripter
+
+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.

package/README.md

@@ -0,0 +1,337 @@
+# mpeg-sdl-parser
+
+> ISO/IEC 14496-34 Syntactic Description Language (MPEG SDL) parser implemented
+> in TypeScript
+
+[![version](https://img.shields.io/github/v/release/mpeggroup/mpeg-sdl-parser?sort=semver)](https://github.com/mpeggroup/mpeg-sdl-parser/releases)
+[![build](https://img.shields.io/github/actions/workflow/status/mpeggroup/mpeg-sdl-parser/release-bun-library.yml)](https://github.com/mpeggroup/mpeg-sdl-parser/actions/workflows/release-bun-library.yml)
+[![docs](https://img.shields.io/badge/docs-API-blue)](https://mpeggroup.github.io/mpeg-sdl-parser/index.html)
+[![license: MIT](https://img.shields.io/github/license/mpeggroup/mpeg-sdl-parser)](https://github.com/mpeggroup/mpeg-sdl-parser/blob/main/LICENSE)
+
+## Web Editor
+
+A browser based web editor using this module is available at
+https://github.com/MPEGGroup/mpeg-sdl-editor
+
+## Module Usage
+
+### Installation
+
+**NPM**
+
+Add the module to your project:
+
+`npm install @mpeggroup/mpeg-sdl-parser`
+
+**BUN**
+
+Add the module to your project:
+
+`bun add @mpeggroup/mpeg-sdl-parser`
+
+### Example Code
+
+```javascript
+import {
+  SdlStringInput,
+  createLenientSdlParser,
+  collateSyntaxErrors,
+  buildAst,
+  dispatchNodeHandler,
+  prettyPrint
+} from "@mpeggroup/mpeg-sdl-parser";
+
+// Create a Lezer based SDL concrete syntax parser.
+// This will create a lenient parser which recovers from parse errors and places error nodes in the parse tree.
+// A strict parser which will throw a `SyntaxError` can be created with `createStrictSdlParser()`.
+const parser = await createLenientSdlParser();
+
+// Prepare the SDL input
+const sdlStringInput = new SdlStringInput("class A{}");
+
+// Parse SDL input and produce a parse tree
+const sdlParseTree = sdlParser.parse(sdlStringInput);
+
+// Traverse and print the parse tree
+const cursor = sdlParseTree.cursor();
+do {
+  console.log(`Node ${cursor.name} from ${cursor.from} to ${cursor.to}`)
+} while (cursor.next());
+
+// Print any syntax errors by collating any error nodes in the parse tree
+const syntaxErrors = collateSyntaxErrors(sdlParseTree, sdlStringInput);
+
+console.log(JSON.stringify(syntaxErrors);
+
+// Build an Abstract Syntax Tree (AST) of the SDL specification from the concrete parse tree
+// The third argument sets `lenient = true`. If this is not set or is `false`
+// a `SyntaxError` will be thrown if the sdlParseTree contains parsing errors.
+const specification = buildAst(sdlParseTree, sdlStringInput, true);
+
+// Define a simple AST Node handler
+class MyNodeHandler implements NodeHandler {
+  beforeVisit(node: AbstractCompositeNode) {
+    console.log("About to visit child nodes");
+  }
+
+  visit(node: AbstractLeafNode) {
+    console.log("Visiting leaf node");
+  }
+
+  afterVisit(node: AbstractCompositeNode) {
+    console.log("Finished visiting child nodes");
+  }
+}
+
+// Dispatch the handler to visit all nodes in the AST
+dispatchNodeHandler(specification, new MyNodeHandler());
+
+// Create an SDL semantic analyser
+// This will create a lenient analyser which recovers from semantic errors and stores them in the analysis results.
+// A strict analyser which will throw a `SemanticError` can be created with `createStrictSdlAnalyser()`.
+const analyser = createLenientSdlAnalyser();
+
+// Analyse the AST
+const analysisResult = analyser.analyse(specification);
+
+// Print any semantic errors from the AST analysis
+console.log(JSON.stringify(analysisResult.semanticErrors));
+
+// Print any semantic warnings from the AST analysis
+console.log(JSON.stringify(analysisResult.semanticWarnings));
+
+// Pretty print the specification (retaining comments and handling parse errors)
+let prettifiedSpecification = await prettyPrint(specification, sdlStringInput)
+
+console.log(prettifiedSpecification);
+
+// A Prettier (prettier.io) plugin for SDL is also available:
+import * as prettier from "prettier/standalone.js";
+import { prettierPluginSdl } from "@mpeggroup/mpeg-sdl-parser"; 
+
+prettifiedSpecification = await prettier.format("class A{}", { 
+  parser: "sdl",
+  plugins: [prettierPluginSdl],
+});
+
+console.log(prettifiedSpecification);
+```
+
+## Development
+
+Install dependencies:
+
+`bun install`
+
+Generate parser from grammar:
+
+`bun run generate`
+
+Test:
+
+`bun test`
+
+**NOTE**: The following tasks use Deno as it excels at these and Bun does not
+currently provide such functionality:
+
+Format:
+
+`deno fmt`
+
+Lint:
+
+`deno lint index.ts src/ tests/`
+
+Generate HTML API Documentation:
+
+`deno doc --html --name=mpeg-sdl-parser index.ts`
+
+## Documentation
+
+### Overview
+
+The concrete syntax parser is implemented using
+[Lezer](https://lezer.codemirror.net) and the Lezer grammar defined in
+[sdl.lezer.grammar](grammar/sdl.lezer.grammar). This framework was chosen as it:
+
+- Provides robust error recovery whilst parsing.
+- Integrates well with the web based code editor framework
+  [Codemirror](https://codemirror.net) which is used in the
+  [MPEG SDL Editor](https://github.com/MPEGGroup/mpeg-sdl-editor).
+
+For reference purposes an SDL EBNF grammar is also provided in
+[sdl.ebnf.grammar](grammar/sdl.ebnf.grammar)
+
+The concrete syntax tree is then converted to an Abstract Syntax Tree (AST)
+which is not tied to any underlying framework. The AST representation is used
+for pretty printing and as such retains a "full fidelity" represenation of the
+source i.e. including text location and trivia items (comments and blank lines).
+
+### Abstract Syntax Tree Model
+
+```mermaid
+classDiagram
+
+  class Trivia {
+    <<interface>> 
+    text: string;
+  }
+
+  class Location {
+    <<interface>> 
+    row: number
+    column: number
+    position: number
+  }
+
+  class AbstractNode {
+    <<Abstract>>
+    nodeKind: NodeKind
+    isCompositeNode: boolean
+  }
+
+  class AbstractLeafNode {
+    <<Abstract>>
+    isCompositeNode = false
+  }
+
+  class AbstractCompositeNode {
+    <<Abstract>>
+    isCompositeNode = true
+  }
+
+  class Token {
+    text: string;
+    tokenKind: TokenKind;
+  }
+
+  class TraversingVisitor {
+  }
+
+  class NodeVisitor {
+    <<interface>> 
+    visit(node: AbstractNode)
+  }
+
+  class NodeHandler {
+    <<interface>> 
+    beforeVisit(node: AbstractCompositeNode)
+    visit(node: AbstractLeafNode)
+    afterVisit(node: AbstractCompositeNode)
+  }
+
+  Trivia --> Location : location
+
+  NodeHandler ..> AbstractCompositeNode : afterVisit
+  NodeHandler ..> AbstractCompositeNode : beforeVisit
+  NodeHandler ..> AbstractLeafNode : visit
+
+  AbstractNode --> "*" Trivia : leadingTrivia
+  AbstractNode --> "*" Trivia : trailingTrivia
+
+  AbstractLeafNode --|> AbstractNode
+
+  AbstractCompositeNode --|> AbstractNode
+  AbstractCompositeNode --> "*" AbstractNode : children
+  AbstractCompositeNode --> "0..1" Token : startToken
+  AbstractCompositeNode --> "0..1" Token : endToken
+
+  Token --|> AbstractLeafNode
+  Token --> Location
+
+  NodeVisitor ..> AbstractNode : visit
+  TraversingVisitor --|> NodeVisitor
+  TraversingVisitor --> NodeHandler
+
+  CompositeNodeXYZ "*" --|> AbstractCompositeNode
+  Specification --|> AbstractCompositeNode
+```
+
+### Semantic Analyser Model
+
+```mermaid
+classDiagram
+    class SdlAnalyser {
+        configure(options) SdlAnalyser
+        analyse(specification) SdlAnalysisResult
+    }
+
+    class SdlAnalysisResult {
+        <<interface>>
+        SemanticError[] semanticErrors
+        SemanticWarning[] semanticWarnings
+    }
+
+    class SymbolTable {
+        addSymbol()
+        lookupVariable()
+        lookupClass()
+        lookupMap()
+        enterClassScope()
+        enterBlockScope()
+        exitScope()
+    }
+
+    class AbstractAnalysisNodeHandler {
+        <<abstract>>
+    }
+
+    class BuildSymbolTableNodeHandler {
+    }
+
+    class ValidateScopeNodeHandler {
+    }
+
+    class ValidateTypeNodeHandler {
+    }
+
+    class SpecificCheckNodeHandler {
+    }
+
+    class Check {
+        <<interface>>
+        string nodeKind
+        string subKind
+        checkFunc()
+    }
+
+    class Specification {
+    }
+
+    SdlAnalyser --> SdlAnalysisResult : produces
+    SdlAnalyser --> Specification : analyses
+    SdlAnalysisResult --> SymbolTable
+    SdlAnalysisResult --> Specification
+    AbstractAnalysisNodeHandler --> SymbolTable
+    BuildSymbolTableNodeHandler --|> AbstractAnalysisNodeHandler
+    ValidateScopeNodeHandler --|> AbstractAnalysisNodeHandler
+    ValidateTypeNodeHandler --|> AbstractAnalysisNodeHandler
+    SpecificCheckNodeHandler --|> AbstractAnalysisNodeHandler
+    SpecificCheckNodeHandler --> Check
+    SdlAnalyser ..> BuildSymbolTableNodeHandler : pass 1
+    SdlAnalyser ..> ValidateScopeNodeHandler : pass 2
+    SdlAnalyser ..> ValidateTypeNodeHandler : pass 3
+    SdlAnalyser ..> SpecificCheckNodeHandler : pass 4
+```
+
+### API
+
+Link to auto-generated API docs:
+
+[API Documentation](https://mpeggroup.github.io/mpeg-sdl-parser)
+
+### Debug Logging
+
+Internal framework logging can be enabled by setting the `MPEG_SDL_PARSER_DEBUG`
+environment variable. If running in a browser open the developer console and
+run:
+
+`localStorage.setItem("MPEG_SDL_PARSER_DEBUG", "true")`
+
+The logging implementation will look for an object conforming to the `Logger`
+interface and use it if found. If not found, a simple logging implementation
+using the `console` object will be used.
+
+## License
+
+MIT © Flowscripter

package/bun.lock

@@ -0,0 +1,65 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 0,
+  "workspaces": {
+    "": {
+      "name": "@mpeggroup/mpeg-sdl-parser",
+      "dependencies": {
+        "@codemirror/language": "latest",
+        "@codemirror/state": "latest",
+        "@lezer/common": "latest",
+        "@lezer/generator": "latest",
+        "@lezer/highlight": "latest",
+        "@lezer/lr": "latest",
+        "prettier": "latest",
+      },
+      "devDependencies": {
+        "@types/bun": "latest",
+        "@types/node": "latest",
+      },
+      "peerDependencies": {
+        "typescript": "latest",
+      },
+    },
+  },
+  "overrides": {
+    "@codemirror/state": "6.5.4",
+    "@lezer/common": "1.5.0",
+    "@lezer/lr": "1.4.7",
+  },
+  "packages": {
+    "@codemirror/language": ["@codemirror/language@6.12.3", "", { "dependencies": { "@codemirror/state": "^6.0.0", "@codemirror/view": "^6.23.0", "@lezer/common": "^1.5.0", "@lezer/highlight": "^1.0.0", "@lezer/lr": "^1.0.0", "style-mod": "^4.0.0" } }, "sha512-QwCZW6Tt1siP37Jet9Tb02Zs81TQt6qQrZR2H+eGMcFsL1zMrk2/b9CLC7/9ieP1fjIUMgviLWMmgiHoJrj+ZA=="],
+
+    "@codemirror/state": ["@codemirror/state@6.5.4", "", { "dependencies": { "@marijn/find-cluster-break": "^1.0.0" } }, "sha512-8y7xqG/hpB53l25CIoit9/ngxdfoG+fx+V3SHBrinnhOtLvKHRyAJJuHzkWrR4YXXLX8eXBsejgAAxHUOdW1yw=="],
+
+    "@codemirror/view": ["@codemirror/view@6.39.9", "", { "dependencies": { "@codemirror/state": "^6.5.0", "crelt": "^1.0.6", "style-mod": "^4.1.0", "w3c-keyname": "^2.2.4" } }, "sha512-miGSIfBOKC1s2oHoa80dp+BjtsL8sXsrgGlQnQuOcfvaedcQUtqddTmKbJSDkLl4mkgPvZyXuKic2HDNYcJLYA=="],
+
+    "@lezer/common": ["@lezer/common@1.5.0", "", {}, "sha512-PNGcolp9hr4PJdXR4ix7XtixDrClScvtSCYW3rQG106oVMOOI+jFb+0+J3mbeL/53g1Zd6s0kJzaw6Ri68GmAA=="],
+
+    "@lezer/generator": ["@lezer/generator@1.8.0", "", { "dependencies": { "@lezer/common": "^1.1.0", "@lezer/lr": "^1.3.0" }, "bin": { "lezer-generator": "src/lezer-generator.cjs" } }, "sha512-/SF4EDWowPqV1jOgoGSGTIFsE7Ezdr7ZYxyihl5eMKVO5tlnpIhFcDavgm1hHY5GEonoOAEnJ0CU0x+tvuAuUg=="],
+
+    "@lezer/highlight": ["@lezer/highlight@1.2.3", "", { "dependencies": { "@lezer/common": "^1.3.0" } }, "sha512-qXdH7UqTvGfdVBINrgKhDsVTJTxactNNxLk7+UMwZhU13lMHaOBlJe9Vqp907ya56Y3+ed2tlqzys7jDkTmW0g=="],
+
+    "@lezer/lr": ["@lezer/lr@1.4.7", "", { "dependencies": { "@lezer/common": "^1.0.0" } }, "sha512-wNIFWdSUfX9Jc6ePMzxSPVgTVB4EOfDIwLQLWASyiUdHKaMsiilj9bYiGkGQCKVodd0x6bgQCV207PILGFCF9Q=="],
+
+    "@marijn/find-cluster-break": ["@marijn/find-cluster-break@1.0.2", "", {}, "sha512-l0h88YhZFyKdXIFNfSWpyjStDjGHwZ/U7iobcK1cQQD8sejsONdQtTVU+1wVN1PBw40PiiHB1vA5S7VTfQiP9g=="],
+
+    "@types/bun": ["@types/bun@1.3.13", "", { "dependencies": { "bun-types": "1.3.13" } }, "sha512-9fqXWk5YIHGGnUau9TEi+qdlTYDAnOj+xLCmSTwXfAIqXr2x4tytJb43E9uCvt09zJURKXwAtkoH4nLQfzeTXw=="],
+
+    "@types/node": ["@types/node@25.6.0", "", { "dependencies": { "undici-types": "~7.19.0" } }, "sha512-+qIYRKdNYJwY3vRCZMdJbPLJAtGjQBudzZzdzwQYkEPQd+PJGixUL5QfvCLDaULoLv+RhT3LDkwEfKaAkgSmNQ=="],
+
+    "bun-types": ["bun-types@1.3.13", "", { "dependencies": { "@types/node": "*" } }, "sha512-QXKeHLlOLqQX9LgYaHJfzdBaV21T63HhFJnvuRCcjZiaUDpbs5ED1MgxbMra71CsryN/1dAoXuJJJwIv/2drVA=="],
+
+    "crelt": ["crelt@1.0.6", "", {}, "sha512-VQ2MBenTq1fWZUH9DJNGti7kKv6EeAuYr3cLwxUWhIu1baTaXh4Ib5W2CqHVqib4/MqbYGJqiL3Zb8GJZr3l4g=="],
+
+    "prettier": ["prettier@3.8.3", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-7igPTM53cGHMW8xWuVTydi2KO233VFiTNyF5hLJqpilHfmn8C8gPf+PS7dUT64YcXFbiMGZxS9pCSxL/Dxm/Jw=="],
+
+    "style-mod": ["style-mod@4.1.3", "", {}, "sha512-i/n8VsZydrugj3Iuzll8+x/00GH2vnYsk1eomD8QiRrSAeW6ItbCQDtfXCeJHd0iwiNagqjQkvpvREEPtW3IoQ=="],
+
+    "typescript": ["typescript@6.0.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw=="],
+
+    "undici-types": ["undici-types@7.19.2", "", {}, "sha512-qYVnV5OEm2AW8cJMCpdV20CDyaN3g0AjDlOGf1OW4iaDEx8MwdtChUp4zu4H0VP3nDRF/8RKWH+IPp9uW0YGZg=="],
+
+    "w3c-keyname": ["w3c-keyname@2.2.8", "", {}, "sha512-dpojBhNsCNN7T82Tm7k26A6G9ML3NkhDsnw9n/eoxSRlVBB4CEtIQ/KTCLI2Fwf3ataSXRhYFkQi3SlnFwPvPQ=="],
+  }
+}