Embed the formal grammar to the language reference document

[SupunS]

Issue To Be Solved

Formal grammar can be used to check the syntactic validity of a given code (e.g: validate some edge cases against the grammar).

Language reference can be used to understand how the language and its semantics works.

Having both of these at one place makes it more convenient for the users, as they don't have to switch between two places.

Suggest A Solution

Suggestion is to embed the relevant part of the formal grammar to each of the section in the language reference.

A sample section would eventually looks like below:

Imports

importDeclaration
    : Import ( identifier ( ',' identifier )* From )?
      ( stringLiteral | HexadecimalLiteral | location=identifier )
    ;

Programs can import declarations (types, functions, variables, etc.) from other programs.

Imports are declared using the import keyword.

It can either be followed by a location, which imports all declarations; or it can be followed by the names of the declarations that should be imported, followed by the from keyword, and then followed by the location.

If importing a local file, the location is a string literal, and the path to the file.

 🚧 Status: Imports from local files are not currently implemented.

If importing an external type in a different account, the location is an address literal, and the address of the account where the declarations are deployed to and published.

// Import the type `Counter` from a local file.
//
import Counter from "examples/counter.cdc"

// Import the type `Counter` from an external account.
//
import Counter from 0x299F20A29311B9248F12

[turbolent]

So far the syntax is mainly described in a human-readable way, because not all developers are able to understand the grammar rule. I think it won't hurt to also add the grammar rule.

[turbolent]

We should maybe consider having the grammar in the language specification, the language reference is more targeted towards users, who are usually not familiar with grammars.