Declaring nodes when they're used

[stutrek]

At eraser.io, we're trying to adopt Langium for our diagram as code feature. Right now I'm working on our cloud architecture diagrams, and I'm running into an issue: nodes aren't automatically declared when they're being used.

A very simple example of our code looks like this:

// declare structure and nodes
My Cloud [icon: cloud] {
    API Gateway
    Worker 1 [icon: gear]
}

// make connections between nodes, optionally declaring them
Internet > API Gateway
API Gateway > Worker 1

My current problem is that it's legal to make a new node in the connections, but I can't figure out how to do this. In this example, the Internet node is not declared ahead of time, so it should be created when it's used.

This is my grammar, I have additional code that scopes all the nodes at the top level, since nesting comes automatically but is not desired for this use case.

grammar EraserDsl

entry Model:
    (nodes+=(Node) | connections+=(InitialConnection) | Newline)*;

Node:
    name=ID ('[' (settings+=Setting)* ']')? ('{' Newline* (children+=Node*)+ '}')? Newline+;

Setting:
    key=ID ':' value=ID|EscapedText ','?;

InitialConnection:
    (nodes+=[Node] ','?) connectionType=ConnectionToken (to+=SecondConnection)+;

SecondConnection:
    (nodes+=[Node] ','?) (':'message=ID)? connectionType=ConnectionToken?;

hidden terminal WS: /[ \t]+/;

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


terminal ID: /[^:{}[\]"<>,\n]*[^:{}[\]"<>,\n ]/;
terminal ConnectionToken: /[<>-]+/;
terminal EscapedText: /"[^"]+"/;
terminal Newline: /\n/;

Thanks!

[msujew]

Hey @stutrek,

We had to solve a very similar issue in our Langium based implementation of SQL. Generally, Langium uses the name property as a convention to make an element available for referencing. However, it doesn't actually have to be the name property explicitly, you can use any property to make an element visible, even a self reference.

For your use case, this requires essentially three parts:

1. Adjust the grammar to make elements of type InitialConnection and SecondConnection referencable:

Node:
    name=ID ('[' (settings+=Setting)* ']')? ('{' Newline* (children+=Node*)+ '}')? Newline+;

InitialConnection:
    (nodes+=[RefItem:ID] ','?) connectionType=ConnectionToken (to+=SecondConnection)+;

SecondConnection:
    (nodes+=[RefItem:ID] ','?) (':'message=ID)? connectionType=ConnectionToken?;

type RefItem = Node | InitialConnection | SecondConnection;

2. Give elements of type InitialConnection and SecondConnection a name by creating a specialized NameProvider. Note that there's also a different approach by using the ScopeComputation. For now, using the NameProvider should be good enough:

export class EraserNameProvider extends DefaultNameProvider {
  getName(node: AstNode): string | undefined {
    if (isInitialConnection(node) || isSecondConnection(node)) {
      return node.nodes.$refText; // Use the reference text as the name of the node
    } else {
      return super.getName(node);
    }
  }

  getNameNode(node: AstNode): CstNode | undefined {
    if (isInitialConnection(node) || isSecondConnection(node)) {
      return node.nodes.$refNode;
    } else {
      return super.getNameNode(node);
    }
  }
}

3. (this is an optional step, but might be useful) Ensure that in a given Scope actual Node objects are preferred over InitialConnection or SecondConnection elements with the same name. I'll only outline this in pseudo-code:

export class EraserScopeProvider extends DefaultScopeProvider {
  getScope(context: ReferenceInfo): Scope {
    if (context.property === 'nodes') { // a reference for the `nodes` property
      const superScope = super.getScope(context);
      const allElements = superScope.getAllElements();
      // Remove all element descriptions for `InitialConnection` and `SecondConnection`
      // which already have a matching `Node` element
      const filtered = filterWithPrecedence(allElements);
      return new StreamScope(filtered);
    } else {
      return super.getScope(context);
    }
  }
}

Don't forget to bind those services in the references part of the services module! I hope that helps you along :)

[stutrek]

note: this is marked as the answer, but there's more below!

[stutrek]

Thank you! This is very helpful!

I kept my ScopeProvider (pasted below) because it flattens the heirarchy. It filters to the first instance of a RefItem, whether that's a node or a connection, since the first instance is the declaration.

My next problem is with right click -> rename symbol. For nodes declared as nodes, it works great. When the declaration is in a connection, I get Error: Overlapping ranges are not allowed!. These are the ranges:

I suspect that somewhere there's a double entry.

export class EraserScopeProvider extends DefaultScopeProvider {
  override getScope(context: ReferenceInfo): Scope {
    if (context.property === 'nodes') {
      const scopes: Array<Stream<AstNodeDescription>> = [];
      const referenceType = this.reflection.getReferenceType(context);

      const precomputed = AstUtils.getDocument(context.container).precomputedScopes;

      if (precomputed) {
        const nodeDescriptions: AstNodeDescription[] = [];
        const found = new Set<string>();
        for (const scope of precomputed) {
          if (!found.has(scope[1].name)) {
            nodeDescriptions.push(scope[1]);
            found.add(scope[1].name);
          }
        }
        scopes.push(stream(nodeDescriptions));
      }

      let result: Scope = this.getGlobalScope(referenceType, context);
      for (let i = scopes.length - 1; i >= 0; i--) {
        result = this.createScope(scopes[i], result);
      }
      return result;
    }
    return super.getScope(context);
  }
}

[msujew]

@stutrek To determine all references of an element, the scoping service isn't used (it's only used during the cross reference resolving phase). The scope seems to work as expected. You might want to take a look at the References services and see what goes wrong there. It's the source of the renaming LSP service among others.