Langium

https://langium.org/docs
Admin
Langium is an open source language engineering tool with first-class support for the Language Server...
Tokens:81,749
Snippets:684
Trust Score:7.6
Update:1 day ago
Show doc for...
Tokens:
Raw
### Install Yeoman and Langium generator with npm

Source: https://langium.org/docs/learn/workflow/install/

Run this command to globally install Yeoman and the Langium extension generator. Requires Node.js version 16 or higher. Recommended to have Visual Studio Code installed for the getting started example.

```bash
npm i -g yo generator-langium
```

--------------------------------

### Example of hello-world language content

Source: https://langium.org/docs/learn/workflow/scaffold/

A quick example showing the two entity types (`person` and `Hello`) accepted by the generated `hello-world` language. This is a sample file with the `.hello` extension.

```text
person Alice
Hello Alice!

person Bob
Hello Bob!

```

--------------------------------

### Implementation greetings.hello

Source: https://langium.org/docs/recipes/multiple-languages/

Example content for the greetings.hello file, showing expected output.

```text
Hello Markus!
Hello Michael!
```

--------------------------------

### Install esbuild as a dev dependency

Source: https://langium.org/docs/learn/minilogo/building_an_extension/

Run this command to install esbuild as a dev dependency, which is required for the esbuild-base script to work.

```bash
npm i --save-dev esbuild
```

--------------------------------

### MiniLogo definition syntax example

Source: https://langium.org/docs/learn/minilogo/writing_a_grammar/

Shows the concrete syntax for definitions with parameters and a block of statements.

```minilogo
def myDef() {
    ...
}
...
def anotherDef(x,y,z) {
    ...
}
```

--------------------------------

### Example .hello File

Source: https://langium.org/docs/recipes/validation/dependency-loops/

A sample input file for the greeting DSL. The expected order from the topological sort is Homer, Brain, Pinky, Marge.

```plaintext
person Homer
person Marge

person Pinky
person Brain

Homer greets Marge!
Brain greets Pinky!
Pinky greets Marge!
```

--------------------------------

### Install graphology packages

Source: https://langium.org/docs/recipes/validation/dependency-loops/

Install the required graphology packages: `graphology` for the data structure, `graphology-components` for strongly-connected component search, and `graphology-dag` for topological sort.

```bash
npm install graphology graphology-components graphology-dag
```

--------------------------------

### Configuration thats.me

Source: https://langium.org/docs/recipes/multiple-languages/

Example content for the thats.me file, specifying who you are.

```text
I am Markus.
```

--------------------------------

### Macro concrete syntax example

Source: https://langium.org/docs/learn/minilogo/writing_a_grammar/

Shows the intended concrete syntax for macros in MiniLogo, with optional arguments.

```minilogo
myMacro()
...
anotherMacro(1, 2, 3 * 3)
```

--------------------------------

### Simple dependency resolution example

Source: https://langium.org/docs/recipes/validation/dependency-loops/

Shows a class hierarchy with no loops and the resulting resolution order using depth-first search.

```java
public class A {}            //add A
public class B extends A {}  //add A -> B
public class C extends A {}  //add A -> C
public class D extends C {}  //add C -> D
public class E extends C {}  //add C -> E

//resolution: A, (B or (C, (D or E)))
```

--------------------------------

### Hello-World input file

Source: https://langium.org/docs/learn/workflow/generate_ast/

Example input file for the Hello-World language from the Yeoman generator. This input is used to produce the syntax tree shown in the next snippet.

```text
person John
person Jane

Hello John!
Hello Jane!
```

--------------------------------

### Original grammar from hello-world example

Source: https://langium.org/docs/recipes/multiple-languages/

The original Langium grammar from the hello-world example, generated by Langium's Yeoman generator. It defines a Model with persons and greetings.

