+
+```jayvee
+ block ExampleDataSelector oftype CellRangeSelector {
+ select: range A1:B2;
+ }
+```
+
+
+
+
+
+The following `CellRangeSelector` block will select cells from the first to the last cell in row 2 in a `Sheet`:
+
+| + | A | +B | +C | +
| 1 | +Cell A1 | +Cell B1 | +Cell C1 | +
| 2 | +Cell A2 | +Cell B2 | +Cell C2 | +
| 3 | +Cell A3 | +Cell B3 | +Cell C3 | +
+
+```jayvee
+ block ExampleDataSelector oftype CellRangeSelector {
+ select: range A2:*2;
+ }
+```
+
+
+
+
+
+The following `CellRangeSelector` block will select cells from the top-left most cell to the last cell in column B in a `Sheet`:
+
+| + | A | +B | +C | +
| 1 | +Cell A1 | +Cell B1 | +Cell C1 | +
| 2 | +Cell A2 | +Cell B2 | +Cell C2 | +
| 3 | +Cell A3 | +Cell B3 | +Cell C3 | +
+
+```jayvee
+ block ExampleDataSelector oftype CellRangeSelector {
+ select: range A1:B*;
+ }
+```
+
+
+
+
+
+## Selecting Rows
+
+Using the **`row`** keyword, individual rows can be selected. For example, `row 2` will select the second row in a `Sheet`. By adding multiple rows to a `Collection| + | A | +B | +C | +
| 1 | +Cell A1 | +Cell B1 | +Cell C1 | +
| 2 | +Cell A2 | +Cell B2 | +Cell C2 | +
| 3 | +Cell A3 | +Cell B3 | +Cell C3 | +
+
+```jayvee
+ block ExampleRowDeleter oftype RowDeleter {
+ delete: [row 1, row 2];
+ }
+```
+
+
+
+
+
+## Selecting Columns
+
+Using the **`column`** keyword, individual columns can be selected. For example, `column 2` will select the second column in a `Sheet`. By adding multiple columns to a `Collection| + | A | +B | +C | +
| 1 | +Cell A1 | +Cell B1 | +Cell C1 | +
| 2 | +Cell A2 | +Cell B2 | +Cell C2 | +
| 3 | +Cell A3 | +Cell B3 | +Cell C3 | +
+
+```jayvee
+ block ExampleColumnDeleter oftype ColumnDeleter {
+ delete: [column A, column B];
+ }
+```
+
+
+
+
\ No newline at end of file
diff --git a/apps/docs/docs/user/cell-range.md.license b/apps/docs/docs/user/cell-range.md.license
new file mode 100644
index 000000000..db3db822d
--- /dev/null
+++ b/apps/docs/docs/user/cell-range.md.license
@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2024 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only
diff --git a/apps/docs/docs/user/runtime-parameters.md b/apps/docs/docs/user/runtime-parameters.md
index d0620d14c..c68f8ce36 100644
--- a/apps/docs/docs/user/runtime-parameters.md
+++ b/apps/docs/docs/user/runtime-parameters.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 9
+sidebar_position: 10
---
# Runtime Parameters
diff --git a/apps/docs/src/css/custom.css b/apps/docs/src/css/custom.css
index dead4e6e9..04c919e11 100644
--- a/apps/docs/src/css/custom.css
+++ b/apps/docs/src/css/custom.css
@@ -36,12 +36,13 @@
}
.header-github-link:before {
- background: url("data:image/svg+xml;charset=utf-8,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E") no-repeat;
- display: flex;
- height: 24px;
- width: 24px;
- content: "";
+ background: url("data:image/svg+xml;charset=utf-8,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E") no-repeat;
+ display: flex;
+ height: 24px;
+ width: 24px;
+ content: "";
}
+
.header-github-link:hover {
opacity: 0.6;
}
@@ -50,4 +51,15 @@
background: linear-gradient(45deg, var(--ifm-color-primary), var(--ifm-color-primary-lightest) 80%);
background-clip: text;
-webkit-text-fill-color: transparent;
+}
+
+.example-table__highlighted {
+ background-color: var(--ifm-color-primary-lightest);
+}
+
+.side-by-side__container {
+ display: flex;
+ flex-direction: row;
+ flex-wrap: wrap;
+ justify-content: space-evenly;
}
\ No newline at end of file
diff --git a/apps/docs/versioned_docs/version-0.5.0/dev/01-intro.mdx b/apps/docs/versioned_docs/version-0.5.0/dev/01-intro.mdx
new file mode 100644
index 000000000..cdb9efe14
--- /dev/null
+++ b/apps/docs/versioned_docs/version-0.5.0/dev/01-intro.mdx
@@ -0,0 +1,64 @@
+---
+sidebar_position: 1
+---
+
+# Introduction for Jayvee Developers
+
+import MascotImageUrl from '@site/static/img/mascots/mascot3.png';
+
+| + | A | +B | +C | +
| 1 | +Cell A1 | +Cell B1 | +Cell C1 | +
| 2 | +Cell A2 | +Cell B2 | +Cell C2 | +
| 3 | +Cell A3 | +Cell B3 | +Cell C3 | +
+
+
+## How to contribute
+
+In order to contribute to the Jayvee project, please have a look at our [contribution guide](https://github.com/jvalue/jayvee/blob/main/CONTRIBUTING.md). Before planning a contribution, please read the [design principles](./05-design-principles.md) and consider if your changes fit the vision expressed there.
+
+The overall project is licensed under the `AGPL-3.0-only` license and is compliant to the [REUSE Specification](https://reuse.software/spec/) by the [Free Software Foundation Europe](https://fsfe.org/).
+Because of this, contributions are required to adhere to the license and follow that specification.
+More details on this topic can be found [here](./02-dev-processes/03-licensing-and-copyright.md).
+
+And last but not least, please read and follow our [code of conduct](https://github.com/jvalue/jayvee/blob/main/CODE_OF_CONDUCT.md).
+
+## Project overview
+
+The Jayvee repository is located [here](https://github.com/jvalue/jayvee) on GitHub.
+It uses an [Nx mono-repository](https://nx.dev/) setup and contains all related projects, most notably the Jayvee language server and interpreter.
+Please have a look at the [architecture overview](./03-architecture-overview.md) for more details.
+
+## Prerequisites
+
+Node.js and npm are required for development.
+It is recommended to use their LTS version to avoid any potential compatibility issues.
+Also, refer to this [quick start guide](https://github.com/jvalue/jayvee#development-quickstart) for developers.
+
+In order to run the Jayvee VS Code extension during development, VS Code is required as IDE.
+Using VS Code also allows installing the [Langium VS Code extension](https://marketplace.visualstudio.com/items?itemName=langium.langium-vscode) for better IDE support when working with Langium grammar files.
+
+## Resources for getting started
+
+### Langium
+
+- [**Langium documentation**](https://langium.org/docs/)
+- Practical examples using Langium:
+ - [Langium examples](https://github.com/langium/langium/tree/main/examples): Official example languages by Langium
+ - [Langium's grammar language](https://github.com/langium/langium/tree/main/packages/langium): The implementation of Langium's own grammar language
+ - [Language server for SQL](https://github.com/langium/langium-sql): An implementation of a language server for SQL
+ - [MiniLogo DSL](https://github.com/langium/langium-minilogo): A domain-specific language for drawing pictures
+ - [Lox language](https://github.com/langium/langium-lox): An implementation of the Lox scripting language (also see the "Crafting Interpreters" book below)
+ - [SimpleUI DSL](https://github.com/TypeFox/langium-ui-framework): A domain-specific language for generating user interfaces
+ - [STPA-DSL](https://github.com/kieler/stpa): A domain-specific language for System-Theoretic Process Analysis
+- [Langium playground](https://langium.org/playground/): A tool for testing Langium grammars and visualizing resulting ASTs
+- [Typefox blog](https://www.typefox.io/blog/): A blog by the company behind Langium, mostly posting Langium-related content.
+
+### Building compilers / interpreters / DSLs
+
+- [Crafting Interpreters](https://craftinginterpreters.com/contents.html): A book by Robert Nystrom on implementing an interpreter for the Lox scripting language
+- [DSL Engineering](https://voelter.de/dslbook/markusvoelter-dslengineering-1.0.pdf): A book by Markus Voelter on designing, implementing and using domain-specific languages
+- [Awesome Compilers](https://github.com/aalhour/awesome-compilers#readme): A list featuring many resources on compilers and interpreters
diff --git a/apps/docs/versioned_docs/version-0.5.0/dev/01-intro.mdx.license b/apps/docs/versioned_docs/version-0.5.0/dev/01-intro.mdx.license
new file mode 100644
index 000000000..17c5d2bad
--- /dev/null
+++ b/apps/docs/versioned_docs/version-0.5.0/dev/01-intro.mdx.license
@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only
diff --git a/apps/docs/versioned_docs/version-0.5.0/dev/02-dev-processes/01-rfc-process.md b/apps/docs/versioned_docs/version-0.5.0/dev/02-dev-processes/01-rfc-process.md
new file mode 100644
index 000000000..074440850
--- /dev/null
+++ b/apps/docs/versioned_docs/version-0.5.0/dev/02-dev-processes/01-rfc-process.md
@@ -0,0 +1,13 @@
+---
+title: Language Design Process (RFCs)
+sidebar_position: 1
+---
+
+We use RFCs to discuss changes to the language before implementing them. You can have a look at all closed (accepted / rejected) RFCs [here](https://github.com/jvalue/jayvee/pulls?q=is%3Apr+is%3Aclosed+RFC+), and all RFCs under discussion [here](https://github.com/jvalue/jayvee/pulls?q=is%3Apr+is%3Aopen+RFC).
+
+If you want to contribute an RFC please follow these steps:
+1. Make a copy of the **template** at `rfc/0000-rfc-template.md` and place it into the `rfc` folder.
+2. Create a draft for the RFC on a new branch. Follow the `TODOs` in template to do so.
+3. Open a pull request with prefix `RFC
+ 
+
+
+
+ "On the tracks of Jayvee's internals"
+ +
+
+
+
+## Usage of `assertUnreachable`
+
+Most times, it is beneficial to make case distinctions exhaustive, especially when working with AST nodes, properties with a [union literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types) or enums.
+Exhaustiveness in this context means, that the TypeScript compiler is supposed to yield an error if a case distinction does not cover all possibilities.
+
+Langium offers a function called `assertUnreachable` which is capable of enforcing exhaustiveness and producing compiler errors in case of violations. See the following examples to get an idea on how to use it in practice:
+
+Full example
+ +Consider an exemplary AST node `A` with a property `x` of type `string`. To access that property safely: + +```typescript +import { A } from './ast' + +const astNode: A; + +// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition +const property: string | undefined = astNode?.x; +``` + +
+
+
+
+Example for an exhaustive switch statement on a union literal type
+ +```typescript +import { assertUnreachable } from 'langium'; + +const operator: '+' | '-'; + +switch(operator) { + case '+': { + // ... + break; + } + case '-': { + // ... + break; + } + default: { + // To ensure the switch being exhaustive on `operator`: + assertUnreachable(operator); + } +} +``` + +
+
+
+
+## Usage of `assert` for expressing runtime expectations
+
+During development, it may occur that a certain condition is expected to **be always true** at runtime.
+For example, an AST node being of a certain type or a property being defined.
+The type system of TypeScript is not always able to infer such facts, so developers may have to express these expectations explicitly in their code.
+Examples are [type assertions](https://www.typescriptlang.org/docs/handbook/advanced-types.html) or the [non-null assertion operator](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-0.html#non-null-assertion-operator).
+Their usage may be problematic in case the condition does not always hold, e.g. due to a bug in the program or a wrong expectation by the programmer.
+In such cases, it is hard to locate the origin and debug the program because such operations are erased in the compiled JavaScript code.
+
+To avoid these issues, it is recommended to express such expectations as boolean expressions that are actually validated at runtime.
+This can be easily achieved by using the `assert` function.
+It evaluates a given boolean expression and throws an `AssertionError` in case it evaluates to `false`.
+After calling `assert`, the type system of TypeScript assumes the condition to be `true` and afterwards narrows types accordingly.
+
+Here is an example of how to use it in practice:
+
+```typescript
+// We use the `assert` function from the `assert` library, not `node:assert` (to preserve browser compatibility)
+
+// eslint-disable-next-line unicorn/prefer-node-protocol
+import { strict as assert } from 'assert';
+
+import { A, B, isB } from './ast';
+
+const astNode: A;
+assert(isB(astNode));
+// Here `astNode` has type `B`
+
+const referenced = astNode?.reference?.ref;
+assert(referenced !== undefined);
+// Here `referred` is not `undefined`
+```
+
+## AST wrapper classes
+
+The generated interfaces for AST nodes in `ast.ts` are only meant to represent the AST structurally, they don't define any behavior.
+Also, in case of syntactic sugar, there may be different kinds of AST nodes representing the same semantic language concept.
+
+To cope with this problem, there is the concept of an `AstNodeWrapper`.
+An AST node wrapper is capable of wrapping AST nodes that represent the same semantic language concept and adding behavior to them via custom methods.
+To get an impression on how this can be done in practice, please have a look at the [`PipeWrapper` class](https://github.com/jvalue/jayvee/blob/main/libs/language-server/src/lib/ast/wrappers/pipe-wrapper.ts) and the [`AstNodeWrapper` interface](https://github.com/jvalue/jayvee/blob/main/libs/language-server/src/lib/ast/wrappers/ast-node-wrapper.ts).
diff --git a/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/02-working-with-the-ast.md.license b/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/02-working-with-the-ast.md.license
new file mode 100644
index 000000000..17c5d2bad
--- /dev/null
+++ b/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/02-working-with-the-ast.md.license
@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only
diff --git a/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/03-validation-and-diagnostics.md b/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/03-validation-and-diagnostics.md
new file mode 100644
index 000000000..328d57285
--- /dev/null
+++ b/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/03-validation-and-diagnostics.md
@@ -0,0 +1,64 @@
+---
+title: Validation and diagnostics
+sidebar_position: 3
+---
+
+Validation in the context of Jayvee can be understood as semantic analysis of Jayvee models.
+The purpose is to uncover errors in models besides lexing, parsing and linking errors that the Langium framework already detects out of the box.
+In case such errors are found, the language server makes the IDE display a diagnostic.
+This means that the location of the error is underlined and an error message is shown.
+
+For example, each pipeline is expected to contain at least one starting block that requires no input.
+Therefore, the language server analyzes every pipeline in a Jayvee model and checks for the presence of such a starting block.
+In case no such block is found, the IDE underlines the pipeline definition in a red color and displays an error message.
+
+## How to implement validation
+
+### For arbitrary AST nodes
+
+In the file [`validation-registry.ts`](https://github.com/jvalue/jayvee/blob/main/libs/language-server/src/lib/validation/validation-registry.ts) of the language server, there is a registry containing validation functions for various AST nodes.
+A validation function provided for a certain kind of AST node is called for every occurrence of such a node in a Jayvee model.
+E.g. when registering a validation function for `PipelineDefinition` nodes, that function gets called once for each pipeline.
+
+A validation function always operates on a single, concrete AST node.
+Besides the AST node, a `ValidationContext` object is passed to the function for reporting diagnostics via its `accept` method.
+
+The overall validation for a specific kind of AST node is usually subdivided into smaller checks that are called sequentially.
+This potentially allows aborting the validation early, i.e. before all checks were run.
+Aborting early may be useful if errors were reported during previous checks.
+This can be determined via the `ValidationContext` which keeps track whether any errors occurred so far.
+
+A practical example where this plays a role are blocks:
+When the type of a block is unknown to the language server, it makes no sense to validate inputs / outputs and properties of that block.
+So, in case an error was reported during the check of the block type, the validation of that block is discontinued at that point.
+
+### For properties of blocks and constraints
+
+Validating property values of blocks / constraints works a bit differently because their individual validation is already incorporated into the overall validation framework.
+
+In general, the validation logic for a property values is located in the meta information of the block type / constraint type.
+There, properties are defined using the `PropertySpecification` interface.
+In order to add validation logic to a certain property, a validation function needs to be added to that property.
+
+For more complex validations that need to take multiple property values into account, it is also possible to provide a more general validation function which operates on the entire `PropertyBody` AST node.
+
+See [`text-range-selector-meta-inf.ts`](https://github.com/jvalue/jayvee/blob/main/libs/extensions/std/lang/src/text-range-selector-meta-inf.ts) for an example which includes both cases described above.
+
+## Reporting diagnostics
+
+During validation, diagnostics can be reported by calling the `accept` method of the given `ValidationContext` object.
+
+The call requires the severity of the diagnostic (`error`, `warning`, `info` or `hint`), the error message and its location.
+The location is described by a `DiagnosticInfo` object which contains the affected AST node and optionally some further restrictions.
+For more details, have a look at the [`DiagnosticInfo` interface](https://github.com/langium/langium/blob/main/packages/langium/src/validation/validation-registry.ts) by Langium.
+
+## Common issues
+
+When working on validations, a diagnostic with the following message may unexpectedly occur: `An error occurred during validation: ...`
+
+Such a diagnostic is generated by the Langium framework if an error object is thrown within the validation.
+In most cases, the reason is the access of an `undefined` AST node property or an `AssertionError`.
+For more details on such errors and how to avoid them, have a look at the documentation on [how to work with the AST](./02-working-with-the-ast.md).
+
+One way locate the origin of such errors is to debug the Jayvee VS Code extension, see [here](../02-dev-processes/02-debug-vs-code-extension.md) for more details.
+Another possibility is to debug the interpreter and set appropriate breakpoints in the language server codebase.
diff --git a/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/03-validation-and-diagnostics.md.license b/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/03-validation-and-diagnostics.md.license
new file mode 100644
index 000000000..17c5d2bad
--- /dev/null
+++ b/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/03-validation-and-diagnostics.md.license
@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only
diff --git a/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/04-expressions-and-operators.md b/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/04-expressions-and-operators.md
new file mode 100644
index 000000000..d201864e1
--- /dev/null
+++ b/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/04-expressions-and-operators.md
@@ -0,0 +1,151 @@
+---
+title: Expressions and operators
+sidebar_position: 4
+---
+
+Jayvee supports arbitrarily nested expressions and offers a variety of different operators.
+Such expressions are similar to those used in programming languages, and they are intended to be read and understood intuitively.
+
+The following sections explain the definition of expressions in the language grammar, their type inference mechanism, and how the evaluation of expressions works.
+As a small practical example, you may also have a look at the [arithmetics example by Langium](https://github.com/langium/langium/tree/main/examples/arithmetics) which has a heavy focus on mathematical expressions and functions.
+
+## Expressions in the grammar
+
+Expressions in the Jayvee grammar are defined in [`expression.langium`](https://github.com/jvalue/jayvee/blob/main/libs/language-server/src/grammar/expression.langium) and consist of operators (unary / binary / ternary) and literals.
+Unary operators only have a single operand (e.g. the `not` operator), binary operators require two operands (e.g. the `*` operator) and ternary operators require three operands.
+
+The grammar is written in a way that literals end up in the leaves of the resulting AST and the nodes above represent the operators.
+
+As an example, have a look at the following AST structure of the expression `(-3 + 5) * 7`:
+
+```mermaid
+classDiagram
+
+class `:BinaryOperator` {
+ operator = '*'
+}
+
+%% Uses spaces in the name so it is unique
+class ` :BinaryOperator` {
+ operator = '+'
+}
+
+class `:UnaryOperator` {
+ operator = '-'
+}
+
+%% Uses spaces in the name so it is unique
+class ` :NumericLiteral` {
+ value = 3
+}
+
+%% Uses spaces in the name so it is unique
+class ` :NumericLiteral` {
+ value = 5
+}
+
+class `:NumericLiteral` {
+ value = 7
+}
+
+`:BinaryOperator` --> ` :BinaryOperator` : leftOperand
+`:BinaryOperator` --> `:NumericLiteral` : rightOperand
+` :BinaryOperator` --> `:UnaryOperator` : leftOperand
+`:UnaryOperator` --> ` :NumericLiteral` : operand
+` :BinaryOperator` --> ` :NumericLiteral` : rightOperand
+```
+
+The AST is constructed in a way that ensures an unambiguous evaluation order when using depth-first search.
+This implies that the AST structure already reflects the precedence and associativity of the operators, and that parentheses do not need to be explicitly represented.
+
+For more details on how such a grammar for expressions can be realized, see the [official Langium documentation](https://langium.org/docs/grammar-language/#tree-rewriting-actions), [this blog post](https://www.typefox.io/blog/parsing-expressions-with-xtext) and the following two sections which discuss the precedence and associativity of operators.
+
+### Precedence of operators
+
+The grammar implicitly defines the precedence of operators.
+The operator precedence defines the order in which operators are evaluated within an expression.
+For example, multiplication has a higher precedence than addition, which leads to multiplications being performed before additions.
+In order to manually override such precedence conventions, parentheses can be used in expressions.
+
+The diagram below shows a more extensive precedence hierarchy, focused on common arithmetic operators.
+Note that the hierarchy is arranged in ascending order, according to the operator precedence.
+Such an order is similar to how operators in the actual Jayvee grammar are arranged:
+
+```mermaid
+graph TD
+ subgraph BinaryOperators
+ add/sub(Addition Operator / Subtraction operator) --> mul/div(Multiplication Operator / Division Operator)
+ mul/div --> exp/root(Exponential Operator / Root Operator)
+ end
+ subgraph UnaryOperators
+ exp/root --> plus/minus(Plus Operator / Minus Operator)
+ end
+ plus/minus --> literal(Numeric Literal)
+```
+
+In the Jayvee grammar, every level of precedence is represented by a single grammar rule.
+Within each such rule, the grammar rule which defines the operators with the next higher precedence is referenced.
+E.g. the `AdditiveExpression` rule refers to the `MultiplicativeExpression` rule because multiplicative operators are supposed to have the next higher precedence.
+
+In order to alter the precedence of operators, their hierarchy of grammar rules has to be adjusted accordingly in [`expression.langium`](https://github.com/jvalue/jayvee/blob/main/libs/language-server/src/grammar/expression.langium).
+
+### Associativity of operators
+
+The associativity of operators defines the order in which operators with the same precedence are evaluated when they appear in succession without parentheses.
+Operators may be either **left-associative**, **right-associative** or **non-associative**.
+For example, depending on the associativity of the binary `+` operator, the expression `a + b + c` has different semantics:
+
+- Left-associative: `(a + b) + c` (evaluation from left to right)
+- Right-associative: `a + (b + c)` (evaluation from right to left)
+- Non-associative: _syntax error_, the operator cannot be chained
+
+The associativity of operators is also defined in the Jayvee grammar, more specifically by the structure of the grammar rules that define operators.
+For details on how to encode the different kinds of associativity in grammar rules, have a look at the "Associativity" section near the end of [this blog post](https://www.typefox.io/blog/parsing-expressions-with-xtext).
+The patterns described in the linked article can be found in [`expression.langium`](https://github.com/jvalue/jayvee/blob/main/libs/language-server/src/grammar/expression.langium), so each operator grammar rule encodes its own associativity.
+
+## Typing of expressions
+
+Jayvee has a mechanism for inferring and validating the type of a given expression.
+This is achieved using a recursive algorithm which performs depth-first search on a given expression:
+
+The base case for the algorithm are literals, i.e. the tree leaves of an expression.
+Depending on the type of literal, their type can be inferred trivially (in case of value literals) or otherwise from the context where the expression is located.
+
+For operators, the types of their operands are first inferred via recursion, and then it is checked whether they are supported by the operator.
+Next, given the operand types, the resulting type is computed.
+Such behavior is defined in a _type computer class_ located [here](https://github.com/jvalue/jayvee/tree/main/libs/language-server/src/lib/ast/expressions/type-computers).
+Additionally, in [`operator-registry.ts`](https://github.com/jvalue/jayvee/blob/main/libs/language-server/src/lib/ast/expressions/operator-registry.ts), a type computer is registered for each kind of operator.
+
+In case the algorithm fails to infer a type, e.g. due to unsupported operand types or unresolved references in literals, the resulting type is `undefined`.
+In order to report diagnostics in such cases, a `ValidationContext` object can be supplied when calling the type inference.
+
+## Evaluation of expressions
+
+The evaluation has the purpose of computing a single value out of an expression.
+For a successful evaluation, it is a **precondition** that **a type could successfully be inferred** from the respective expression.
+Also, the **value for each free variable** in that expression (i.e. literals resembling placeholders for values) needs to be **known beforehand**.
+Therefore, an `ExecutionContext` object is passed to the evaluation which holds values for free variables in the current context.
+
+### Algorithm
+
+The algorithm for evaluating expressions is also based on a recursive depth-first search, similar to how the type inference works:
+
+Again, literals are the base case. A value literal trivially evaluates to its own value.
+Other literals that resemble free variables evaluate to their value provided by the given `ExecutionContext` object.
+
+Regarding operators, their operands first are evaluated recursively.
+Next, using the concrete operand values, the operator computes its resulting value.
+This is defined in operator evaluator classes located [here](https://github.com/jvalue/jayvee/tree/main/libs/language-server/src/lib/ast/expressions/evaluators).
+The classes are registered in [operator-registry.ts](https://github.com/jvalue/jayvee/blob/main/libs/language-server/src/lib/ast/expressions/operator-registry.ts) for every operator, similar to the previously mentioned type computers.
+
+The result of an evaluation may be `undefined` in case any errors occurred.
+If the preconditions were all met, such errors are most likely arithmetic errors (like division by zero).
+It is possible to provide a `ValidationContext` object to the evaluation for reporting such errors as diagnostics.
+
+### Evaluation strategies
+
+There are different evaluation strategies to choose from.
+They affect the way, expressions are evaluated and thus have an impact on their semantics:
+
+- `exhaustive`: A full depth-first search is performed, all parts of an expression are evaluated.
+- `lazy`: An evaluation with the least effort is performed. Logical operators use [short circuit semantics](https://en.wikipedia.org/wiki/Short-circuit_evaluation) and binary operators don't evaluate their right operand if the left one evaluated to `undefined`.
diff --git a/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/04-expressions-and-operators.md.license b/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/04-expressions-and-operators.md.license
new file mode 100644
index 000000000..17c5d2bad
--- /dev/null
+++ b/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/04-expressions-and-operators.md.license
@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only
diff --git a/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/05-standard-library.md b/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/05-standard-library.md
new file mode 100644
index 000000000..2da1646f0
--- /dev/null
+++ b/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/05-standard-library.md
@@ -0,0 +1,48 @@
+---
+title: Working with the Standard Library
+sidebar_position: 5
+---
+
+Jayvee ships with its own standard library on board, including the most often used _value types_, transformations, and so on.
+The standard library itself is written in `.jv` files [here](https://github.com/jvalue/jayvee/tree/main/libs/language-server/src/stdlib/).
+
+## Standard Library Contents
+
+The following elements are part of the standard library:
+
+## Builtin Contents
+
+The implementations of built-in contents are not expressed in Jayvee itself but on the TypeScript layer. Examples:
+
+- **Builtin value types**: These _value types_ are the base for defining user-defined _value types_ in Jayvee, e.g., `text`, `integer`, `decimal`, `boolean`.
+- **Builtin io types**: These _io types_ are used to describe in inputs and outputs of _block types_, e.g., `Sheet`, `File`.
+- **Builtin block types**: These _block types_ are the very basic building _blocks_ in Jayvee, e.g., `HttpExtractor`, `SqliteLoader`.
+- **Builtin constraint types**: These _constraint types_ are constraints with custom logic, e.g., `LengthConstraint`, `RegexConstraint`.
+
+Builtin definitions are usually generated and added to the standard library from the internal representations of the concepts.
+
+### User-defined Contents
+
+The implementations of user-defined contents are expressed in Jayvee itself. Examples:
+
+- **User-defined value types**: These _value types_ are based on built-in or other user-defined _value types_. Their definition is expressed natively in Jayvee, e.g., `Percent`.
+- **User-defined block types**: These _block types_ are based on built-in or other user-defined _block types_. Their definition is expressed natively in Jayvee.
+
+We use `jv` files to add user-defined _value types_ to the standard library (see below).
+
+## Extending the Standard Library
+
+Just add `jv` files to the directory [here](https://github.com/jvalue/jayvee/tree/main/libs/language-server/src/stdlib/). It is crawled hierarchically, meaning that you can also organize files in folders.
+
+## Implementation
+
+### 1. Code generation
+
+We use code generation to transform these `.jv` files into TypeScript files that the language server can used. The [generation script](https://github.com/jvalue/jayvee/tree/main/tools/scripts/language-server/generate-stdlib.mjs) is run via `npm run generate` next to the AST generation.
+
+### 2. Builtin libraries
+
+The solution we chose to implement the standard library mechanism is close to the [built-in library tutorial](https://langium.org/guides/builtin-library/) by Langium. The following components are of interest:
+
+- [JayveeWorkspaceManager](https://github.com/jvalue/jayvee/tree/main/libs/language-server/src/lib/builtin-library/jayvee-workspace-manager.ts) in the `language-server` that registers all libraries with the langium framework.
+- [StandardLibraryFileSystemProvider](https://github.com/jvalue/jayvee/tree/main/apps/vs-code-extension/src/standard-library-file-system-provider.ts) in the `vs-code-extension` that registers all libraries with the vscode plugin framework.
diff --git a/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/05-standard-library.md.license b/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/05-standard-library.md.license
new file mode 100644
index 000000000..17c5d2bad
--- /dev/null
+++ b/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/05-standard-library.md.license
@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only
diff --git a/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/06-jayvee-extensions.md b/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/06-jayvee-extensions.md
new file mode 100644
index 000000000..e10d24313
--- /dev/null
+++ b/apps/docs/versioned_docs/version-0.5.0/dev/04-guides/06-jayvee-extensions.md
@@ -0,0 +1,190 @@
+---
+title: Jayvee Extensions
+sidebar_position: 6
+---
+
+## Concepts
+
+### Jayvee extension
+
+A Jayvee extension is used to add new block types to the language without having to modify the actual grammar of the language. Such a Jayvee extension usually consists of two parts: a language extension and an execution extension which are described in the upcoming two sections.
+
+Jayvee extensions that shall be used by default are bundled into the so-called [standard extension](https://github.com/jvalue/jayvee/tree/main/libs/extensions/std). That way, the [language server](https://github.com/jvalue/jayvee/tree/main/libs/language-server) and the [interpreter](https://github.com/jvalue/jayvee/tree/main/apps/interpreter) are able to load them out of the box.
+
+### Language extension
+
+A language extension defines meta information of block types which are required by the
+[language server](https://github.com/jvalue/jayvee/tree/main/libs/language-server).
+Such meta information describes properties of
+block types such as their names, input / output types and their properties.
+
+Note that language extensions don't define any behavior. Instead, this is done by the corresponding execution extension.
+
+### Execution extension
+
+An execution extension defines behavior for block types. They build on the meta information from the corresponding
+language extension, e.g. input / output types of the block need to match the signature of the execution method and
+properties are accessed by their specified name.
+
+Execution extensions are only required by the [interpreter](https://github.com/jvalue/jayvee/tree/main/apps/interpreter) and not necessarily by the [language server](https://github.com/jvalue/jayvee/tree/main/libs/language-server) as they solely define behavior.
+
+## Recipes
+
+### Add a new Jayvee execution extension
+
+#### 1. Generate an execution libraries
+
+```bash
+npx nx g @nx/node:library --name="extensions/Example for an exhaustive if-elseif-else cascade using typeguards
+ +Consider the exemplary AST nodes `A`, `B` and `C` and that `A = B | C`: + +```typescript +import { assertUnreachable } from 'langium'; +import { A, B, isB, C, isC } from './ast' + +const astNode: A; + +if (isB(astNode)) { + // `astNode` has type `B` here +} else if (isC(astNode)) { + // `astNode` has type `C` here +} else { + // To ensure the if-elseif-else cascade being exhaustive on `astNode`: + assertUnreachable(astNode); +} +``` + +| + | A | +B | +C | +
| 1 | +Cell A1 | +Cell B1 | +Cell C1 | +
| 2 | +Cell A2 | +Cell B2 | +Cell C2 | +
| 3 | +Cell A3 | +Cell B3 | +Cell C3 | +
+
+```jayvee
+ block ExampleDataSelector oftype CellRangeSelector {
+ select: range A1:B2;
+ }
+```
+
+
+
+
+
+The following `CellRangeSelector` block will select cells from the first to the last cell in row 2 in a `Sheet`:
+
+| + | A | +B | +C | +
| 1 | +Cell A1 | +Cell B1 | +Cell C1 | +
| 2 | +Cell A2 | +Cell B2 | +Cell C2 | +
| 3 | +Cell A3 | +Cell B3 | +Cell C3 | +
+
+```jayvee
+ block ExampleDataSelector oftype CellRangeSelector {
+ select: range A2:*2;
+ }
+```
+
+
+
+
+
+The following `CellRangeSelector` block will select cells from the top-left most cell to the last cell in column B in a `Sheet`:
+
+| + | A | +B | +C | +
| 1 | +Cell A1 | +Cell B1 | +Cell C1 | +
| 2 | +Cell A2 | +Cell B2 | +Cell C2 | +
| 3 | +Cell A3 | +Cell B3 | +Cell C3 | +
+
+```jayvee
+ block ExampleDataSelector oftype CellRangeSelector {
+ select: range A1:B*;
+ }
+```
+
+
+
+
+
+## Selecting Rows
+
+Using the **`row`** keyword, individual rows can be selected. For example, `row 2` will select the second row in a `Sheet`. By adding multiple rows to a `Collection| + | A | +B | +C | +
| 1 | +Cell A1 | +Cell B1 | +Cell C1 | +
| 2 | +Cell A2 | +Cell B2 | +Cell C2 | +
| 3 | +Cell A3 | +Cell B3 | +Cell C3 | +
+
+```jayvee
+ block ExampleRowDeleter oftype RowDeleter {
+ delete: [row 1, row 2];
+ }
+```
+
+
+
+
+
+## Selecting Columns
+
+Using the **`column`** keyword, individual columns can be selected. For example, `column 2` will select the second column in a `Sheet`. By adding multiple columns to a `Collection| + | A | +B | +C | +
| 1 | +Cell A1 | +Cell B1 | +Cell C1 | +
| 2 | +Cell A2 | +Cell B2 | +Cell C2 | +
| 3 | +Cell A3 | +Cell B3 | +Cell C3 | +
+
+```jayvee
+ block ExampleColumnDeleter oftype ColumnDeleter {
+ delete: [column A, column B];
+ }
+```
+
+
+
+
\ No newline at end of file
diff --git a/apps/docs/versioned_docs/version-0.5.0/user/cell-range.md.license b/apps/docs/versioned_docs/version-0.5.0/user/cell-range.md.license
new file mode 100644
index 000000000..db3db822d
--- /dev/null
+++ b/apps/docs/versioned_docs/version-0.5.0/user/cell-range.md.license
@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2024 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only
diff --git a/apps/docs/versioned_docs/version-0.5.0/user/composite-block-types.md b/apps/docs/versioned_docs/version-0.5.0/user/composite-block-types.md
new file mode 100644
index 000000000..e0e9df159
--- /dev/null
+++ b/apps/docs/versioned_docs/version-0.5.0/user/composite-block-types.md
@@ -0,0 +1,118 @@
+---
+sidebar_position: 4
+---
+
+# Composite Block Types
+
+_Composite block types_ are a way to create new _block types_ in Jayvee by combining the functionality of existing _blocks_ and _pipes_. By relying on _composite block types_ instead of implementing more _built-in block types_ in a language interpreter, Jayvee supports easy extension by users.
+
+_Composite block types_ define:
+
+- with the `property` keyword: properties with a name and [value type](<./core-concepts.md#value types>), optionally a default value
+- with the `input` keyword: one input with a name and _io type_ (that can be `None`)
+- with the `output` keyword: one output with a name and _io type_ (that can be `None`)
+- one _pipeline_ definition, starting from the input (using its name) and ending in the output (again using its name)
+- all _blocks_ that are used in the _pipeline_ definition (either _blocks_ of _built-in_ or _composite block types_)
+
+## Example
+
+As an example, the common use-case of extracting a CSV file from a web server using HTTP. With _built-in block types_, a _pipeline_ would start with a `HttpExtractor` source that downloads a file from the internet and outputs a binary file. This file must be interpreted as text (using a `TextFileInterpreter`) and finally as `Sheet` (using a `CSVInterpreter`).
+
+### Implementation with built-in block types
+
+```mermaid
+flowchart LR
+ A[HttpExtractor] --> B(TextFileInterpreter)
+ B --> C(CSVInterpreter)
+ C --> D(TableInterpreter)
+ D --> E[SQLiteSink]
+```
+
+A _pipeline_ with _blocks_ using _built-in block types_ is very verbose:
+
+```jayvee
+pipeline CarsPipeline {
+ CarsExtractor
+ -> CarsTextFileInterpreter
+ -> CarsCSVInterpreter
+ -> CarsTableInterpreter
+ -> CarsLoader;
+
+ block CarsExtractor oftype HttpExtractor {
+ url: "https://example.com/cars.csv";
+ }
+
+ block CarsTextFileInterpreter oftype TextFileInterpreter { }
+
+ block CarsCSVInterpreter oftype CSVInterpreter {
+ enclosing: '"';
+ }
+ // ... further block definitions
+}
+```
+
+### Refactoring using composite block types
+
+The common use-case of downloading a CSV file using HTTP can be refactored into a _composite block type_. Note that we define all properties of the _built-in blocks_ that are used as properties of the new `CSVExtractor` _block type_ (but add fallback values). If some internal configuration is always the same, we could also not expose it as a property of the new _block type_.
+
+```jayvee
+// Define a new composite block type named CSVExtractor outside of the pipeline
+composite blocktype CSVExtractor {
+ // Properties of the CSVExtractor, some with default values
+ property url oftype text;
+ property delimiter oftype text: ',';
+ property enclosing oftype text: '';
+ property enclosingEscape oftype text: '';
+
+ // Input and outputs
+ input inputName oftype None;
+ output outputName oftype Sheet;
+
+ // Pipeline definition from input, over blocks defined later, to output
+ inputName
+ ->FileExtractor
+ ->FileTextInterpreter
+ ->FileCSVInterpreter
+ ->outputName;
+
+ // Block definitions using values from properties by name
+ block FileExtractor oftype HttpExtractor { url: url; }
+ block FileTextInterpreter oftype TextFileInterpreter {}
+
+ block FileCSVInterpreter oftype CSVInterpreter {
+ delimiter: delimiter;
+ enclosing: enclosing;
+ enclosingEscape: enclosingEscape;
+ }
+}
+```
+
+With the new `CSVExtractor` _composite block type_, the _pipeline_ now looks like this.
+
+```mermaid
+flowchart LR
+ CSVExtractor --> D(TableInterpreter)
+ D --> E[SQLiteSink]
+
+ subgraph CSVExtractor
+ A[HttpExtractor] --> B(TextFileInterpreter)
+ B --> C(CSVInterpreter)
+end
+```
+
+If the `CSVExtractor` is available in the scope of the `CarsPipeline` from before (e.g., by defining it above the _pipeline_), it can then be used to shorten the actual _pipeline_ code.
+
+```jayvee
+pipeline CarsPipeline {
+ // HttpExtractor, TextFileInterpreter and CSVInterpreter have been replaced by CSVExtractor
+ CarsExtractor
+ -> CarsTableInterpreter
+ -> CarsLoader;
+
+ block CarsExtractor oftype CSVExtractor {
+ url: "https://example.com/cars.csv";
+ }
+
+ // ... further block definitions
+}
+```
diff --git a/apps/docs/versioned_docs/version-0.5.0/user/composite-block-types.md.license b/apps/docs/versioned_docs/version-0.5.0/user/composite-block-types.md.license
new file mode 100644
index 000000000..17c5d2bad
--- /dev/null
+++ b/apps/docs/versioned_docs/version-0.5.0/user/composite-block-types.md.license
@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only
diff --git a/apps/docs/versioned_docs/version-0.5.0/user/constraint-types/AllowlistConstraint.md b/apps/docs/versioned_docs/version-0.5.0/user/constraint-types/AllowlistConstraint.md
new file mode 100644
index 000000000..a8b7f0260
--- /dev/null
+++ b/apps/docs/versioned_docs/version-0.5.0/user/constraint-types/AllowlistConstraint.md
@@ -0,0 +1,27 @@
+---
+title: AllowlistConstraint
+---
+
+
+
+Compatible value type: text
+
+## Description
+
+Limits the values to a defined a set of allowed values. Only values in the list are valid.
+
+## Example 1
+
+```jayvee
+ publish constraint TimeUnitString oftype AllowlistConstraint {
+ allowlist: ["ms", "s", "min", "h", "d", "m", "y"];
+ }
+```
+
+Only allows the common abbreviations for millisecond, second, minute, etc..
+
+## Properties
+
+### `allowlist`
+
+Type `Collection| + | A | +B | +C | +
| 1 | +Cell A1 | +Cell B1 | +Cell C1 | +
| 2 | +Cell A2 | +Cell B2 | +Cell C2 | +
| 3 | +Cell A3 | +Cell B3 | +Cell C3 | +
+
+
+Jayvee is a domain-specific language (DSL) for automated processing of data pipelines.
+The Jayvee interpreter allows executing such data pipelines on local machines.
+Data engineers can use Jayvee and its interpreter to clean and preprocess data for later activities like data science or machine learning.
+
+## Installation
+
+Install the interpreter via `npm`. You will need a **nodejs version >= 17.0.0**.
+
+```bash
+npm install -g @jvalue/jayvee-interpreter
+```
+
+You can install a specific version using the `@`-syntax, e.g., version `0.0.17`:
+
+```bash
+npm install -g @jvalue/jayvee-interpreter@0.0.17
+```
+
+## Update
+
+Details about how to update Jayvee and the VSCode extension can be found [here](./update.md).
+
+## Usage
+
+### Show help
+
+```console
+jv -h
+```
+
+### Run a `.jv` file
+
+```console
+jv
+
+
+
+
+