From 973044e1cf6509725b52d95aa4085e0f13d87487 Mon Sep 17 00:00:00 2001 From: Georg Schwarz Date: Thu, 27 Jul 2023 11:46:18 +0200 Subject: [PATCH] Move valuetype doc into own category --- apps/docs/docs/user/.gitignore | 2 - .../user/constraint-types/_category_.json | 2 +- apps/docs/docs/user/core-concepts.md | 54 +++++-------------- apps/docs/docs/user/expressions.md | 4 +- apps/docs/docs/user/runtime-parameters.md | 2 +- apps/docs/docs/user/transforms.md | 2 +- apps/docs/docs/user/valuetypes/.gitignore | 5 ++ .../docs/docs/user/valuetypes/_category_.json | 8 +++ .../user/valuetypes/_category_.json.license | 3 ++ .../user/valuetypes/primitive-valuetypes.md | 48 +++++++++++++++++ .../primitive-valuetypes.md.license | 3 ++ apps/docs/generator/src/main.ts | 2 +- apps/docs/generator/src/user-doc-generator.ts | 7 +-- 13 files changed, 91 insertions(+), 51 deletions(-) create mode 100644 apps/docs/docs/user/valuetypes/.gitignore create mode 100644 apps/docs/docs/user/valuetypes/_category_.json create mode 100644 apps/docs/docs/user/valuetypes/_category_.json.license create mode 100644 apps/docs/docs/user/valuetypes/primitive-valuetypes.md create mode 100644 apps/docs/docs/user/valuetypes/primitive-valuetypes.md.license diff --git a/apps/docs/docs/user/.gitignore b/apps/docs/docs/user/.gitignore index eb7531ecd..d1b2321da 100644 --- a/apps/docs/docs/user/.gitignore +++ b/apps/docs/docs/user/.gitignore @@ -1,5 +1,3 @@ # SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg # # SPDX-License-Identifier: AGPL-3.0-only - -builtin-valuetypes.md \ No newline at end of file diff --git a/apps/docs/docs/user/constraint-types/_category_.json b/apps/docs/docs/user/constraint-types/_category_.json index 9cced194c..7eecb5c68 100644 --- a/apps/docs/docs/user/constraint-types/_category_.json +++ b/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." diff --git a/apps/docs/docs/user/core-concepts.md b/apps/docs/docs/user/core-concepts.md index a104b8ac7..d46c48ac3 100644 --- a/apps/docs/docs/user/core-concepts.md +++ b/apps/docs/docs/user/core-concepts.md @@ -81,55 +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. See [Built-in Valuetypes](./builtin-valuetypes). +- `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) \ No newline at end of file +``` \ No newline at end of file diff --git a/apps/docs/docs/user/expressions.md b/apps/docs/docs/user/expressions.md index 250e3294f..c3728c886 100644 --- a/apps/docs/docs/user/expressions.md +++ b/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](./builtin-valuetypes). +Expressions get evaluated at runtime by the interpreter to a [Built-in ValueType](./valuetypes/builtin-valuetypes). ### Example diff --git a/apps/docs/docs/user/runtime-parameters.md b/apps/docs/docs/user/runtime-parameters.md index ac5d8995e..4f257fac9 100644 --- a/apps/docs/docs/user/runtime-parameters.md +++ b/apps/docs/docs/user/runtime-parameters.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 8 --- # Runtime Parameters diff --git a/apps/docs/docs/user/transforms.md b/apps/docs/docs/user/transforms.md index f232f6dbd..731ec304a 100644 --- a/apps/docs/docs/user/transforms.md +++ b/apps/docs/docs/user/transforms.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 7 --- # Transforms diff --git a/apps/docs/docs/user/valuetypes/.gitignore b/apps/docs/docs/user/valuetypes/.gitignore new file mode 100644 index 000000000..eb7531ecd --- /dev/null +++ b/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 \ No newline at end of file diff --git a/apps/docs/docs/user/valuetypes/_category_.json b/apps/docs/docs/user/valuetypes/_category_.json new file mode 100644 index 000000000..d69f22af2 --- /dev/null +++ b/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." + } +} diff --git a/apps/docs/docs/user/valuetypes/_category_.json.license b/apps/docs/docs/user/valuetypes/_category_.json.license new file mode 100644 index 000000000..17c5d2bad --- /dev/null +++ b/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 diff --git a/apps/docs/docs/user/valuetypes/primitive-valuetypes.md b/apps/docs/docs/user/valuetypes/primitive-valuetypes.md new file mode 100644 index 000000000..92400a538 --- /dev/null +++ b/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`. \ No newline at end of file diff --git a/apps/docs/docs/user/valuetypes/primitive-valuetypes.md.license b/apps/docs/docs/user/valuetypes/primitive-valuetypes.md.license new file mode 100644 index 000000000..17c5d2bad --- /dev/null +++ b/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 diff --git a/apps/docs/generator/src/main.ts b/apps/docs/generator/src/main.ts index fb81e33bc..ceeadf3b5 100644 --- a/apps/docs/generator/src/main.ts +++ b/apps/docs/generator/src/main.ts @@ -72,7 +72,7 @@ function generateConstraintTypeDocs(rootPath: string): void { } function generateValueTypeDocs(rootPath: string): void { - const docsPath = join(rootPath, 'apps', 'docs', 'docs', 'user'); + const docsPath = join(rootPath, 'apps', 'docs', 'docs', 'user', 'valuetypes'); const userDocBuilder = new UserDocGenerator(); const valueTypeDoc = userDocBuilder.generateValueTypesDoc(PrimitiveValuetypes); diff --git a/apps/docs/generator/src/user-doc-generator.ts b/apps/docs/generator/src/user-doc-generator.ts index 2e54cec18..23781d642 100644 --- a/apps/docs/generator/src/user-doc-generator.ts +++ b/apps/docs/generator/src/user-doc-generator.ts @@ -31,10 +31,10 @@ export class UserDocGenerator .generationComment() .description( ` -For an introduction to valuetypes, see the [Core Concepts](./core-concepts). +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\` -that fullfil [Constraints](./core-concepts#constraints).`.trim(), +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); @@ -71,6 +71,7 @@ block ExampleTableInterpreter oftype TableInterpreter { return builder.build(); } + generateBlockTypeDoc(metaInf: BlockMetaInformation): string { const builder = new UserDocMarkdownBuilder() .docTitle(metaInf.type)