```langium
grammar MultipleLanguages

entry Model:
    (persons+=Person | greetings+=Greeting)*;

Person:
    'person' name=ID;

Greeting:
    'Hello' person=[Person:ID] '!';

hidden terminal WS: /\s+/;
terminal ID: /[_a-zA-Z][\w_]*/;
terminal INT returns number: /[0-9]+/;
terminal STRING: /"(\\.|[^"\\])*"|'(\\.|[^'\\])*'/;

hidden terminal ML_COMMENT: /\/\*[\s\S]*?\*\//;
hidden terminal SL_COMMENT: /\/\/[^\n\r]*/; 

```

--------------------------------

### Example import and greeting file with reference errors

Source: https://langium.org/docs/recipes/scoping/file-based/

This file imports persons from 'persons.hello' and greets them. It demonstrates reference errors for non-exported persons, invalid imports, and renamed imports.

```plain
import { 
    Marge,
    Homer,
    Lisa, //reference error, because not exported
    Maggy as Baby
} from "persons.hello"

Hello Lisa! //reference error, because no valid import
Hello Maggy! //reference error, because name was overwritten with 'Baby'
Hello Homer!
Hello Marge!
Hello Baby!
```

--------------------------------

### Cross-reference example with Person and Greeting

Source: https://langium.org/docs/reference/grammar-language/

Shows a cross-reference where 'Greeting' references a 'Person' object by its 'ID'. The example parses 'person Bob' and 'Hello Bob !' successfully, but fails for 'Hello Sara !' because no Person named 'Sara' is defined.

```langium
Person:
    'person' name=ID;
Greeting:
    'Hello' person=[Person:ID] '!';
```

```plain
person Bob
Hello Bob !
```

```plain
person Bob
Hello Sara !
```

--------------------------------

### Example of member-based scoping in TypeScript

Source: https://langium.org/docs/recipes/scoping/class-member/

Shows a simple TypeScript example of member access on class instances, illustrating the concept of member scoping.

```ts
class A {
    b: B;
}

class B {
    value: string;
}

function test(): void {
    const a = new A();
    const b = a.b; // Refers to the `b` defined in class `A`
    const value = b.value; // Refers to the `value` defined in class `B`
}
```

--------------------------------

### Example .hello file with greeting loops

Source: https://langium.org/docs/recipes/validation/dependency-loops/

A sample `.hello` file that triggers three greeting loop errors: Homer greets Marge, Marge greets Brain, and Brain greets Homer. Pinky greets Marge is valid.

```plaintext
person Homer
person Marge
person Pinky
person Brain

Homer greets Marge! //error
Marge greets Brain! //error
Brain greets Homer! //error
Pinky greets Marge!
```

--------------------------------

### MiniLogo example program (test.logo)

Source: https://langium.org/docs/learn/minilogo/customizing_cli/

A simple MiniLogo program that defines a test function and calls it. Save this as test.logo in the project root to validate with the CLI.

```minilogo
def test() {
    pen(down)
    move(10,10)
    pen(up)
}

test()
```

--------------------------------

### Run CLI parseAndValidate on examples/test.logo

Source: https://langium.org/docs/learn/minilogo/customizing_cli/

If test.logo is placed in an examples subdirectory, use this command instead. The location of .logo files is flexible.

```bash
./bin/cli parseAndValidate examples/test.logo
```

--------------------------------

### package.json script for browser worker build

Source: https://langium.org/docs/recipes/code-bundling/

A smaller esbuild setup to bundle a Langium language server for the browser, outputting an IIFE worker file.

```js
"scripts": {
  "build:worker": "esbuild ./src/main.ts --bundle --format=iife --outfile=./public/languageServerWorker.js"
}
```

--------------------------------

### Example persons.hello file with Simpsons family

Source: https://langium.org/docs/recipes/scoping/file-based/

This file defines persons with export flags. Only those marked 'export' are visible to other files. It is used to test the editor after building with 'npm run build'.

```plain
export person Homer
export person Marge
person Bart
person Lisa
export person Maggy
```

--------------------------------

### Simple loop detection example

Source: https://langium.org/docs/recipes/validation/dependency-loops/

Shows a class hierarchy where class C extends A, creating a loop. The comment marks the error.

```java
public class A extends B {}
public class B extends C {}
public class C extends A {} //error
```

--------------------------------

### HelloWorldScopeProvider implementation

