Understanding the Cross Reference feature

[theogiraudet]

Hello,

I'm interested in Langium and I am currently reading the documentation of the grammar, in particular the part about Cross References.
I don't really understand the difference between Greeting: 'Hello' person=[Person:ID] '!'; and Greeting: 'Hello' person=[Person] '!'; because in these two cases, Langium seems to use the property 'name' from the type Person.

I tried something like this to to identify the name by an integer:

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

but my extension returns this error: "Could not resolve reference to Person named '5'."
for the text

person 5 a
Hello 5!

Last test I do:

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

And this time, no error, even if I put a value that does not reference anything.

So I find it hard to understand the behavior of the cross-reference.
Would it be possible to explain it with examples?

Thanks!

[msujew]

HI @theogiraudet,

by default, Langium tries to infer the terminal which is used for the name property, which is why it can be omitted. In some cases, this behavior might not be intended. For example, if you want to reference elements in your DSL using a fully qualified name (FQN, dot separated IDs), although their name is simply ID. Then you would refer to it using person=[Person:FQN]. Examples can be found in the domain model grammar:

https://github.com/langium/langium/blob/8a1d1df07bbae6e2fb14f4f74ebe154402502038/examples/domainmodel/src/language-server/domain-model.langium#L25-L26

Regarding the INT issue at hand. This might be an oversight on our end, simply because we usually don't refer to other elements using an integer, but always use strings instead. I believe that internally we always expect a string as a cross reference, which is why your example simply doesn't resolve correctly. In particular, this comparison might be incorrect:

https://github.com/langium/langium/blob/8a1d1df07bbae6e2fb14f4f74ebe154402502038/packages/langium/src/references/scope.ts#L64-L66

It will probably try to compare a number and a string, and fails, which is why it doesn't resolve. I created a new issue #468 to track this.

[theogiraudet]

Thanks for the answer, it seems clearer to me :)

[ballcoach12]

I have a related question.

Given the following grammar rules:

entry TemplateLibrary:
    '<TemplateLibrary>'
        (templates+=Template)*
    '</TemplateLibrary>'
    '<TemplateRefs>'entries+=TemplateRef'</TemplateRefs>'
;
Template:
 '<Template' 
    'id' '=' name=STRING ('/>' | '>''</Template>')
  ; 

TemplateRef:
    '<TemplateRef' 'ref''=' ref=[Template] '/>';

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

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

If I try to parse the following:

<TemplateLibrary>
    <Template id="Bob"></Template>
</TemplateLibrary>
<TemplateRefs><TemplateRef  ref="Bob"  /></TemplateRefs>

I also get the error Could not resolve reference to Template named '"Bob"'.

I would expect the linker to infer the STRING type from the name property of the Template and resolve the reference. But it does not. Is there something that I am misunderstanding?

[ballcoach12]

@spoenemann , the previous example works for me as well. I think I made it overly simplistic in my attempt to make it small and reproducible. Here is a somewhat more complex grammar that demonstrates the problem that I am seeing:

grammar TestTemplate

entry TemplateLibrary:
    '<TemplateLibrary>'
        (templates+=Template)*
    '</TemplateLibrary>'
 ;

Template:
 '<Template' 
    'id' '=' name=STRING 
 '>'
    properties=TemplateProperties
    triggers=TemplateTriggers
  '</Template>' 
;
TemplateProperties:
    '<TemplateProperties>'(entries+=TemplateProperty)*'</TemplateProperties>'
;

TemplateTriggers:
    '<TemplateTriggers>' entries+=Trigger* '</TemplateTriggers>'
;
Trigger:
    '<Trigger' 'property' '=' property=[TemplateProperty]  'value' '=' value=STRING '>'
    '</Trigger>'
;

TemplateProperty:
'<TemplateProperty' 'name' '=' name=STRING  /*'defaultValue' '=' defaultValue=STRING*/ '/>'
;

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

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

with the following code:

<TemplateLibrary>
    <Template id="Bob">
        <TemplateProperties>
            <TemplateProperty name="Alan" />
        </TemplateProperties>
        <TemplateTriggers>
            <Trigger property="Alan" value="Steve"></Trigger>
        </TemplateTriggers>
    </Template>
</TemplateLibrary>

In this case, I get the error "Could not resolve reference to TemplateProperty name 'Alan'". I think the problem is actually with my grammar and not necessarily with Langium; I just can't figure out what it is. The TemplateProperty does not seem to be located by the linker, though.

[msujew]

@ballcoach12 I'm not 100% sure, but I believe it has to do with the local scoping that we perform. By default, objects can only be referenced either by children or siblings (or children of siblings). I.e:

{
  let x = 3;
  x = 42; // gets correctly resolved to `x`
}

{
  if (something) {
    let x = 3;
  }
  x = 42; // cannot resolve, x is declared in another local scope
}

Basically, each TemplateProperties rule has it's own local scoping context. Objects outside of this TemplateProperties element cannot reference objects inside of it. Consequently, no elements inside of TemplateTriggers can reference them.

See the domain-model example on how to export all elements to the global scope (if you want that).

[ballcoach12]

Thanks, @msujew. That was the direction I was beginning to go. I'll work on that.

[ballcoach12]

Just to confirm, the solution to my problem was to build a flat scope for the cross-references in my grammar. As you surmised, @msujew , I had multiple levels of containment in my AST, and had to assemble my scopes accordingly.

[msujew]

@ballcoach12 Great, good to know 👍