From 34ca10e7d5bff5f971feef8e4c162efce2a6dde0 Mon Sep 17 00:00:00 2001 From: Georg Schwarz Date: Fri, 12 Jan 2024 15:04:33 +0100 Subject: [PATCH 1/2] Add section to docs speaking about relation of langium files and generated AST node files --- apps/docs/docs/dev/03-architecture-overview.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/apps/docs/docs/dev/03-architecture-overview.md b/apps/docs/docs/dev/03-architecture-overview.md index cb4576fa2..bac01768f 100644 --- a/apps/docs/docs/dev/03-architecture-overview.md +++ b/apps/docs/docs/dev/03-architecture-overview.md @@ -12,6 +12,14 @@ On the pure language side, the central project is the [language server](https:// It contains the syntax definition (i.e. the grammar) and is capable of performing static semantic analysis on models, so invalid models can be rejected and errors are reported to the user. It uses the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) for communicating with IDEs in order to provide common features such as diagnostics, auto completion and much more. +**Note:** The [Langium framework](https://langium.org/) generate TypeScript files for the AST based on the grammar specification. +The following locations might be especially helpful to understand the grammar and its AST: + +- The Langium grammar files (see [here](https://github.com/jvalue/jayvee/tree/main/libs/language-server/src/grammar) or locally at `libs/language-server/src/grammar`; with `.langium` file ending). These files define the **syntax of the language**. +- The generate TypeScript AST files (execute `npm run generate` to generate them at `libs/language-server/src/lib/ast/generated` in your local repository). These files include **AST node interfaces** (e.g., `BlockDefinition`) and **guard methods** (e.g., `isBlockDefinition`). + They reflect the input of the grammar files regarding naming. +- The remaining source files of the language server implement the LSP and the additional validations beyond the syntax of Jayvee. + ## Interpreter The Jayvee [interpreter](https://github.com/jvalue/jayvee/tree/main/apps/interpreter) on the other hand is capable of running Jayvee models. From 23c1e18e505f34a2277039b5ae74a7cad5138f3b Mon Sep 17 00:00:00 2001 From: Georg Schwarz Date: Mon, 15 Jan 2024 14:23:21 +0100 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Philip Heltweg --- apps/docs/docs/dev/03-architecture-overview.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/apps/docs/docs/dev/03-architecture-overview.md b/apps/docs/docs/dev/03-architecture-overview.md index bac01768f..b609a6135 100644 --- a/apps/docs/docs/dev/03-architecture-overview.md +++ b/apps/docs/docs/dev/03-architecture-overview.md @@ -12,13 +12,13 @@ On the pure language side, the central project is the [language server](https:// It contains the syntax definition (i.e. the grammar) and is capable of performing static semantic analysis on models, so invalid models can be rejected and errors are reported to the user. It uses the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) for communicating with IDEs in order to provide common features such as diagnostics, auto completion and much more. -**Note:** The [Langium framework](https://langium.org/) generate TypeScript files for the AST based on the grammar specification. +**Note:** The [Langium framework](https://langium.org/) generate TypeScript files for the abstract syntax tree (AST), based on the grammar specification. The following locations might be especially helpful to understand the grammar and its AST: - The Langium grammar files (see [here](https://github.com/jvalue/jayvee/tree/main/libs/language-server/src/grammar) or locally at `libs/language-server/src/grammar`; with `.langium` file ending). These files define the **syntax of the language**. -- The generate TypeScript AST files (execute `npm run generate` to generate them at `libs/language-server/src/lib/ast/generated` in your local repository). These files include **AST node interfaces** (e.g., `BlockDefinition`) and **guard methods** (e.g., `isBlockDefinition`). +- The generated TypeScript AST files (execute `npm run generate` to generate them at `libs/language-server/src/lib/ast/generated` in your local repository). These files include **TypeScript interfaces for AST nodes** (e.g., `BlockDefinition`) and **guard methods** (e.g., `isBlockDefinition`). They reflect the input of the grammar files regarding naming. -- The remaining source files of the language server implement the LSP and the additional validations beyond the syntax of Jayvee. +- The remaining source files of the language server implement the language server protocol (LSP) and the additional validations beyond the syntax of Jayvee. ## Interpreter