Source: https://langium.org/docs/learn/workflow/resolve_cross_references/

Custom scope provider for the Hello-World example. It handles cross-references from greetings to persons by collecting all persons from the document and creating a MapScope. Returns EMPTY_SCOPE for other references. Requires overriding the default scope provider in the language module.

```TypeScript
import { ReferenceInfo, Scope, ScopeProvider, AstUtils, LangiumCoreServices, AstNodeDescriptionProvider, MapScope, EMPTY_SCOPE } from "langium";
import { isGreeting, isModel } from "./generated/ast.js";

export class HelloWorldScopeProvider implements ScopeProvider {
    private astNodeDescriptionProvider: AstNodeDescriptionProvider;
    constructor(services: LangiumCoreServices) {
        //get some helper services
        this.astNodeDescriptionProvider = services.workspace.AstNodeDescriptionProvider;
    }
    getScope(context: ReferenceInfo): Scope {
        //make sure which cross-reference you are handling right now
        if(isGreeting(context.container) && context.property === 'person') {
            //Success! We are handling the cross-reference of a greeting to a person!

            //get the root node of the document
            const model = AstUtils.getContainerOfType(context.container, isModel)!;
            //select all persons from this document
            const persons = model.persons;
            //transform them into node descriptions
            const descriptions = persons.map(p => this.astNodeDescriptionProvider.createDescription(p, p.name));
            //create the scope
            return new MapScope(descriptions);
        }
        return EMPTY_SCOPE;
    }
}
```

--------------------------------

### Test parser with parseHelper

Source: https://langium.org/docs/learn/workflow/generate_ast/

TypeScript example using `parseHelper` from `langium/test` to parse a Hello-World input and assert the AST structure. The cross-reference checks will fail at this point because cross-references are not resolved yet.

```typescript
import { createHelloWorldServices } from "./your-project//hello-world-module.js";
import { EmptyFileSystem } from "langium";
import { parseHelper } from "langium/test";
import { Model } from "../../src/language/generated/ast.js";

//arrange
const services = createHelloWorldServices(EmptyFileSystem);
const parse = parseHelper<Model>(services.HelloWorld);

//act
const document = await parse(`
    person John
    person Jane
    
    Hello John!
    Hello Jane!
`);

//assert
const model = document.parseResult.value;
expect(model.persons).toHaveLength(2);
expect(model.persons[0].name).toBe("John");
expect(model.persons[1].name).toBe("Jane");
expect(model.greetings).toHaveLength(2);
//be aware of the fact that the following checks will fail at this point, because the cross-references are not resolved yet
expect(model.greetings[0].person.ref?.name).toBe("John");
expect(model.greetings[1].person.ref?.name).toBe("Jane");
```

--------------------------------

### Invalid Hello-World input file

Source: https://langium.org/docs/learn/workflow/create_validations/

Example input file that violates the semantic rule: John is greeted twice. The comment indicates the expected error message.

```text
person John
person Jane

Hello John!
Hello Jane!
Hello John! //should throw: You can great each person at most once! This is the 2nd greeting to John.
```

--------------------------------

### Hello-World grammar definition

Source: https://langium.org/docs/learn/workflow/write_grammar/

The complete grammar from the Hello-World example generated by the Yeoman generator. It defines the grammar name, hidden whitespace terminal, identifier terminal, entry rule, and two parser rules with a cross reference.

```langium
grammar HelloWorld

hidden terminal WS: /\s+/;
terminal ID: /[_a-zA-Z][\w]*/;

entry Model: (persons+=Person | greetings+=Greeting)*;

Person:
    'person' name=ID;

Greeting:
    'Hello' person=[Person] '!';

```

--------------------------------

### Python list example showing indentation to ignore

Source: https://langium.org/docs/recipes/lexing/indentation-sensitive-languages/

Example of a Python list where indentation between '[' and ']' should be ignored by the token builder.

```Python
x = [
    1,
    2
]
```

--------------------------------

### Open project in VS Code

Source: https://langium.org/docs/learn/workflow/scaffold/

Opens the newly created Langium project in VS Code using the `code` command. Replace `hello-world` with your chosen project name.

