Builtin Valuetypes

apps/docs/docs/user/.gitignore

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+#
+# SPDX-License-Identifier: AGPL-3.0-only

apps/docs/docs/user/constraint-types/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Constraint Types",
-  "position": 4,
+  "position": 5,
   "link": {
     "type": "generated-index",
     "description": "These constraints are shipped with Jayvee and are available right out of the box."

apps/docs/docs/user/core-concepts.md

@@ -81,56 +81,29 @@ In the example above, the `url` property of type `text` is defined by the corres
 A `ValueType` is the definition of a data type of the processed data.
 Some `Blocks` use `ValueTypes` to define logic (like filtering or assessing the data type in a data sink).
 We differentiate the following types of `ValueTypes`:
-- `Built-in ValueTypes` come with the basic version of Jayvee.
-  Currently `text`, `decimal`, `integer`, and `boolean` are supported.
+- `Built-in ValueTypes` come with the basic version of Jayvee. See [Built-in Valuetypes](./valuetypes/builtin-valuetypes).
 - `Primitive ValueTypes` can be defined by the user to model domain-specific data types and represent a single value.
-  `Constraints` can be added to a `Primitive ValueType` (see [below](#constraints)).
+  `Constraints` can be added to a `Primitive ValueType`.
+See [Primitive Valuetypes](./valuetypes/primitive-valuetypes).
 - `Compound ValueTypes`: UPCOMING.
 
-### Constraints
-
-`Constraints` for `ValueTypes` declare the validity criteria that each concrete value is checked against.
-
-#### Syntax 1: Expression syntax
-
-The syntax of expression-based `Constraints` uses an expression that evaluates to `true` or `false` for the given `value`. The type of the values the expression is working in is indicated ofter the keyword `on`:
-
 ```jayvee
+valuetype GasFillLevel oftype integer {
+    constraints: [ GasFillLevelRange ];
+}
+
 constraint GasFillLevelRange on decimal:
     value >= 0 and value <= 100;
 ```
 
-Refer to the [Expression documentation](./expressions.md) for further reading on expressions.
-
-
-#### Syntax 2: Block-like syntax
-
-The syntax of `Constraints` is similar to the syntax of `Blocks`.
-The availability of property keys and their respective `ValueTypes` is determined by the type of the `Constraint` - indicated by the identifier after the keyword `oftype`:
+## Transforms
+`Transforms` are used to transform data from one `ValueType` to a different one. For more details, see [Transforms](./transforms.md).
 
 ```jayvee
-constraint GasFillLevelRange oftype RangeConstraint {
-    lowerBound: 0;
-    lowerBoundInclusive: true;
-    upperBound: 100;
-    upperBoundInclusive: true;
-}
-```
-
-Note that the type of `Constraint` also determines its applicability to `ValueTypes`.
-For instance, a `RangeConstraint` can only be applied to the numerical types `integer` and `decimal`.
-
-### Primitive ValueTypes
-
-`Primitive ValueTypes` are based on `Built-in ValueTypes` and use a collection of constraints to restrict the range of valid values.
-Such constraints are implicitly connected via a logical `AND` relation.
-Note that the `Constraints` need to be applicable to the base-type of the `ValueType` - indicated by the identifier after the keyword `oftype`:
+transform CelsiusToKelvin {
+  from tempCelsius oftype decimal;
+  to tempKelvin oftype decimal;
 
-```jayvee
-valuetype GasFillLevel oftype integer {
-    constraints: [ GasFillLevelRange ];
+  tempKelvin: tempCelsius + 273.15;
 }
-```
-
-### Transforms
-`Transforms` are used to transform data from one `ValueType` to a different one. For more details, see [Transforms](./transforms.md)
+```

apps/docs/docs/user/expressions.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 # Expressions
@@ -9,7 +9,7 @@ Expressions in Jayvee are arbitrarily nested statements. They consist of:
 - variables (e.g., declared by `from` properties in [Transforms](./transforms.md))
 - operators (e.g., `*` or `sqrt`)
 
-Expressions get evaluated at runtime by the interpreter to a [Built-in ValueType](./core-concepts.md#valuetypes).
+Expressions get evaluated at runtime by the interpreter to a [Built-in ValueType](./valuetypes/builtin-valuetypes).
 
 ### Example
 

apps/docs/docs/user/runtime-parameters.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 8
 ---
 
 # Runtime Parameters

apps/docs/docs/user/transforms.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 7
 ---
 
 # Transforms

apps/docs/docs/user/valuetypes/.gitignore

@@ -0,0 +1,5 @@
+# SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+#
+# SPDX-License-Identifier: AGPL-3.0-only
+
+builtin-valuetypes.md

apps/docs/docs/user/valuetypes/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Valuetypes",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "description": "Jayvee supports these different kinds of valuetypes."
+  }
+}

apps/docs/docs/user/valuetypes/_category_.json.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only

apps/docs/docs/user/valuetypes/primitive-valuetypes.md

@@ -0,0 +1,48 @@
+---
+sidebar_position: 2
+---
+# Primitive ValueTypes
+
+`Primitive ValueTypes` are based on `Built-in ValueTypes` and use a collection of constraints to restrict the range of valid values.
+Such constraints are implicitly connected via a logical `AND` relation.
+Note that the `Constraints` need to be applicable to the base-type of the `ValueType` - indicated by the identifier after the keyword `oftype`:
+
+```jayvee
+valuetype GasFillLevel oftype integer {
+    constraints: [ GasFillLevelRange ];
+}
+```
+
+
+## Constraints
+
+`Constraints` for `ValueTypes` declare the validity criteria that each concrete value is checked against.
+
+### Syntax 1: Expression syntax
+
+The syntax of expression-based `Constraints` uses an expression that evaluates to `true` or `false` for the given `value`. The type of the values the expression is working in is indicated ofter the keyword `on`:
+
+```jayvee
+constraint GasFillLevelRange on decimal:
+    value >= 0 and value <= 100;
+```
+
+Refer to the [Expression documentation](../expressions.md) for further reading on expressions.
+
+
+### Syntax 2: Block-like syntax
+
+The syntax of `Constraints` is similar to the syntax of `Blocks`.
+The availability of property keys and their respective `ValueTypes` is determined by the type of the `Constraint` - indicated by the identifier after the keyword `oftype`:
+
+```jayvee
+constraint GasFillLevelRange oftype RangeConstraint {
+    lowerBound: 0;
+    lowerBoundInclusive: true;
+    upperBound: 100;
+    upperBoundInclusive: true;
+}
+```
+
+Note that the type of `Constraint` also determines its applicability to `ValueTypes`.
+For instance, a `RangeConstraint` can only be applied to the numerical types `integer` and `decimal`.

apps/docs/docs/user/valuetypes/primitive-valuetypes.md.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only

apps/docs/generator/src/main.ts

@@ -7,6 +7,7 @@ import { join } from 'path';
 
 import { StdLangExtension } from '@jvalue/jayvee-extensions/std/lang';
 import {
+  PrimitiveValuetypes,
   getRegisteredBlockMetaInformation,
   getRegisteredConstraintMetaInformation,
   registerConstraints,
@@ -21,6 +22,7 @@ function main(): void {
   const rootPath = join(__dirname, '..', '..', '..', '..');
   generateBlockTypeDocs(rootPath);
   generateConstraintTypeDocs(rootPath);
+  generateValueTypeDocs(rootPath);
 }
 
 function generateBlockTypeDocs(rootPath: string): void {
@@ -69,4 +71,17 @@ function generateConstraintTypeDocs(rootPath: string): void {
   }
 }
 
+function generateValueTypeDocs(rootPath: string): void {
+  const docsPath = join(rootPath, 'apps', 'docs', 'docs', 'user', 'valuetypes');
+  const userDocBuilder = new UserDocGenerator();
+  const valueTypeDoc =
+    userDocBuilder.generateValueTypesDoc(PrimitiveValuetypes);
+
+  const fileName = `builtin-valuetypes.md`;
+  writeFileSync(join(docsPath, fileName), valueTypeDoc, {
+    flag: 'w',
+  });
+  console.info(`Generated file ${fileName}`);
+}
+
 main();

apps/docs/generator/src/user-doc-generator.ts

@@ -2,20 +2,76 @@
 //
 // SPDX-License-Identifier: AGPL-3.0-only
 
+import { strict as assert } from 'assert';
+
 import {
   BlockMetaInformation,
   ConstraintMetaInformation,
   ExampleDoc,
   IOType,
   JayveeBlockTypeDocGenerator,
   JayveeConstraintTypeDocGenerator,
+  JayveeValueTypesDocGenerator,
   MarkdownBuilder,
+  PrimitiveValuetype,
   PropertySpecification,
 } from '@jvalue/jayvee-language-server';
 
 export class UserDocGenerator
-  implements JayveeBlockTypeDocGenerator, JayveeConstraintTypeDocGenerator
+  implements
+    JayveeBlockTypeDocGenerator,
+    JayveeConstraintTypeDocGenerator,
+    JayveeValueTypesDocGenerator
 {
+  generateValueTypesDoc(valueTypes: {
+    [name: string]: PrimitiveValuetype;
+  }): string {
+    const builder = new UserDocMarkdownBuilder()
+      .docTitle('Built-in Valuetypes')
+      .generationComment()
+      .description(
+        `
+For an introduction to valuetypes, see the [Core Concepts](../core-concepts).
+Built-in valuetypes come with the basic version of Jayvee.
+They are the basis for more restricted [Primitive Valuetypes](./primitive-valuetypes)
+that fullfil [Constraints](./primitive-valuetypes#constraints).`.trim(),
+        1,
+      )
+      .heading('Available built-in valuetypes', 1);
+
+    Object.entries(valueTypes)
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      .filter(([_, valueType]) => valueType.isUserExtendable())
+      .forEach(([name, valueType]) => {
+        assert(
+          valueType.getUserDoc(),
+          `Documentation is missing for user extendable value type: ${valueType.getName()}`,
+        );
+        builder
+          .heading(name, 2)
+          .description(valueType.getUserDoc() ?? '', 3)
+          .examples(
+            [
+              {
+                code: `
+block ExampleTableInterpreter oftype TableInterpreter {
+  header: true;
+  columns: [
+    "columnName" oftype ${valueType.getName()}
+  ];
+}`.trim(),
+                description: `A block of type \`TableInterpreter\` that
+              interprets data in the column \`columnName\` as \`${valueType.getName()}\`.
+              `.trim(),
+              },
+            ],
+            3,
+          );
+      });
+
+    return builder.build();
+  }
+
   generateBlockTypeDoc(metaInf: BlockMetaInformation): string {
     const builder = new UserDocMarkdownBuilder()
       .docTitle(metaInf.type)
@@ -84,6 +140,11 @@ class UserDocMarkdownBuilder {
     return this;
   }
 
+  heading(heading: string, depth = 1): UserDocMarkdownBuilder {
+    this.markdownBuilder.heading(heading, depth);
+    return this;
+  }
+
   propertyHeading(propertyName: string, depth = 1): UserDocMarkdownBuilder {
     this.markdownBuilder.heading(`\`${propertyName}\``, depth);
     return this;

apps/vs-code-extension/src/standard-library-file-system-provider.ts

@@ -23,6 +23,10 @@ export class StandardLibraryFileSystemProvider implements FileSystemProvider {
   onDidChangeFile = this.didChangeFile.event;
 
   constructor() {
+    this.registerStdLib();
+  }
+
+  private registerStdLib() {
     Object.entries(StdLib).forEach(([libName, lib]) => {
       this.libraries.set(
         Uri.parse(libName).toString(), // removes slashes if missing authorities, required for matching later on

libs/interpreter-lib/src/parsing-util.ts

@@ -6,11 +6,9 @@ import * as fs from 'fs';
 import * as path from 'path';
 
 import { Logger } from '@jvalue/jayvee-execution';
+import { initializeWorkspace } from '@jvalue/jayvee-language-server';
 import { AstNode, LangiumDocument, LangiumServices } from 'langium';
-import {
-  DiagnosticSeverity,
-  WorkspaceFolder,
-} from 'vscode-languageserver-protocol';
+import { DiagnosticSeverity } from 'vscode-languageserver-protocol';
 import { URI } from 'vscode-uri';
 
 export enum ExitCode {
@@ -63,17 +61,6 @@ export async function extractDocumentFromString(
   return await validateDocument(document, services, logger);
 }
 
-/**
- * Initializes the workspace with all workspace folders.
- * Also loads additional required files, e.g., the standard library
- */
-async function initializeWorkspace(services: LangiumServices): Promise<void> {
-  const workspaceFolders: WorkspaceFolder[] = [];
-  await services.shared.workspace.WorkspaceManager.initializeWorkspace(
-    workspaceFolders,
-  );
-}
-
 export async function validateDocument(
   document: LangiumDocument,
   services: LangiumServices,

libs/language-server/src/grammar/main.langium

@@ -13,7 +13,7 @@ import './transform'
 entry JayveeModel:
   (
     pipelines+=PipelineDefinition
-    | valuetypes+=ValuetypeDefinition
+    | valuetypes+=(CustomValuetypeDefinition | BuiltinValuetypeDefinition)
     | constraints+=ConstraintDefinition
     | transforms+=TransformDefinition
   )*;
@@ -23,7 +23,7 @@ PipelineDefinition:
     (
       blocks+=BlockDefinition
       | pipes+=PipeDefinition
-      | valuetypes+=ValuetypeDefinition
+      | valuetypes+=CustomValuetypeDefinition
       | constraints+=ConstraintDefinition
       | transforms+=TransformDefinition
     )*