Merge pull request #578 from jvalue/document-publish-use-feature

Document publish use feature
jvalue · May 29, 2024 · c2fd906 · c2fd906
2 parents daa04b5 + 06e82a8
commit c2fd906
Show file tree

Hide file tree

Showing 3 changed files with 93 additions and 67 deletions.
diff --git a/apps/docs/docs/user/core-concepts.md b/apps/docs/docs/user/core-concepts.md
@@ -107,15 +107,24 @@ constraint GasFillLevelRange on decimal:
     value >= 0 and value <= 100;
 
 publish GasFillLevelRange;
+publish GasFillLevelRange as PercentGasFillLevel; // Alias for renaming the published element
 ```
 
 2. Use the element in another file
 
 ```jayvee
 // Define from where you want to take elements
+
+// Wildcard "*" makes all published elements of the file available
 use * from './relative/path/to/file.jv';
 
+// Named use only makes the named elements available
+use { GasFillLevelRange } './relative/path/to/file.jv';
+use { GasFillLevelRange as FillLevelRange } './relative/path/to/file.jv'; // Alias locally renames elements
+
+
 // Then just use them as if they were defined on root level
+
 valuetype GasFillLevel oftype integer {
     constraints: [ GasFillLevelRange ]; // GasFillLevelRange is defined in another file
 }

diff --git a/example/electric-vehicles.jv b/example/electric-vehicles.jv
@@ -8,6 +8,11 @@
 // - Understand how to construct a pipeline with multiple sinks
 // - Understand the use of runtime parameters
 
+// 0. We can use elements defined in other files with the "use" syntax.
+// In this case, we use the value type UsStateCode when later specifying the table column value types. 
+use { UsStateCode } from './state-codes.jv';
+
+
 // 1. This Jayvee model describes a pipeline 
 // from a CSV file in the web 
 // to a SQLite file and a PostgreSQL db sink.
@@ -51,7 +56,7 @@ pipeline ElectricVehiclesPipeline {
       "VIN (1-10)" oftype VehicleIdentificationNumber10,
       "County" oftype text,
       "City" oftype text,
-      "State" oftype UsStateCode,
+      "State" oftype UsStateCode, // We can just use the element as if it was defined in this file.
       "Postal Code" oftype text,
       "Model Year" oftype integer,
       "Make" oftype text,
@@ -125,69 +130,3 @@ valuetype VehicleIdentificationNumber10 oftype text {
 constraint OnlyCapitalLettersAndDigits on text: value matches /^[A-Z0-9]*$/;
 
 constraint ExactlyTenCharacters on text: value.length == 10;
-
-valuetype UsStateCode oftype text {
-  constraints: [
-    UsStateCodeAllowlist,
-  ];
-}
-
-constraint UsStateCodeAllowlist on text: value in [
-  "AL",
-  "AK",
-  "AZ",
-  "AR",
-  "AS",
-  "CA",
-  "CO",
-  "CT",
-  "DE",
-  "DC",
-  "FL",
-  "GA",
-  "GU",
-  "HI",
-  "ID",
-  "IL",
-  "IN",
-  "IA",
-  "KS",
-  "KY",
-  "LA",
-  "ME",
-  "MD",
-  "MA",
-  "MI",
-  "MN",
-  "MS",
-  "MO",
-  "MT",
-  "NE",
-  "NV",
-  "NH",
-  "NJ",
-  "NM",
-  "NY",
-  "NC",
-  "ND",
-  "MP",
-  "OH",
-  "OK",
-  "OR",
-  "PA",
-  "PR",
-  "RI",
-  "SC",
-  "SD",
-  "TN",
-  "TX",
-  "TT",
-  "UT",
-  "VT",
-  "VA",
-  "VI",
-  "WA",
-  "WV",
-  "WI",
-  "WY",
-];
diff --git a/example/state-codes.jv b/example/state-codes.jv
@@ -0,0 +1,78 @@
+// SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// This file belongs to example 2: Electric Vehicles
+// Learning goals:
+// - Understand how to publish elements to use them in other files
+
+// 1. The publish keyword can be used directly when defining an element.
+publish valuetype UsStateCode oftype text {
+  constraints: [
+    UsStateCodeAllowlist,
+  ];
+}
+
+// 2. The publish keyword can be used after a definition as well (see below).
+// When using this delayed publish syntax, the published element can also be renamed. Doing so will make it available using the changed name whenever it is imported with the `use` syntax in another file. 
+constraint UsStateCodeAllowlist on text: value in [
+  "AL",
+  "AK",
+  "AZ",
+  "AR",
+  "AS",
+  "CA",
+  "CO",
+  "CT",
+  "DE",
+  "DC",
+  "FL",
+  "GA",
+  "GU",
+  "HI",
+  "ID",
+  "IL",
+  "IN",
+  "IA",
+  "KS",
+  "KY",
+  "LA",
+  "ME",
+  "MD",
+  "MA",
+  "MI",
+  "MN",
+  "MS",
+  "MO",
+  "MT",
+  "NE",
+  "NV",
+  "NH",
+  "NJ",
+  "NM",
+  "NY",
+  "NC",
+  "ND",
+  "MP",
+  "OH",
+  "OK",
+  "OR",
+  "PA",
+  "PR",
+  "RI",
+  "SC",
+  "SD",
+  "TN",
+  "TX",
+  "TT",
+  "UT",
+  "VT",
+  "VA",
+  "VI",
+  "WA",
+  "WV",
+  "WI",
+  "WY",
+];
+
+publish UsStateCodeAllowlist as UsStateCodeConstraint;