```bash
code hello-world

```

--------------------------------

### Test linking by comparing resolved references

Source: https://langium.org/docs/learn/workflow/resolve_cross_references/

Example test that parses a document and asserts that the resolved references match the expected model elements. Uses parseHelper from langium/test and any assertion library (the Hello World example uses Vitest).

```TypeScript
import { createHelloWorldServices } from "./your-project//hello-world-module.js";
import { EmptyFileSystem } from "langium";
import { parseHelper } from "langium/test";
import { Model } from "../../src/language/generated/ast.js";

//arrange
const services = createHelloWorldServices(EmptyFileSystem);
const parse = parseHelper<Model>(services.HelloWorld);

//act
const document = await parse(`
    person John
    person Jane
    
    Hello John!
    Hello Jane!
`);

//assert
const model = document.parseResult.value;
expect(model.persons).toHaveLength(2);
expect(model.greetings).toHaveLength(2);
expect(model.greetings[0].person.ref).toBe(model.persons[0]);
expect(model.greetings[1].person.ref).toBe(model.persons[1]);
```

--------------------------------

### Definition people.who

Source: https://langium.org/docs/recipes/multiple-languages/

Example content for the people.who file, listing persons.

```text
person Markus
person Michael
person Frank
```

--------------------------------

### Build and run CLI to generate commands

Source: https://langium.org/docs/learn/minilogo/generation/

Commands to build the project and run the CLI to generate commands from a MiniLogo file. The output is written to generated/test.json.

```bash
npm run build
./bin/cli generate test.logo
```

--------------------------------

### Service class with dependencies

Source: https://langium.org/docs/reference/configuration-services/

Example `ServiceClass` that receives `ArithmeticsServices` in its constructor and stores references to dependent services.

```typescript
export class ServiceClass {
    private readonly serviceOne: ServiceOne;
    private readonly serviceTwo: ServiceTwo;
    private readonly serviceN: ServiceN;

    constructor(services: ArithmeticsServices) {
        this.serviceOne = services.ServiceOne;
        this.serviceTwo = services.Group.ServiceTwo;
        this.serviceN = services.Group.SubGroup.ServiceN;
    }
    /* service logic */
}
```

--------------------------------

### Negated Token: NONO (EBNF)

Source: https://langium.org/docs/reference/grammar-language/

Matches a word that does not start with 'no' using a negated token and character ranges.

```langium
terminal NONO: (!'no')('a'..'z'|'A'..'Z')+;
```

--------------------------------

### Syntax tree diagram for Hello-World input

Source: https://langium.org/docs/learn/workflow/generate_ast/

Mermaid graph showing the syntax tree generated by Langium for the Hello-World input. Note the question marks (?) for cross-references inside the greetings, which are not resolved yet.

```mermaid
graph TB
  Model-->persons
  Model-->greetings
  
  persons-->P1[Person]
  P1 --> H1('person')
  P1 --> N1[name]
  N1 --> NL1('John')
  
  persons-->P2[Person]
  P2 --> H2('person')
  P2 --> N2[name]
  N2 --> NL2('Jane')

  greetings-->G1[Greeting]
  G1 --> KW1('hello')
  G1 --> PRef1[Ref]
  G1 --> EM1('!')
  PRef1 --> QM1{?}

  greetings-->G2[Greeting]
  G2 --> KW2('hello')
  G2 --> PRef2[Ref]
  G2 --> EM2('!')
  PRef2 --> QM2{?}
```

--------------------------------

### Activate extension on builtin file system

Source: https://langium.org/docs/recipes/builtin-library/

Adds the 'onFileSystem:builtin' activation event to package.json so the extension activates when any builtin file is opened. This ensures the file system provider is registered before any DSL file is opened.

```JSON
"activationEvents": [
    "onFileSystem:builtin"
]
```

--------------------------------

### Unassigned rule call example

Source: https://langium.org/docs/reference/grammar-language/

Shows an unassigned rule call where 'AbstractDefinition' does not create an object but delegates to either 'Definition' or 'DeclaredParameter'.

