DOCSEARCHbyAlgolia
Submit Docs

Eclipse Langium

repository·main·Indexed 21 days ago

https://github.com/eclipse-langium/langium

A TypeScript-based framework for building language tools such as compilers, interpreters, and DSLs, featuring native support for the Language Server Protocol (LSP). The framework includes a Yeoman-based package generator for scaffolding extensions and provides capabilities for creating CLI tools, cross-language references, and VS Code integrations.

Tokens
32.5K
Snippets
80
Records
134
Agent score
72%

What's inside Eclipse Langium

  1. What is Langium?

    main

    Eclipse Langium is a next-generation language engineering framework for TypeScript. It is designed to build programming languages, domain-specific languages (DSLs), code generators, interpreters, and compilers.

    Key features include:

    • Semantics First: Build abstract models in parallel to syntax using a grammar declaration language. Parsers are powered by Chevrotain.
    • Customizable Infrastructure: Uses a dependency injection system to allow fine-tuning of language details.
    • LSP Support: Built-in support for the Language Server Protocol (LSP), allowing languages to run in IDEs, browsers, CLIs, or server applications.

  3. Integrate Langium and Sprotty

    main

    This package provides glue code to connect a Langium-based language with Sprotty diagrams. It enables generating diagram models from a Langium AST, automatically updating diagrams in response to document changes, and hooking into the JSON-RPC channel used by the language server.

    To display these diagrams in VS Code, use the sprotty-vscode package, which provides the necessary webview integration and connects to the language's JSON-RPC stream.

  4. Structure of the minimal CLI package

    main

    A minimal Langium CLI package typically contains the following files:

    • package.json: The manifest file for the CLI package.
    • tsconfig.src.json: Package-specific TypeScript configuration extending the base config.
    • tsconfig.json: TypeScript configuration required for VSCode functionality.
    • bin/cli/cli.js: The executable script referenced in package.json used to run the CLI.
    • src/cli/main.ts: The main entry point for the language's CLI.
    • src/cli/generator.ts: The code generator logic used to write output files from DSL documents.
    • src/cli/util.ts: Utility functions used by the CLI.

  5. Understand the Langium generated workspace structure

    main

    When you use the Langium Package Generator, the resulting project is organized as a monorepo within a packages directory. The specific contents of this directory depend on the options you selected during the generation process.

    Core Packages

    • packages/language: Mandatory. This package contains the core language definition (grammar, services, etc.).

    Optional Packages

    • packages/cli: Included only if you opted to generate a Command-Line Interface (CLI).
    • packages/extension: Included only if you opted to generate a VSCode extension.

  7. Understand the structure of a mandatory language package

    main

    When building a language with Langium, the mandatory language package contains the core grammar, AST, and service definitions. The following files constitute the standard structure of this package:

    Core Implementation Files

    • src/<language-id>.langium: The grammar definition of your language.
    • src/<language-id>-module.ts: The dependency injection module. Use this to register overridden or additional services.
    • src/<language-id>-validator.ts: An example validator file where you implement your language's semantic rules.
    • src/index.ts: The entry point that defines which parts of the package are exported to other packages.

    Generated Files (via langium generate)

    These files are automatically produced by the Langium generator:

    • src/generated/ast.ts: The Abstract Syntax Tree (AST) definitions.
    • src/generated/grammar.ts: The generated grammar implementation.
    • src/generated/module.ts: The generated dependency injection module.

    Syntax Highlighting

    • src/syntaxes/<language-id>.monarch.ts: Monarch-based syntax highlighting instructions.
    • syntaxes/<language-id>.tmLanguage.json: Textmate-based syntax highlighting instructions.

    Configuration

    • package.json: The manifest file for the language package.
    • tsconfig.json: The package-specific TypeScript configuration, extending the base project config.

    If testing was enabled during generation, the package also includes:

    • tsconfig.test.json: TypeScript configuration for unit tests.
    • test/linking.test.ts: Tests for the linking phase.
    • test/parsing.test.ts: Tests for the parsing phase.
    • test/validating.test.ts: Tests for the validation phase.

  8. Implement cross-language references and integration

    main

    This example demonstrates how to integrate two separate languages so they can interact. This is achieved by:

    1. Shared Grammars: Using a common grammar file (e.g., common.langium) that is included in both main language grammars.
    2. Cross-Language References: Defining one language (e.g., tests.langium) to include and reference elements from another language (e.g., requirements.langium).
    3. Unified Services: Using a factory function (e.g., createRequirementsAndTestsLangServices) to create a complete set of services that support both languages simultaneously for use in a CLI or Language Server.
    4. Cross-Language Validation: Implementing validators that check relationships across models, such as verifying if a Requirement defined in one file is covered by a TestCase defined in another.

  9. Understand the structure of a Langium language package with tests

    main

    If the test option was selected during package generation, the following additional files are included in the package:

    • tsconfig.test.json: The TypeScript compiler configuration for unit tests, extending tsconfig.src.json.
    • test/linking.test.ts: Unit tests specifically for checking linking.
    • test/parsing.test.ts: Unit tests regarding parsing.
    • test/validating.test.ts: Unit tests regarding validation.

  10. Language Features in VS Code

    main

    When using the Langium VS Code extension, the following language features are available for .langium files:

    • Syntax highlighting: Visual distinction of grammar elements.
    • Completion: Intelligent code completion for grammar rules.
    • Diagnostics: Real-time error reporting and warnings.
    • Code actions: Quick fixes and refactoring suggestions.
    • Go to definition: Navigation to rule definitions.
    • Find references: Locating all usages of a specific rule.
    • Document highlighting: Highlighting matching symbols within a document.
    • Document symbols: Outline view of the document structure.
    • Semantic tokens highlighting: Highlighting based on the semantic meaning of tokens.

  11. Understand the structure of a Langium language package

    main

    A Langium language package follows a specific structure containing the grammar, generated code, and configuration files. When using the Langium Package Generator, the following files are created as part of the mandatory language package:

    Core Implementation Files

    • src/<language-id>.langium: The grammar definition of your language.
    • src/<language-id>-module.ts: The dependency injection module. Use this to register overridden or additional services.
    • src/<language-id>-validator.ts: An example validator file that should be customized to reflect your language's semantics.
    • src/index.ts: The entry point that defines what is exported to other packages.

    Generated Files (via langium generate)

    These files are automatically produced by the Langium CLI and should not be edited manually:

    • src/generated/ast.ts: The Abstract Syntax Tree (AST) definitions.
    • src/generated/grammar.ts: The generated grammar code.
    • src/generated/module.ts: The generated dependency injection module.

    Syntax Highlighting

    • src/syntaxes/<language-id>.monarch.ts: Monarch-based syntax highlighting instructions.
    • syntaxes/<language-id>.tmLanguage.json: TextMate-based syntax highlighting instructions.

    Configuration

    • package.json: The manifest file for the language package.
    • tsconfig.json: The package-specific TypeScript configuration, extending the base configuration.

  12. How Langium works: Grammar, AST, and LSP

    main

    Langium is a language engineering tool built around a grammar declaration language. You use this grammar to describe three core aspects of your language:

    • Tokens: Keywords and terminal rules.
    • Syntax: Parser rules.
    • Abstract Syntax Tree (AST): The structure of the language.

    Key Features

    • Code Generation: The langium-cli can read your grammar declaration and generate TypeScript type declarations for the AST and other necessary components.
    • LSP Support: Langium has built-in support for the Language Server Protocol (LSP) via vscode-languageserver. You can register additional message handlers or extend the protocol directly.
    • Extensibility: The core logic is organized into services connected via Dependency Injection (DI). You can override default functionality or add custom service classes by providing your own DI module.