From 3fefd9a9789b7a796e012233e185dbaaf92f2daa Mon Sep 17 00:00:00 2001 From: Georg Schwarz Date: Tue, 9 Apr 2024 17:06:49 +0200 Subject: [PATCH 1/5] Make usage of block types and value types consistent in docs by using italic text --- .../docs/dev/04-guides/05-standard-library.md | 16 +++---- .../dev/04-guides/06-jayvee-extensions.md | 6 +-- .../docs/user/block-types/_category_.json | 2 +- apps/docs/docs/user/composite-blocks.md | 39 ++++++++------- .../user/constraint-types/_category_.json | 2 +- apps/docs/docs/user/core-concepts.md | 48 +++++++++---------- apps/docs/docs/user/expressions.md | 2 +- apps/docs/docs/user/runtime-parameters.md | 4 +- apps/docs/docs/user/transforms.md | 18 +++---- .../docs/user/value-types/_category_.json | 2 +- .../user/value-types/primitive-value-types.md | 25 +++++----- apps/docs/generator/src/user-doc-generator.ts | 12 ++--- example/cars.jv | 10 ++-- example/electric-vehicles.jv | 20 ++++---- 14 files changed, 104 insertions(+), 102 deletions(-) diff --git a/apps/docs/docs/dev/04-guides/05-standard-library.md b/apps/docs/docs/dev/04-guides/05-standard-library.md index e1dfbdbd2..80625207c 100644 --- a/apps/docs/docs/dev/04-guides/05-standard-library.md +++ b/apps/docs/docs/dev/04-guides/05-standard-library.md @@ -3,7 +3,7 @@ title: Working with the Standard Library sidebar_position: 5 --- -Jayvee ships with its own standard library on board, including the most often used valuetypes, transformations, and so on. +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 @@ -14,10 +14,10 @@ The following elements are part of the standard library: The implementations of builtin contents are not expressed in Jayvee itself but on the TypeScript layer. Examples: -- **Builtin valuetypes**: These valuetypes are the base for defining user-defined value types in Jayvee, e.g., `text`, `integer`, `decimal`, `boolean`. -- **Builtin iotypes**: These iotypes are used to describe in inputs and outputs of blocktypes, e.g., `Sheet`, `File`. -- **Builtin blocktypes**: These blocktypes 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 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. @@ -25,10 +25,10 @@ Builtin definitions are usually generated and added to the standard library from The implementations of user-defined contents are expressed in Jayvee itself. Examples: -- **User-defined valuetypes**: These valuetypes are based on builtin or other user-defined value types. Their definition is expressed natively in Jayvee, e.g., `Percent`. -- **User-defined blocktypes**: These blocktypes are based on builtin or other user-defined blocktypes. Their definition is expressed natively in Jayvee. +- **User-defined value types**: These _value types_ are based on builtin 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 builtin or other user-defined _block types_. Their definition is expressed natively in Jayvee. -We use `jv` files to add user-defined valuetypes to the standard library (see below). +We use `jv` files to add user-defined _value types_ to the standard library (see below). ## Extending the Standard Library diff --git a/apps/docs/docs/dev/04-guides/06-jayvee-extensions.md b/apps/docs/docs/dev/04-guides/06-jayvee-extensions.md index 55dca9172..1478f2f3f 100644 --- a/apps/docs/docs/dev/04-guides/06-jayvee-extensions.md +++ b/apps/docs/docs/dev/04-guides/06-jayvee-extensions.md @@ -86,9 +86,9 @@ export class StdExecExtension extends JayveeExecExtension { ### Add a new block type in a Jayvee extension -#### 1. Create a builtin blocktype +#### 1. Create a builtin block type -Define the syntax of the new blocktype in the [language server's builtin blocktypes](https://github.com/jvalue/jayvee/tree/main/libs/language-server/src/stdlib/builtin-blocktypes). +Define the syntax of the new _block type_ in the [language server's builtin _block types_](https://github.com/jvalue/jayvee/tree/main/libs/language-server/src/stdlib/builtin-blocktypes). The following example defines a block type `MyExtractor` with a text property called `url` and a property `retries` with a default value: @@ -166,7 +166,7 @@ export class MyExtractorExecutor > The interface `BlockExecutor` is used as an API for block executors. The abstract class `AbstractBlockExecutor` gives some further functionality for free, e.g., debug logging. > **Warning** -> The generic types of `AbstractBlockExecutor` need to match the input and output types of the corresponding `blocktype` definition. +> The generic types of `AbstractBlockExecutor` need to match the input and output types of the corresponding _block type_ definition. #### 4. Register the new `BlockExecutor` in the execution extension diff --git a/apps/docs/docs/user/block-types/_category_.json b/apps/docs/docs/user/block-types/_category_.json index 740dd2f28..63f8d0660 100644 --- a/apps/docs/docs/user/block-types/_category_.json +++ b/apps/docs/docs/user/block-types/_category_.json @@ -3,6 +3,6 @@ "position": 3, "link": { "type": "generated-index", - "description": "These blocks are shipped with Jayvee and are available right out of the box." + "description": "These block types are shipped with Jayvee and are available right out of the box." } } diff --git a/apps/docs/docs/user/composite-blocks.md b/apps/docs/docs/user/composite-blocks.md index 3db9e78f1..3ce4d9267 100644 --- a/apps/docs/docs/user/composite-blocks.md +++ b/apps/docs/docs/user/composite-blocks.md @@ -2,21 +2,24 @@ sidebar_position: 4 --- -# Composite Blocks +# Composite Block Types -Composite blocks are a way to create new blocktypes in Jayvee by combining the functionality of existing blocks and pipes. By relying on composite blocks instead of implementing more builtin blocks in a language interpreter, Jayvee supports easy extension by users. +_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 _builtin block types_ in a language interpreter, Jayvee supports easy extension by users. -Composite blocks define: -- with the `property` keyword: properties with a name and [value type](./core-concepts.md#valuetypes), 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 builtin or other composite blocks) +_Composite block types_ define: + +- with the `property` keyword: properties with a name and [value type](./core-concepts.md#value%20types), 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 _builtin_ or _composite block types_) ## Example -As an example, the common use-case of extracting a CSV file from a webserver using HTTP. With builtin blocks, 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 builtin blocks +As an example, the common use-case of extracting a CSV file from a web server using HTTP. With _builtin 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 builtin block types + ```mermaid flowchart LR A[HttpExtractor] --> B(TextFileInterpreter) @@ -25,13 +28,13 @@ flowchart LR D --> E[SQLiteSink] ``` -A pipeline with builtin blocks is very verbose: +A _pipeline_ with _blocks_ using _builtin block types_ is very verbose: ```jayvee pipeline CarsPipeline { CarsExtractor -> CarsTextFileInterpreter - -> CarsCSVInterpreter + -> CarsCSVInterpreter -> CarsTableInterpreter -> CarsLoader; @@ -48,12 +51,12 @@ pipeline CarsPipeline { } ``` -### Refactoring using composite blocks +### Refactoring using composite block types -The common use-case of downloading a CSV file using HTTP can be refactored into a composite block. Note that we define all properties of the builtin blocks that are used as properties of the new CSVExtractor blocktype (but add fallback values). If some internal configuration is always the same, we could also not expose it as a property of the new blocktype. +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 _builtin 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 blocktype named CSVExtractor outside of the pipeline +// Define a new block type named CSVExtractor outside of the pipeline composite blocktype CSVExtractor { // Properties of the CSVExtractor, some with default values property url oftype text; @@ -84,7 +87,7 @@ composite blocktype CSVExtractor { } ``` -With the new CSVExtractor composite blocktype, the pipeline now looks like this. +With the new `CSVExtractor` _composite block type_, the _pipeline_ now looks like this. ```mermaid flowchart LR @@ -97,7 +100,7 @@ flowchart LR 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. +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 { @@ -112,4 +115,4 @@ pipeline CarsPipeline { // ... further block definitions } -``` \ 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 cd8b13006..6cb00cc8c 100644 --- a/apps/docs/docs/user/constraint-types/_category_.json +++ b/apps/docs/docs/user/constraint-types/_category_.json @@ -3,6 +3,6 @@ "position": 6, "link": { "type": "generated-index", - "description": "These constraints are shipped with Jayvee and are available right out of the box." + "description": "These constraint types 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 f4cecb7da..222884376 100644 --- a/apps/docs/docs/user/core-concepts.md +++ b/apps/docs/docs/user/core-concepts.md @@ -4,13 +4,13 @@ sidebar_position: 2 # Core Concepts -The core concepts of Jayvee are `Pipelines`, `Blocks`, and `ValueTypes`. +The core concepts of Jayvee are _pipelines_, _blocks_, and _value types_. ## Pipelines -A `Pipeline` is a sequence of different computing steps, the `Blocks`. -The default output of a block becomes the default input of the next block, building a chain of computing steps. -In the scope of a `Pipeline`, you can connect these blocks via the `pipe` syntax: +A _pipeline_ is a sequence of different computing steps, the _blocks_. +The default output of a _block_ becomes the default input of the next _block_, building a chain of computing steps. +In the scope of a _pipeline_, you can connect these _blocks_ via the _pipe_ syntax: ```jayvee pipeline CarsPipeline { @@ -26,14 +26,14 @@ pipeline CarsPipeline { ## Blocks -A `Block` is a processing step within a `Pipeline`. +A _block_ is a processing step within a _pipeline_. It can have a default input and a default output. -We differentiate the following types of `Blocks`: -- `ExtractorBlocks` do not have a default input but only a default output. They model a **data source**. -- `TransformatorBlocks` have a default input and a default output. They model a **transformation**. -- `LoaderBlocks` do have a default input but nor a default output. They model a **data sink**. +We differentiate the following types of _blocks_: +- _Extractor blocks_ do not have a default input but only a default output. They model a **data source**. +- _Transformator blocks_ have a default input and a default output. They model a **transformation**. +- _Loader blocks_ do have a default input but nor a default output. They model a **data sink**. -The general structure of a `Pipeline` consisting of different blocks is the following: +The general structure of a _pipeline_ consisting of different blocks is the following: ```mermaid flowchart LR @@ -42,8 +42,8 @@ flowchart LR C --> D(LoaderBlock) ``` -The common syntax of blocks is at its core a key-value map to provide configuration to the block. -The availability of property keys and their respective `ValueTypes` is determined by the type of the `Block` - indicated by the identifier after the keyword `oftype`: +The common syntax of _blocks_ is at its core a key-value map to provide configuration to the _block_. +The availability of property keys and their respective _value types_ is determined by the type of the _block_, called _block type_ - indicated by the identifier after the keyword `oftype`: ```jayvee block GasReserveHttpExtractor oftype HttpExtractor { @@ -52,20 +52,20 @@ block GasReserveHttpExtractor oftype HttpExtractor { } ``` -In the example above, the `url` property of type `text` is defined by the corresponding `HttpExtractor` block type. +In the example above, the `url` property of type `text` is defined by the corresponding `HttpExtractor` _block type_. -Blocks can be either defined as part of the language, called `builtin` or defined as composition of existing blocks by users in Jayvee, called `composite`. See the documentation for [Composite Blocks](./composite-blocks.md). +_Blocks_ can be either defined as part of the language, called _builtin_ or defined as composition of existing _blocks_ by users in Jayvee, called _composite block types_. See the documentation for [_composite block types_](./composite-blocks.md). -## ValueTypes +## Value types -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](./value-types/builtin-value-types). -- `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 [Primitive Valuetypes](./value-types/primitive-value-types). -- `Compound ValueTypes`: UPCOMING. +A _value type_ is the definition of a data type of the processed data. +Some _blocks_ use _value types_ to define logic (like filtering or assessing the data type in a data sink). +We differentiate the following kinds of _value types_: +- _Built-in value types_ come with the basic version of Jayvee. See [built-in value types](./value-types/builtin-value-types). +- _Primitive value types_ can be defined by the user to model domain-specific data types and represent a single value. + _Constraints_ can be added to a _primitive value types_. +See [primitive value types](./value-types/primitive-value-types). +- _Compound value types_: UPCOMING. ```jayvee valuetype GasFillLevel oftype integer { @@ -77,7 +77,7 @@ constraint GasFillLevelRange on decimal: ``` ## Transforms -`Transforms` are used to transform data from one `ValueType` to a different one. For more details, see [Transforms](./transforms.md). +_Transforms_ are used to transform data from one _value type_ to a different one. For more details, see [transforms](./transforms.md). ```jayvee transform CelsiusToKelvin { diff --git a/apps/docs/docs/user/expressions.md b/apps/docs/docs/user/expressions.md index 6c4518fbf..69c09ae12 100644 --- a/apps/docs/docs/user/expressions.md +++ b/apps/docs/docs/user/expressions.md @@ -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](./value-types/builtin-value-types). +Expressions get evaluated at runtime by the interpreter to a [built-in _value type_](./value-types/builtin-value-types). ### Example diff --git a/apps/docs/docs/user/runtime-parameters.md b/apps/docs/docs/user/runtime-parameters.md index bbdab1ed4..d0620d14c 100644 --- a/apps/docs/docs/user/runtime-parameters.md +++ b/apps/docs/docs/user/runtime-parameters.md @@ -4,11 +4,11 @@ sidebar_position: 9 # Runtime Parameters -Property values in Jayvee can be assigned to `values` or left open for later configuration via `runtime parameters`. +Property values in Jayvee can be assigned to _values_ or left open for later configuration via _runtime parameters_. ## Syntax -Runtime parameters are indicated by the `requires` keyword, followed by the identifier of the parameter. Example +_Runtime parameters_ are indicated by the `requires` keyword, followed by the identifier of the parameter. Example ```jayvee block CarsLoader oftype SQLiteLoader { diff --git a/apps/docs/docs/user/transforms.md b/apps/docs/docs/user/transforms.md index bf3dfd7d9..468a22cb9 100644 --- a/apps/docs/docs/user/transforms.md +++ b/apps/docs/docs/user/transforms.md @@ -4,8 +4,8 @@ sidebar_position: 8 # Transforms -Transforms are a concept in Jayvee to define the transformation of individual values. -They are similar to functions in programming languages, i.e. they perform computations on some input values and produce output values. Transform work by mapping input values to outputs using [expressions](./expressions.md). +_Transforms_ are a concept in Jayvee to define the transformation of individual values. +They are similar to functions in programming languages, i.e. they perform computations on some input values and produce output values. _Transforms_ work by mapping input values to outputs using [expressions](./expressions.md). :::info Important @@ -23,23 +23,23 @@ For the future, it is planned to support arbitrary numbers for outputs as well. ## Syntax -The general syntax of transforms looks like this: +The general syntax of _transforms_ looks like this: ```jayvee transform { - from oftype ; - to oftype ; + from oftype ; + to oftype ; : ; } ``` -The `transform` keyword is used to define a transform and give it a name. -The curly braces denote the body of the transform. +The `transform` keyword is used to define a _transform_ and give it a name. +The curly braces denote the body of the _transform_. The body first contains the definitions of input and output ports. Input ports are defined using the `from` keyword whereas output ports use the `to` keyword. -Next, they are given a name and, after the `oftype` keyword, typed with a valuetype. +Next, they are given a name and, after the `oftype` keyword, typed with a _value type_. Below, there needs to be an output assignment for each output port. The output assignment defines how a particular output value is computed. @@ -60,7 +60,7 @@ transform CelsiusToKelvin { } ``` -The following transform converts a text based status into a boolean value, `true` if the text is `Active`, `false` for any other value: +The following _transform_ converts a text based status into a boolean value, `true` if the text is `Active`, `false` for any other value: ```jayvee transform StatusToBoolean { diff --git a/apps/docs/docs/user/value-types/_category_.json b/apps/docs/docs/user/value-types/_category_.json index 5dde1e0a1..37375108e 100644 --- a/apps/docs/docs/user/value-types/_category_.json +++ b/apps/docs/docs/user/value-types/_category_.json @@ -1,5 +1,5 @@ { - "label": "ValueTypes", + "label": "Value Types", "position": 5, "link": { "type": "generated-index", diff --git a/apps/docs/docs/user/value-types/primitive-value-types.md b/apps/docs/docs/user/value-types/primitive-value-types.md index 92400a538..4fac4b448 100644 --- a/apps/docs/docs/user/value-types/primitive-value-types.md +++ b/apps/docs/docs/user/value-types/primitive-value-types.md @@ -1,11 +1,12 @@ --- 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`: +# Primitive Value Types + +_Primitive value types_ are based on _built-in value types_ 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 _value type_ - indicated by the identifier after the keyword `oftype`: ```jayvee valuetype GasFillLevel oftype integer { @@ -13,27 +14,25 @@ valuetype GasFillLevel oftype integer { } ``` - ## Constraints -`Constraints` for `ValueTypes` declare the validity criteria that each concrete value is checked against. +_Constraints_ for _value types_ 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`: +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. - +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`: +The syntax of _constraints_ is similar to the syntax of _blocks_. +The availability of property keys and their respective _value types_ is determined by the type of the _constraint_ - indicated by the identifier after the keyword `oftype`: ```jayvee constraint GasFillLevelRange oftype RangeConstraint { @@ -44,5 +43,5 @@ constraint GasFillLevelRange oftype RangeConstraint { } ``` -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 +Note that the type of _constraint_ also determines its applicability to _value types_. +For instance, a `RangeConstraint` can only be applied to the numerical types `integer` and `decimal`. diff --git a/apps/docs/generator/src/user-doc-generator.ts b/apps/docs/generator/src/user-doc-generator.ts index c7244a57b..115e25555 100644 --- a/apps/docs/generator/src/user-doc-generator.ts +++ b/apps/docs/generator/src/user-doc-generator.ts @@ -30,14 +30,14 @@ export class UserDocGenerator valueTypes: Record, ): string { const builder = new UserDocMarkdownBuilder() - .docTitle('Built-in ValueTypes') + .docTitle('Built-in Value Types') .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-value-types) -that fullfil [Constraints](./primitive-value-types#constraints).`.trim(), +For an introduction to _value types_, see the [core concepts](../core-concepts). +_Built-in value types_ come with the basic version of Jayvee. +They are the basis for more restricted [_primitive value types_](./primitive-value-types) +that fullfil [_constraints_](./primitive-value-types#constraints).`.trim(), 1, ) .heading('Available built-in value types', 1); @@ -236,7 +236,7 @@ class UserDocMarkdownBuilder { } compatibleValueType(type: string): UserDocMarkdownBuilder { - this.markdownBuilder.line(`Compatible ValueType: ${type}`); + this.markdownBuilder.line(`Compatible value type: ${type}`); this.markdownBuilder.newLine(); return this; } diff --git a/example/cars.jv b/example/cars.jv index 2100e65e7..f4fbb25d8 100644 --- a/example/cars.jv +++ b/example/cars.jv @@ -36,8 +36,8 @@ pipeline CarsPipeline { // 6. Below the pipes, we usually define the blocks // that are connected by the pipes. - // 7. Blocks instantiate a blocktype by using the oftype keyword. - // The blocktype defines the available properties that the block + // 7. Blocks instantiate a block type by using the oftype keyword. + // The block type defines the available properties that the block // can use to specify the intended behavior of the block block CarsExtractor oftype HttpExtractor { @@ -56,7 +56,7 @@ pipeline CarsPipeline { enclosing: '"'; } - // 11. We can write into cells of a sheet using the CellWriter blocktype. + // 11. We can write into cells of a sheet using the CellWriter block type. block NameHeaderWriter oftype CellWriter { // 12. We utilize a syntax similar to spreadsheet programs. // Cell ranges can be described using the keywords "cell", "row", "column", or "range" that indicate which @@ -69,8 +69,8 @@ pipeline CarsPipeline { } // 14. As a next step, we interpret the sheet as a table by adding structure. - // We define a valuetype per column that specifies the data type of the column. - // Rows that include values that are not valid according to the their valuetypes are dropped automatically. + // We define a value type per column that specifies the data type of the column. + // Rows that include values that are not valid according to the their value types are dropped automatically. block CarsTableInterpreter oftype TableInterpreter { header: true; columns: [ diff --git a/example/electric-vehicles.jv b/example/electric-vehicles.jv index b85171e34..a1a85c7b7 100644 --- a/example/electric-vehicles.jv +++ b/example/electric-vehicles.jv @@ -4,7 +4,7 @@ // Example 2: Electric Vehicles // Learning goals: -// - Understand further core concepts transforms and valuetypes +// - Understand further core concepts transforms and value types // - Understand how to construct a pipeline with multiple sinks // - Understand the use of runtime parameters @@ -45,9 +45,9 @@ pipeline ElectricVehiclesPipeline { block ElectricVehiclesTableInterpreter oftype TableInterpreter { header: true; columns: [ - // 4. Here, a user-deifned valuetype is used to describe this column. - // The capital letter indicates that the valuetype is not builtin - // by convention. The valuetype itself is defined further below. + // 4. Here, a user-deifned value type is used to describe this column. + // The capital letter indicates that the value type is not builtin + // by convention. The value type itself is defined further below. "VIN (1-10)" oftype VehicleIdentificationNumber10, "County" oftype text, "City" oftype text, @@ -80,7 +80,7 @@ pipeline ElectricVehiclesPipeline { // 6. Here, we define a transform function, taking parameters // as input ("from" keyword), and producing an output ("to" keyword). - // Inputs and outputs have to be further described by a valuetype. + // Inputs and outputs have to be further described by a value type. transform MilesToKilometers { from miles oftype decimal; to kilometers oftype integer; @@ -107,18 +107,18 @@ pipeline ElectricVehiclesPipeline { } } -// 9. Below the pipeline, we model user-define valuetypes. -// We give them a speaking name and provide a base valuetype -// that this valuetype builts on. User-defined valuetypes always place additional constraints on existing valuetypes. +// 9. Below the pipeline, we model user-define value types. +// We give them a speaking name and provide a base value type +// that this value type builts on. User-defined value types always place additional constraints on existing value types. valuetype VehicleIdentificationNumber10 oftype text { - // 10. Valuetypes can be further refined by providing constraints. + // 10. Value types can be further refined by providing constraints. constraints: [ OnlyCapitalLettersAndDigits, ExactlyTenCharacters, ]; } -// 11. This constraint works on text valuetypes and requires values +// 11. This constraint works on text value types and requires values // to match a given regular expression in order to be valid. constraint OnlyCapitalLettersAndDigits on text: value matches /^[A-Z0-9]*$/; From 1ef15372d0b3a0c70791fd4b62851dc49d9826ba Mon Sep 17 00:00:00 2001 From: Georg Schwarz Date: Tue, 9 Apr 2024 17:09:31 +0200 Subject: [PATCH 2/5] Consistently write "built-in" instead of "builtin" in docs --- apps/docs/docs/dev/04-guides/05-standard-library.md | 8 ++++---- apps/docs/docs/dev/04-guides/06-jayvee-extensions.md | 4 ++-- apps/docs/docs/user/composite-blocks.md | 12 ++++++------ apps/docs/docs/user/core-concepts.md | 2 +- 4 files changed, 13 insertions(+), 13 deletions(-) diff --git a/apps/docs/docs/dev/04-guides/05-standard-library.md b/apps/docs/docs/dev/04-guides/05-standard-library.md index 80625207c..2da1646f0 100644 --- a/apps/docs/docs/dev/04-guides/05-standard-library.md +++ b/apps/docs/docs/dev/04-guides/05-standard-library.md @@ -12,7 +12,7 @@ The following elements are part of the standard library: ## Builtin Contents -The implementations of builtin contents are not expressed in Jayvee itself but on the TypeScript layer. Examples: +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`. @@ -25,8 +25,8 @@ Builtin definitions are usually generated and added to the standard library from The implementations of user-defined contents are expressed in Jayvee itself. Examples: -- **User-defined value types**: These _value types_ are based on builtin 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 builtin or other user-defined _block types_. Their definition is expressed natively in Jayvee. +- **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). @@ -42,7 +42,7 @@ We use code generation to transform these `.jv` files into TypeScript files that ### 2. Builtin libraries -The solution we chose to implement the standard library mechanism is close to the [builtin library tutorial](https://langium.org/guides/builtin-library/) by Langium. The following components are of interest: +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/docs/dev/04-guides/06-jayvee-extensions.md b/apps/docs/docs/dev/04-guides/06-jayvee-extensions.md index 1478f2f3f..e10d24313 100644 --- a/apps/docs/docs/dev/04-guides/06-jayvee-extensions.md +++ b/apps/docs/docs/dev/04-guides/06-jayvee-extensions.md @@ -86,9 +86,9 @@ export class StdExecExtension extends JayveeExecExtension { ### Add a new block type in a Jayvee extension -#### 1. Create a builtin block type +#### 1. Create a built-in block type -Define the syntax of the new _block type_ in the [language server's builtin _block types_](https://github.com/jvalue/jayvee/tree/main/libs/language-server/src/stdlib/builtin-blocktypes). +Define the syntax of the new _block type_ in the [language server's built-in _block types_](https://github.com/jvalue/jayvee/tree/main/libs/language-server/src/stdlib/builtin-blocktypes). The following example defines a block type `MyExtractor` with a text property called `url` and a property `retries` with a default value: diff --git a/apps/docs/docs/user/composite-blocks.md b/apps/docs/docs/user/composite-blocks.md index 3ce4d9267..20d1566ba 100644 --- a/apps/docs/docs/user/composite-blocks.md +++ b/apps/docs/docs/user/composite-blocks.md @@ -4,7 +4,7 @@ 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 _builtin block types_ in a language interpreter, Jayvee supports easy extension by users. +_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: @@ -12,13 +12,13 @@ _Composite block types_ define: - 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 _builtin_ or _composite block types_) +- 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 _builtin 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`). +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 builtin block types +### Implementation with built-in block types ```mermaid flowchart LR @@ -28,7 +28,7 @@ flowchart LR D --> E[SQLiteSink] ``` -A _pipeline_ with _blocks_ using _builtin block types_ is very verbose: +A _pipeline_ with _blocks_ using _built-in block types_ is very verbose: ```jayvee pipeline CarsPipeline { @@ -53,7 +53,7 @@ pipeline CarsPipeline { ### 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 _builtin 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_. +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 block type named CSVExtractor outside of the pipeline diff --git a/apps/docs/docs/user/core-concepts.md b/apps/docs/docs/user/core-concepts.md index 222884376..467f1a59f 100644 --- a/apps/docs/docs/user/core-concepts.md +++ b/apps/docs/docs/user/core-concepts.md @@ -54,7 +54,7 @@ block GasReserveHttpExtractor oftype HttpExtractor { In the example above, the `url` property of type `text` is defined by the corresponding `HttpExtractor` _block type_. -_Blocks_ can be either defined as part of the language, called _builtin_ or defined as composition of existing _blocks_ by users in Jayvee, called _composite block types_. See the documentation for [_composite block types_](./composite-blocks.md). +_Blocks_ can be either defined as part of the language, called _built-in_ or defined as composition of existing _blocks_ by users in Jayvee, called _composite block types_. See the documentation for [_composite block types_](./composite-blocks.md). ## Value types From b8697a825dfd7abcc1fe3803d22682c1d364ff64 Mon Sep 17 00:00:00 2001 From: Georg Schwarz Date: Tue, 9 Apr 2024 17:13:49 +0200 Subject: [PATCH 3/5] Rename composite-blocks.md to composite-block-types.md --- .../docs/user/{composite-blocks.md => composite-block-types.md} | 2 +- ...osite-blocks.md.license => composite-block-types.md.license} | 0 apps/docs/docs/user/core-concepts.md | 2 +- 3 files changed, 2 insertions(+), 2 deletions(-) rename apps/docs/docs/user/{composite-blocks.md => composite-block-types.md} (98%) rename apps/docs/docs/user/{composite-blocks.md.license => composite-block-types.md.license} (100%) diff --git a/apps/docs/docs/user/composite-blocks.md b/apps/docs/docs/user/composite-block-types.md similarity index 98% rename from apps/docs/docs/user/composite-blocks.md rename to apps/docs/docs/user/composite-block-types.md index 20d1566ba..d7ea1ec1d 100644 --- a/apps/docs/docs/user/composite-blocks.md +++ b/apps/docs/docs/user/composite-block-types.md @@ -8,7 +8,7 @@ _Composite block types_ are a way to create new _block types_ in Jayvee by combi _Composite block types_ define: -- with the `property` keyword: properties with a name and [value type](./core-concepts.md#value%20types), optionally a default value +- 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) diff --git a/apps/docs/docs/user/composite-blocks.md.license b/apps/docs/docs/user/composite-block-types.md.license similarity index 100% rename from apps/docs/docs/user/composite-blocks.md.license rename to apps/docs/docs/user/composite-block-types.md.license diff --git a/apps/docs/docs/user/core-concepts.md b/apps/docs/docs/user/core-concepts.md index 467f1a59f..3736280c5 100644 --- a/apps/docs/docs/user/core-concepts.md +++ b/apps/docs/docs/user/core-concepts.md @@ -54,7 +54,7 @@ block GasReserveHttpExtractor oftype HttpExtractor { In the example above, the `url` property of type `text` is defined by the corresponding `HttpExtractor` _block type_. -_Blocks_ can be either defined as part of the language, called _built-in_ or defined as composition of existing _blocks_ by users in Jayvee, called _composite block types_. See the documentation for [_composite block types_](./composite-blocks.md). +_Blocks_ can be either defined as part of the language, called _built-in_ or defined as composition of existing _blocks_ by users in Jayvee, called _composite block types_. See the documentation for [_composite block types_](./composite-block-types.md). ## Value types From 94509a3fa6305aadad663b00e89bdc084a360f4a Mon Sep 17 00:00:00 2001 From: Georg Schwarz Date: Fri, 12 Apr 2024 15:06:55 +0200 Subject: [PATCH 4/5] Update apps/docs/docs/user/composite-block-types.md Co-authored-by: Philip Heltweg --- apps/docs/docs/user/composite-block-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/docs/docs/user/composite-block-types.md b/apps/docs/docs/user/composite-block-types.md index d7ea1ec1d..e0e9df159 100644 --- a/apps/docs/docs/user/composite-block-types.md +++ b/apps/docs/docs/user/composite-block-types.md @@ -56,7 +56,7 @@ pipeline CarsPipeline { 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 block type named CSVExtractor outside of the pipeline +// 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; From fc998d5ad8b1308b913ce4593f17471c0eb8b54e Mon Sep 17 00:00:00 2001 From: Georg Schwarz Date: Fri, 12 Apr 2024 15:14:48 +0200 Subject: [PATCH 5/5] Use "built-in" instead of "builtin" in docs file names --- apps/docs/docs/user/core-concepts.md | 2 +- apps/docs/docs/user/expressions.md | 2 +- apps/docs/docs/user/value-types/.gitignore | 2 +- apps/docs/generator/src/main.ts | 2 +- example/electric-vehicles.jv | 2 +- libs/interpreter-lib/src/std-extension.spec.ts | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/apps/docs/docs/user/core-concepts.md b/apps/docs/docs/user/core-concepts.md index 3736280c5..4c8cf91a0 100644 --- a/apps/docs/docs/user/core-concepts.md +++ b/apps/docs/docs/user/core-concepts.md @@ -61,7 +61,7 @@ _Blocks_ can be either defined as part of the language, called _built-in_ or def A _value type_ is the definition of a data type of the processed data. Some _blocks_ use _value types_ to define logic (like filtering or assessing the data type in a data sink). We differentiate the following kinds of _value types_: -- _Built-in value types_ come with the basic version of Jayvee. See [built-in value types](./value-types/builtin-value-types). +- _Built-in value types_ come with the basic version of Jayvee. See [built-in value types](./value-types/built-in-value-types). - _Primitive value types_ can be defined by the user to model domain-specific data types and represent a single value. _Constraints_ can be added to a _primitive value types_. See [primitive value types](./value-types/primitive-value-types). diff --git a/apps/docs/docs/user/expressions.md b/apps/docs/docs/user/expressions.md index 69c09ae12..6cff26dea 100644 --- a/apps/docs/docs/user/expressions.md +++ b/apps/docs/docs/user/expressions.md @@ -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 _value type_](./value-types/builtin-value-types). +Expressions get evaluated at runtime by the interpreter to a [built-in _value type_](./value-types/built-in-value-types). ### Example diff --git a/apps/docs/docs/user/value-types/.gitignore b/apps/docs/docs/user/value-types/.gitignore index 63f1c91c7..ba5551551 100644 --- a/apps/docs/docs/user/value-types/.gitignore +++ b/apps/docs/docs/user/value-types/.gitignore @@ -2,4 +2,4 @@ # # SPDX-License-Identifier: AGPL-3.0-only -builtin-value-types.md \ No newline at end of file +built-in-value-types.md \ No newline at end of file diff --git a/apps/docs/generator/src/main.ts b/apps/docs/generator/src/main.ts index 280b018d7..f2bf16ec9 100644 --- a/apps/docs/generator/src/main.ts +++ b/apps/docs/generator/src/main.ts @@ -105,7 +105,7 @@ function generateValueTypeDocs( const valueTypeDoc = userDocBuilder.generateValueTypesDoc(PrimitiveValuetypes); - const fileName = `builtin-value-types.md`; + const fileName = `built-in-value-types.md`; writeFileSync(join(docsPath, fileName), valueTypeDoc, { flag: 'w', }); diff --git a/example/electric-vehicles.jv b/example/electric-vehicles.jv index a1a85c7b7..154d69d9a 100644 --- a/example/electric-vehicles.jv +++ b/example/electric-vehicles.jv @@ -46,7 +46,7 @@ pipeline ElectricVehiclesPipeline { header: true; columns: [ // 4. Here, a user-deifned value type is used to describe this column. - // The capital letter indicates that the value type is not builtin + // The capital letter indicates that the value type is not built-in // by convention. The value type itself is defined further below. "VIN (1-10)" oftype VehicleIdentificationNumber10, "County" oftype text, diff --git a/libs/interpreter-lib/src/std-extension.spec.ts b/libs/interpreter-lib/src/std-extension.spec.ts index 4ee55077b..ff45b9562 100644 --- a/libs/interpreter-lib/src/std-extension.spec.ts +++ b/libs/interpreter-lib/src/std-extension.spec.ts @@ -23,7 +23,7 @@ async function loadAllBuiltinBlocktypes(): Promise { } describe('std extension', () => { - it('should provide matching block executors for builtin block types', async () => { + it('should provide matching block executors for built-in block types', async () => { (await loadAllBuiltinBlocktypes()).forEach( (blockType: BlockTypeWrapper) => { const execExtension = new StdExecExtension();