```langium
AbstractDefinition:
	Definition | DeclaredParameter;
```

--------------------------------

### Tree-rewriting action example

Source: https://langium.org/docs/reference/grammar-language/

Langium grammar using a tree-rewriting action '{Addition.left=current}' to clean the tree and create an 'Addition' node when a '+' is found.

```langium
Addition returns Expression:
    SimpleExpression ({Addition.left=current} '+' right=SimpleExpression)*;

SimpleExpression:
    '(' Addition ')' | value=INT;
```

--------------------------------

### Build the CLI with npm run langium:generate and npm run build

Source: https://langium.org/docs/learn/minilogo/customizing_cli/

Run these commands from the project root to generate the language module and build the CLI. This is necessary after changing the grammar or generator code.

```bash
npm run langium:generate
npm run build
```

--------------------------------

### Define Expr rule as Add

Source: https://langium.org/docs/learn/minilogo/writing_a_grammar/

Starts the expression hierarchy by defining the Expr rule to be the Add rule. This is the entry point for parsing expressions.

```langium
Expr: Add;
```

--------------------------------

### Test input file

Source: https://langium.org/docs/recipes/performance/caches/

Create a .hello file with these persons to test the validation. The line 'person Homer' will trigger a warning about an unknown publisher.

```plaintext
person Wonderwoman
person Spiderman
person Homer //warning: unknown publisher!!
person Obelix
```

--------------------------------

### Resolving ambiguity with keywords

Source: https://langium.org/docs/reference/grammar-language/

Adds keywords `'student'` and `'teacher'` to the parser rules to resolve the ambiguity from the previous example. The parser can now differentiate between `Student` and `Teacher`.

```langium
Student:
    'student' name=ID;

Teacher:
    'teacher' name=ID;

Person:
    Student | Teacher;
```

--------------------------------

### Unordered group example

Source: https://langium.org/docs/reference/grammar-language/

A Langium grammar rule using the '&' operator to allow properties in any order. The 'Person' rule now accepts 'name' and 'age' in any order.

```langium
Person:
    'person' name=ID & age=INT
```

--------------------------------

### Add vscode:prepublish and esbuild-base scripts to package.json

Source: https://langium.org/docs/learn/minilogo/building_an_extension/

Add these scripts to your package.json to prepare and bundle the extension. The esbuild-base script bundles the extension entry point (src/extension/main.ts) into out/main.js, excluding the vscode module, and is used by vscode:prepublish with minification and linting.

```json
{
    ...
    "vscode:prepublish": "npm run esbuild-base -- --minify && npm run lint",
    "esbuild-base": "esbuild ./src/extension/main.ts --bundle --outfile=out/main.js --external:vscode --format=cjs --platform=node",
    ...
}
```

--------------------------------

### Ordered group example

Source: https://langium.org/docs/reference/grammar-language/

A Langium grammar rule where properties must appear in the exact order declared. The 'Person' rule requires 'name' before 'age'.

```langium
Person:
    'person' name=ID age=INT
```

--------------------------------

### Function call graph with resolution order

Source: https://langium.org/docs/recipes/validation/dependency-loops/

Shows a set of C functions with dependencies, and the expected build order: answer42, bar1, bar2, foo.

```c
void answer42() {
    printf("42\n");
}
void bar1() {
    answer42();
}
void foo() {
    bar1();
    bar2();
}
void bar2() {
    answer42();
}
```

--------------------------------

### Initial langium-config.json

Source: https://langium.org/docs/recipes/multiple-languages/

The initial Langium configuration file for a single language, before splitting into multiple languages.

```json
{
    "projectName": "MultipleLanguages",
    "languages": [{
        "id": "multiple-languages",
        "grammar": "src/language/multiple-languages.langium",
        "fileExtensions": [".hello"],
        "textMate": {
            "out": "syntaxes/multiple-languages.tmLanguage.json"
        },
        "monarch": {
            "out": "syntaxes/multiple-languages.monarch.ts"
        }
    }],
    "out": "src/language/generated"
}

```

--------------------------------

### Package import dependency graph and resolution

