doc/tutorial/basics: various improvements
- added section for templates
- updated ambiguity in bottom.md
- several small fixes
Change-Id: Iac03e7b99eec1ea352cb30d815a8cfbfb6896b18
diff --git a/doc/tutorial/basics/Readme.md b/doc/tutorial/basics/Readme.md
index fa0deb7..3628a43 100644
--- a/doc/tutorial/basics/Readme.md
+++ b/doc/tutorial/basics/Readme.md
@@ -30,7 +30,7 @@
- [Aliases](aliases.md)
- [Emit Values](emit.md)
- [Hidden Values](hidden.md)
-- Types and Values
+- Types ~~and~~ are Values
- [Duplicate Fields](duplicates.md)
- [Bottom / Error](bottom.md)
- [Basic Types](types.md)
@@ -42,6 +42,7 @@
- [Ranges](ranges.md)
- [Predefined Ranges](rangedef.md)
- [Lists](lists.md)
+ - [Templates](templates.md)
- [Modules, Packages, and Instances](instances.md)
- [Packages](packages.md)
- [Imports](imports.md)
@@ -52,6 +53,6 @@
- [List Comprehensions](listcomp.md)
- [Field Comprehensions](fieldcomp.md)
- [Conditional Fields](conditional.md)
- - [Null or Error coalescing](coalescing.md)
+ - [Null or Error coalescing](coalesce.md)
<!-- - Conversions -->
<!-- - Functions (simulating) -->
diff --git a/doc/tutorial/basics/bottom.md b/doc/tutorial/basics/bottom.md
index 6a6ac5d..77be74b 100644
--- a/doc/tutorial/basics/bottom.md
+++ b/doc/tutorial/basics/bottom.md
@@ -1,15 +1,16 @@
[TOC](Readme.md) [Prev](duplicates.md) [Next](types.md)
-_Types and Values_
+_Types ~~and~~ are Values_
# Bottom
-Specifying duplicate fields with conflicting values results in an error,
-denoted `_|_`.
-
-Technically speaking, bottom is just a value like any other.
-But for all practical purposes it is okay to think of the bottom value
-as an error.
+Specifying duplicate fields with conflicting values results in an error
+or bottom.
+_Bottom_ is a special value in CUE, denoted `_|_`, that indicates an
+error such as incompatible values.
+Any error in CUE results in `_|_`.
+Logically all errors are equal, although errors may be associated with
+metadata such as an error message.
Note that an error is different from `null`: `null` is a valid JSON value,
whereas `_|_` is not.
@@ -21,10 +22,15 @@
l: [ 1, 2 ]
l: [ 1, 3 ]
+
+list: [0, 1, 2]
+val: list[3]
```
<!-- result -->
```
-a: _|_
-l: _|_
+a: _|_
+l: _|_
+list: [0, 1, 2]
+val: _|_
```
\ No newline at end of file
diff --git a/doc/tutorial/basics/coalesce.md b/doc/tutorial/basics/coalesce.md
index 41fbfce..3a487a0 100644
--- a/doc/tutorial/basics/coalesce.md
+++ b/doc/tutorial/basics/coalesce.md
@@ -11,12 +11,20 @@
In the example the fallback values are specified
for `a` and `b` in case the list index is out of bounds.
+To do actual null coalescing one can unify a result with the desired type
+to force an error.
+In that case the default will be used if either the lookup fails or
+the result is not of the desired type.
+
<!-- CUE editor -->
```
list: [ "Cat", "Mouse", "Dog" ]
a: list[0] | "None"
b: list[5] | "None"
+
+n: [null]
+v: n[0] & string | "default"
```
<!-- result -->
@@ -25,4 +33,6 @@
a: "Cat"
b: "None"
+n: [null]
+v: "default"
```
\ No newline at end of file
diff --git a/doc/tutorial/basics/defaults.md b/doc/tutorial/basics/defaults.md
index 642e621..a46825d 100644
--- a/doc/tutorial/basics/defaults.md
+++ b/doc/tutorial/basics/defaults.md
@@ -1,6 +1,6 @@
[TOC](Readme.md) [Prev](disjunctions.md) [Next](disjstruct.md)
-_Types and Values_
+_Types ~~and~~ are Values_
# Default Values
diff --git a/doc/tutorial/basics/disjstruct.md b/doc/tutorial/basics/disjstruct.md
index e60b63b..5cbc9ac 100644
--- a/doc/tutorial/basics/disjstruct.md
+++ b/doc/tutorial/basics/disjstruct.md
@@ -1,6 +1,6 @@
[TOC](Readme.md) [Prev](defaults.md) [Next](numbers.md)
-_Types and Values_
+_Types ~~and~~ are Values_
# Disjunctions of Structs
diff --git a/doc/tutorial/basics/disjunctions.md b/doc/tutorial/basics/disjunctions.md
index f9507ce..e049321 100644
--- a/doc/tutorial/basics/disjunctions.md
+++ b/doc/tutorial/basics/disjunctions.md
@@ -1,6 +1,6 @@
[TOC](Readme.md) [Prev](unification.md) [Next](defaults.md)
-_Types and Values_
+_Types ~~and~~ are Values_
# Disjunctions
diff --git a/doc/tutorial/basics/duplicates.md b/doc/tutorial/basics/duplicates.md
index 63509d9..7d754cf 100644
--- a/doc/tutorial/basics/duplicates.md
+++ b/doc/tutorial/basics/duplicates.md
@@ -1,6 +1,6 @@
[TOC](Readme.md) [Prev](hidden.md) [Next](bottom.md)
-_Types and Values_
+_Types ~~and~~ are Values_
# Duplicate Fields
diff --git a/doc/tutorial/basics/fieldcomp.md b/doc/tutorial/basics/fieldcomp.md
index dfb37d8..6723413 100644
--- a/doc/tutorial/basics/fieldcomp.md
+++ b/doc/tutorial/basics/fieldcomp.md
@@ -17,7 +17,7 @@
{
"\( strings.ToLower(v) )": {
- pos: k
+ pos: k + 1
name: v
nameLen: len(v)
} for k, v in a
diff --git a/doc/tutorial/basics/fieldname.md b/doc/tutorial/basics/fieldname.md
index 66da5a3..ab33ac9 100644
--- a/doc/tutorial/basics/fieldname.md
+++ b/doc/tutorial/basics/fieldname.md
@@ -16,6 +16,7 @@
{
one: 1,
two: 2,
+
"two-and-a-half": 2.5
}
```
diff --git a/doc/tutorial/basics/foldany.md b/doc/tutorial/basics/foldany.md
index 1bcab41..b933eb2 100644
--- a/doc/tutorial/basics/foldany.md
+++ b/doc/tutorial/basics/foldany.md
@@ -6,7 +6,7 @@
This also works if a struct has more than one member.
-In general, any JSON configuration can be expressed as a collection of
+In general, any JSON object can be expressed as a collection of
path-leaf pairs without using any curly braces.
<!-- CUE editor -->
diff --git a/doc/tutorial/basics/instances.md b/doc/tutorial/basics/instances.md
index 1b99949..55a65ff 100644
--- a/doc/tutorial/basics/instances.md
+++ b/doc/tutorial/basics/instances.md
@@ -1,4 +1,4 @@
-[TOC](Readme.md) [Prev](lists.md) [Next](packages.md)
+[TOC](Readme.md) [Prev](templates.md) [Next](packages.md)
# Modules, Packages, and Instances
@@ -8,8 +8,6 @@
A `package` clause allows a single configuration to be split across multiple
files.
-[Packages tutorial](packages.md)
-
## Instances
All files within a directory hierarchy with the same package identifier belong
diff --git a/doc/tutorial/basics/lists.md b/doc/tutorial/basics/lists.md
index d077a06..f583308 100644
--- a/doc/tutorial/basics/lists.md
+++ b/doc/tutorial/basics/lists.md
@@ -1,6 +1,6 @@
-[TOC](Readme.md) [Prev](ranges.md) [Next](instances.md)
+[TOC](Readme.md) [Prev](rangedef.md) [Next](templates.md)
-_Types and Values_
+_Types ~~and~~ are Values_
# Lists
diff --git a/doc/tutorial/basics/numbers.md b/doc/tutorial/basics/numbers.md
index 32f07a4..442d626 100644
--- a/doc/tutorial/basics/numbers.md
+++ b/doc/tutorial/basics/numbers.md
@@ -1,6 +1,6 @@
[TOC](Readme.md) [Prev](defaults.md) [Next](ranges.md)
-_Types and Values_
+_Types ~~and~~ are Values_
# Numbers
diff --git a/doc/tutorial/basics/rangedef.md b/doc/tutorial/basics/rangedef.md
index a854b6b..39da35b 100644
--- a/doc/tutorial/basics/rangedef.md
+++ b/doc/tutorial/basics/rangedef.md
@@ -1,6 +1,6 @@
[TOC](Readme.md) [Prev](ranges.md) [Next](lists.md)
-_Types and Values_
+_Types ~~and~~ are Values_
# Predefined Ranges
diff --git a/doc/tutorial/basics/ranges.md b/doc/tutorial/basics/ranges.md
index 6ef0efb..c37ea75 100644
--- a/doc/tutorial/basics/ranges.md
+++ b/doc/tutorial/basics/ranges.md
@@ -1,6 +1,6 @@
[TOC](Readme.md) [Prev](numbers.md) [Next](rangedef.md)
-_Types and Values_
+_Types ~~and~~ are Values_
# Ranges
diff --git a/doc/tutorial/basics/scopes.md b/doc/tutorial/basics/scopes.md
index 9945d08..f31bed7 100644
--- a/doc/tutorial/basics/scopes.md
+++ b/doc/tutorial/basics/scopes.md
@@ -8,7 +8,7 @@
enclosing scope.
If no field matches the reference within the file, it may match a top-level
-field of the same package.
+field defined in any other file of the same package.
If there is still no match, it may match a predefined value.
diff --git a/doc/tutorial/basics/templates.md b/doc/tutorial/basics/templates.md
new file mode 100644
index 0000000..d0d25ec
--- /dev/null
+++ b/doc/tutorial/basics/templates.md
@@ -0,0 +1,44 @@
+[TOC](Readme.md) [Prev](lists.md) [Next](instances.md)
+
+_Types ~~and~~ are Values_
+
+# Templates
+
+One of CUE's most powerful features is templates.
+A template defines a value to be unified which each field of a struct.
+
+The template's identifier (in angular brackets) is bound to name of each
+of its sibling fields and is visible within the template value
+that is unified with each of the siblings.
+
+```
+// The following struct is unified with all elements in job.
+// The name of each element is bound to Name and visible in the struct.
+job <Name>: {
+ name: Name
+ replicas: 1 | uint
+ command: string
+}
+
+job list command: "ls"
+
+job nginx: {
+ command: "nginx"
+ replicas: 2
+}
+```
+
+```
+job: {
+ list: {
+ name: "list"
+ replicas: 1
+ command: "ls"
+ }
+ nginx: {
+ name: "nginx"
+ replicas: 2
+ command: "nginx"
+ }
+}
+```
\ No newline at end of file
diff --git a/doc/tutorial/basics/types.md b/doc/tutorial/basics/types.md
index 5e64faa..e0f80da 100644
--- a/doc/tutorial/basics/types.md
+++ b/doc/tutorial/basics/types.md
@@ -1,6 +1,6 @@
[TOC](Readme.md) [Prev](bottom.md) [Next](unification.md)
-_Types and Values_
+_Types ~~and~~ are Values_
# Basic Types
@@ -14,6 +14,7 @@
int
float
```
+in addition to the error type mentioned in the previous section.
CUE does not distinguish between types and values.
A field value can be a type (using one of the above names), a concrete value,
diff --git a/doc/tutorial/basics/unification.md b/doc/tutorial/basics/unification.md
index 0d11bbf..bbca5ef 100644
--- a/doc/tutorial/basics/unification.md
+++ b/doc/tutorial/basics/unification.md
@@ -1,6 +1,6 @@
[TOC](Readme.md) [Prev](types.md) [Next](disjunctions.md)
-_Types and Values_
+_Types ~~and~~ are Values_
# Order is Irrelevant
