diff --git a/hugo/content/docs/introduction/_index.md b/hugo/content/docs/introduction/_index.md index 5b90020a..8bb8600b 100644 --- a/hugo/content/docs/introduction/_index.md +++ b/hugo/content/docs/introduction/_index.md @@ -12,11 +12,11 @@ If you need a more detailed list of Langium features, you can find them in the [ ### Try it out -If you want to see Langium in action, you can follow the [showcases](/showcase) or event the [playground](/playground). +If you want to see Langium in action, you can follow the [showcases](/showcase) or even the [playground](/playground). ### Learn Langium -If you are convinced with Langium and want to learn more about it, you can start with the [learn section](/docs/learn). +If you are convinced by Langium and want to learn more about it, you can start with the [learn section](/docs/learn). ### More details diff --git a/hugo/content/docs/learn/workflow/_index.md b/hugo/content/docs/learn/workflow/_index.md index abc24704..927253cc 100644 --- a/hugo/content/docs/learn/workflow/_index.md +++ b/hugo/content/docs/learn/workflow/_index.md @@ -38,9 +38,9 @@ This simple introduction can be seen as three main parts: * setting up your project environment (1.+2.): this is only done once * specifying the language features (3.-7.): this cycle you need to reiterate for each new language feature -* everything advanced (8.): here the limit of the common workflow is reached, for specific questions you can find answers in the [recipes](/docs/recipes). +* everything advanced (8.): The limit of the common workflow is reached here. For specific questions you can find answers in the [recipes](/docs/recipes). -While the first part is straight-forward. The last part is about advanced topics that differ from project to project. +While the first part is straight-forward, the last part is about advanced topics that differ from project to project. The middle part will be explained briefly in the following section. ## Initial setup @@ -57,7 +57,7 @@ After installing Yeoman, you can scaffold a new Langium project. ### [3. Write the grammar](/docs/learn/workflow/write_grammar) -The first step in the core workflow starts from the grammar. You will have some language feature in mind that you want to implement. The grammar is used to nail down the syntax of your features. You can use our Langium VS Code extension to get syntax highlighting and code completion for `.langium` files. If your grammar is free of errors, you can generate the files for the _abstract syntax tree (AST)_. +The first step in the core workflow starts with the grammar. You will have some language feature in mind that you want to implement. The grammar is used to nail down the syntax of your features. You can use our Langium VS Code extension to get syntax highlighting and code completion for `.langium` files. If your grammar is free of errors, you can generate the files for the _abstract syntax tree (AST)_. ### [4. Generate the AST](/docs/learn/workflow/generate_ast) diff --git a/hugo/content/docs/learn/workflow/resolve_cross_references.md b/hugo/content/docs/learn/workflow/resolve_cross_references.md index 65dc2fdc..d2903490 100644 --- a/hugo/content/docs/learn/workflow/resolve_cross_references.md +++ b/hugo/content/docs/learn/workflow/resolve_cross_references.md @@ -118,11 +118,11 @@ export interface Scope { #### Purpose -So, what is the purpose of the scope provider? As mentioned above: it visits each cross-reference and tries to find the corresponding AST nodes over the entire workspace, that can be a candidate for the cross-reference's place. It is important to understand that we do not decide here which of these nodes is the perfect match! That decision is part of the so-called linker of the Langium architecture. +So, what is the purpose of the scope provider? As mentioned above: it visits each cross-reference and tries to find the corresponding AST nodes over the entire workspace that can be a candidate for the cross-reference's place. It is important to understand that we do not decide here which of these nodes is the perfect match! That decision is part of the so-called linker of the Langium architecture. If your cross-reference's `$refText` contains the name `Jane` does not matter here. We need to provide all nodes that are possible at this position. So in the result, you would return `Jane` and `John` AST nodes - for both cross-references! -The background for this behavior is, that this mechanism can be used for two things: the cross-reference resolution and the code completion. The code completion needs to know all possible candidates for a given cross-reference. The resolution of the cross-reference is done by the linker: Given a scope for a certain cross-reference, the linker decides which of the candidates is the right one - for example the first candidate with the same name. +The background for this behavior is that this mechanism can be used for two things: the cross-reference resolution and the code completion. The code completion needs to know all possible candidates for a given cross-reference. The resolution of the cross-reference is done by the linker: Given a scope for a certain cross-reference, the linker decides which of the candidates is the right one - for example the first candidate with the same name. ### Scope computation diff --git a/hugo/content/docs/learn/workflow/write_grammar.md b/hugo/content/docs/learn/workflow/write_grammar.md index 9dce5bff..8bebf921 100644 --- a/hugo/content/docs/learn/workflow/write_grammar.md +++ b/hugo/content/docs/learn/workflow/write_grammar.md @@ -35,7 +35,7 @@ hidden terminal WS: /\s+/; terminal ID: /[_a-zA-Z][\w]*/; ``` -Here we define our two needed terminals for this grammar: The whitespace `WS` and identifier `ID` terminals. Terminals parse a part of our document by matching it against their regular expression. The `WS` terminal parses any whitespace characters with the regex `/\s+/`. This allows us consume whitespaces in our document. As the terminal is declared as `hidden`, the parser will parse any whitespace and discard the results. That way, we don't have to care about how many whitespaces a user uses in their document. Secondly, we define our `ID` terminal. It parses any string that starts with an underscore or letter and continues with any amount of characters that match the `\w` regex token. It will match `Alice`, `_alice`, or `_al1c3` but not `4lice` or `#alice`. Langium is using the JS regex dialect for terminal definitions. +Here we define our two needed terminals for this grammar: The whitespace `WS` and identifier `ID` terminals. Terminals parse a part of our document by matching it against their regular expression. The `WS` terminal parses any whitespace characters with the regex `/\s+/`. This allows us to consume whitespaces in our document. As the terminal is declared as `hidden`, the parser will parse any whitespace and discard the results. That way, we don't have to care about how many whitespaces a user uses in their document. Secondly, we define our `ID` terminal. It parses any string that starts with an underscore or letter and continues with any amount of characters that match the `\w` regex token. It will match `Alice`, `_alice`, or `_al1c3` but not `4lice` or `#alice`. Langium is using the JS regex dialect for terminal definitions. ```langium entry Model: (persons+=Person | greetings+=Greeting)*; diff --git a/hugo/content/docs/recipes/_index.md b/hugo/content/docs/recipes/_index.md index 3f26ac3b..105b28bf 100644 --- a/hugo/content/docs/recipes/_index.md +++ b/hugo/content/docs/recipes/_index.md @@ -6,4 +6,4 @@ url: "/docs/recipes" ## Where to go from here? -Take your time to study the recipes within the navigation on the left. They are designed to help you with common tasks and challenges you might face when working with Langium. If you have any questions or suggestions, feel free to [create an issue](https://github.com/eclipse-langium/langium/issues) or [start a discussion](https://github.com/eclipse-langium/langium/discussions). +Take your time to study the recipes within the navigation on the left. They are designed to help you with common tasks and challenges you might face when working with Langium. If you have any questions or suggestions, feel free to [create an issue](https://github.com/eclipse-langium/langium/issues) or [start a discussion](https://github.com/eclipse-langium/langium/discussions) on the Github repository. diff --git a/hugo/content/docs/reference/glossary.md b/hugo/content/docs/reference/glossary.md index 5c953e84..b84a435d 100644 --- a/hugo/content/docs/reference/glossary.md +++ b/hugo/content/docs/reference/glossary.md @@ -15,6 +15,6 @@ _parser_: A program that takes a _document_ as its input and computes an _abstra _parser rule_: A parser rule describes how a certain _AST_ element is supposed to be parsed. This is done by invoking other _parser rules_ or _terminals_. -_terminal_: A terminal is the smallest parseable part of a document. It usually represents small pieces of text like names, numbers, keywords or comments. +_terminal_: A terminal is the smallest parsable part of a document. It usually represents small pieces of text like names, numbers, keywords or comments. _token_: A token is a substring of the _document_ that matches a certain _terminal_. It contains information about which kind of _terminal_ it represents as well as its location in the document. \ No newline at end of file diff --git a/hugo/content/docs/reference/grammar-language.md b/hugo/content/docs/reference/grammar-language.md index 587afefd..17266f9e 100644 --- a/hugo/content/docs/reference/grammar-language.md +++ b/hugo/content/docs/reference/grammar-language.md @@ -2,6 +2,9 @@ title: "Grammar Language" weight: 100 --- + +{{< toc format=html >}} + The grammar language describes the syntax and structure of your language. The [Langium grammar language](https://github.com/eclipse-langium/langium/blob/main/packages/langium/src/grammar/langium-grammar.langium) is implemented using Langium itself and therefore follows the same syntactic rules as any language created with Langium. The grammar language will define the structure of the *abstract syntax tree* (AST) which in Langium is a collection of *TypeScript types* describing the content of a parsed document and organized hierarchically. The individual nodes of the tree are then represented with JavaScript objects at runtime. In the following, we describe the Langium syntax and document structure.