Source: https://langium.org/docs/recipes/validation/dependency-loops/

Shows a dependency graph of packages (A, B, C, D) and the expected loop-free resolution order: A, B, C, D.

```plaintext
A -> B -> C
A -> C
C -> D

//resolution: A, B, C, D
```

--------------------------------

### package.json contributes before change (single language)

Source: https://langium.org/docs/recipes/multiple-languages/

Original 'contributes' section in package.json defining one language and one grammar before adding multiple languages.

```json
//...
"contributes": {
    "languages": [
        {
            "id": "multiple-languages",
            "aliases": [
                "Multiple Languages",
                "multiple-languages"
            ],
            "extensions": [".hello"],
            "configuration": "./language-configuration.json"
        }
    ],
    "grammars": [
        {
            "language": "multiple-languages",
            "scopeName": "source.multiple-languages",
            "path": "./syntaxes/multiple-languages.tmLanguage.json"
        }
    ]
},
//...
```

--------------------------------

### Expected JSON output from generator

Source: https://langium.org/docs/learn/minilogo/generation/

The JSON array of drawing commands produced by the generator for the example MiniLogo program. It contains penDown, move, and penUp commands.

```json
[
  {
    "cmd": "penDown"
  },
  {
    "cmd": "move",
    "x": 10,
    "y": 10
  },
  {
    "cmd": "penUp"
  }
]
```

--------------------------------

### Modified Hello World grammar with import/export

Source: https://langium.org/docs/recipes/scoping/file-based/

This grammar adds FileImport and PersonImport rules to support importing persons from other files, and an optional 'export' keyword on Person to make symbols available for import. After changing the grammar, you must regenerate the AST and language infrastructure.

```langium
grammar HelloWorld

entry Model:
    (
        fileImports+=FileImport  //NEW: imports per file
        | persons+=Person
        | greetings+=Greeting
    )*;

FileImport: //NEW: imports of the same file are gathered in a list
    'import' '{' 
        personImports+=PersonImport (',' personImports+=PersonImport)* 
    '}' 'from' file=STRING; 

PersonImport:
    person=[Person:ID] ('as' name=ID)?;

Person:
    published?='export'? 'person' name=ID; //NEW: export keyword

type Greetable = PersonImport | Person

Greeting:
    'Hello' person=[Greetable:ID] '!';

hidden terminal WS: /\s+/;
terminal ID: /[_a-zA-Z][\w_]*/;
terminal STRING: /"(\\.|[^"\\])*"|'(\\.|[^'\\])*'/;

hidden terminal ML_COMMENT: /\/\*[\s\S]*?\*\//;
hidden terminal SL_COMMENT: /\/\/[^\n\r]*/;
```

--------------------------------

### isFor statement evaluation

Source: https://langium.org/docs/learn/minilogo/generation/

Handles for loops by computing bounds, creating a copied environment, and iterating while the start value is less than the end value, evaluating the body for each iteration.

```TypeScript
// compute for loop bounds
// start
let vi = evalExprWithEnv(stmt.e1, env);
// end
let ve = evalExprWithEnv(stmt.e2, env);

let results : (Object | undefined)[] = [];

// perform loop
const loopEnv = new Map(env);
while(vi < ve) {
    loopEnv.set(stmt.var.name, vi++);
    stmt.body.forEach(s => {
        results = results.concat(evalStmt(s, new Map(loopEnv)));
    });
}

return results;
```

--------------------------------

### Generate AST with npm run langium:generate

Source: https://langium.org/docs/learn/workflow/generate_ast/

Run this command in your terminal to generate the AST and other files into the `src/generated` directory. The Langium CLI creates a grammar file, a module file, an AST file, and syntax highlighting files.

```bash
npm run langium:generate
```

--------------------------------

### Interrupting expression group with hidden terminal symbols

Source: https://langium.org/docs/reference/grammar-language/

Shows that a sequence of expressions can be interrupted and resumed using hidden terminal symbols, such as comments. The example input is successfully parsed.

```text
paragraph "expression one" /* comment */ "expression two" 3
```
Tokens:
Raw