doc/tutorial/basics: add pieces on structs and definitions
Change-Id: I3eba3ff6835804e76af03e8c26ff8d8814a2b77f
Reviewed-on: https://cue-review.googlesource.com/c/cue/+/3680
Reviewed-by: Marcel van Lohuizen <mpvl@golang.org>
diff --git a/doc/tutorial/basics/2_types/40_numbers.txt b/doc/tutorial/basics/2_types/30_numbers.txt
similarity index 77%
rename from doc/tutorial/basics/2_types/40_numbers.txt
rename to doc/tutorial/basics/2_types/30_numbers.txt
index 645ecb1..4af9dd3 100644
--- a/doc/tutorial/basics/2_types/40_numbers.txt
+++ b/doc/tutorial/basics/2_types/30_numbers.txt
@@ -16,6 +16,8 @@
In the example, the result of `b` is a `float` and cannot be
used as an `int` without conversion.
+CUE also adds a variety of sugar for writing numbers.
+
-- numbers.cue --
a: int
a: 4 // type int
@@ -28,8 +30,16 @@
d: 4 // will evaluate to type int (default)
+e: [
+ 1_234, // 1234
+ 5M, // 5_000_000
+ 1.5Gi, // 1_610_612_736
+ 0x1000_0000, // 268_435_456
+]
+
-- expect-stdout-cue --
a: 4
b: 4.0
c: _|_ // conflicting values int and 4.0 (mismatched types int and float)
d: 4
+e: [1234, 5000000, 1610612736, 268435456]
diff --git a/doc/tutorial/basics/2_types/30_types.txt b/doc/tutorial/basics/2_types/30_types.txt
deleted file mode 100644
index 94792ee..0000000
--- a/doc/tutorial/basics/2_types/30_types.txt
+++ /dev/null
@@ -1,64 +0,0 @@
-cue eval types.cue
-cmp stdout expect-stdout-cue
-
--- frontmatter.toml --
-title = "Basic Types"
-description = ""
-
--- text.md --
-CUE defines the following basic types
-
-```
-null bool string bytes 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,
-or, in case of composite types (lists and structs), anything in between.
-
-In the example, `point` defines an arbitrary point, while `xaxis` and `yaxis`
-define the points on the respective lines.
-We say that `point`, `xaxis`, and `yaxis` are abstract points, as these
-points are underspecified.
-Such abstract values cannot be represented as JSON,
-which requires all values to be concrete.
-
-The only concrete point is `origin`.
-The `origin` is defined to be both on the x-axis and y-axis, which means it
-must be at `0, 0`.
-Here we see constraints in action:
-`origin` evalutes to `0, 0`, even though we did not specify its coordinates
-explicitly.
-
--- types.cue --
-point: {
- x: number
- y: number
-}
-
-xaxis: point
-xaxis x: 0
-
-yaxis: point
-yaxis y: 0
-
-origin: xaxis & yaxis
-
--- expect-stdout-cue --
-point: {
- x: number
- y: number
-}
-xaxis: {
- x: 0
- y: number
-}
-yaxis: {
- x: number
- y: 0
-}
-origin: {
- x: 0
- y: 0
-}
diff --git a/doc/tutorial/basics/2_types/60_stringlit.txt b/doc/tutorial/basics/2_types/40_stringlit.txt
similarity index 100%
rename from doc/tutorial/basics/2_types/60_stringlit.txt
rename to doc/tutorial/basics/2_types/40_stringlit.txt
diff --git a/doc/tutorial/basics/2_types/45_numberlit.txt b/doc/tutorial/basics/2_types/45_numberlit.txt
deleted file mode 100644
index c6da95d..0000000
--- a/doc/tutorial/basics/2_types/45_numberlit.txt
+++ /dev/null
@@ -1,25 +0,0 @@
-cue export numlit.cue
-cmp stdout expect-stdout-cue
-
--- frontmatter.toml --
-title = "Number Literals"
-description = ""
-
--- text.md --
-CUE adds a variety of sugar for writing numbers.
-
--- numlit.cue --
-[
- 1_234, // 1234
- 5M, // 5_000_000
- 1.5Gi, // 1_610_612_736
- 0x1000_0000, // 268_435_456
-]
-
--- expect-stdout-cue --
-[
- 1234,
- 5000000,
- 1610612736,
- 268435456
-]
diff --git a/doc/tutorial/basics/2_types/65_stringraw.txt b/doc/tutorial/basics/2_types/45_stringraw.txt
similarity index 100%
rename from doc/tutorial/basics/2_types/65_stringraw.txt
rename to doc/tutorial/basics/2_types/45_stringraw.txt
diff --git a/doc/tutorial/basics/2_types/68_bytes.txt b/doc/tutorial/basics/2_types/48_bytes.txt
similarity index 100%
rename from doc/tutorial/basics/2_types/68_bytes.txt
rename to doc/tutorial/basics/2_types/48_bytes.txt
diff --git a/doc/tutorial/basics/2_types/50_closed.txt b/doc/tutorial/basics/2_types/50_closed.txt
new file mode 100644
index 0000000..50b3ade
--- /dev/null
+++ b/doc/tutorial/basics/2_types/50_closed.txt
@@ -0,0 +1,33 @@
+cue eval -i structs.cue
+cmp stdout expect-stdout-cue
+
+-- frontmatter.toml --
+title = "Closed structs"
+description = ""
+
+-- text.md --
+Struct is the most important composite type in CUE.
+
+A struct may be open or closed.
+A closed struct may only be merged with structs that have fields that
+it defines to be allowed.
+In other words, closing a struct is equivalent to requiring that all
+other values be undefined.
+
+A closed struct can be created using the `closed` builtin,
+but are more commonly defined using a _definition_, defined next.
+
+-- structs.cue --
+a: close({
+ field: int
+})
+
+b: a & {
+ feild: 3
+}
+
+-- expect-stdout-cue --
+a: {
+ field: int
+}
+b: _|_ // field "feild" not allowed in closed struct
diff --git a/doc/tutorial/basics/2_types/55_defs.txt b/doc/tutorial/basics/2_types/55_defs.txt
new file mode 100644
index 0000000..6817ba5
--- /dev/null
+++ b/doc/tutorial/basics/2_types/55_defs.txt
@@ -0,0 +1,33 @@
+cue eval -ic defs.cue
+cmp stdout expect-stdout-cue
+
+-- frontmatter.toml --
+title = "Definitions"
+description = ""
+
+-- text.md --
+A definition, denoted with `::` instead of `:`, defines values that
+are not output when converting a configuration to a concrete value.
+They are used to define schemata against which concrete values can
+be validated.
+
+Structs defined by definitions are implicitly closed.
+
+-- defs.cue --
+msg: "Hello \(Name)!"
+
+Name :: "world"
+
+A :: {
+ field: int
+}
+
+a: A & { field: 3 }
+err: A & { feild: 3 }
+
+-- expect-stdout-cue --
+msg: "Hello world!"
+a: {
+ field: 3
+}
+err: _|_ // field "feild" not allowed in closed struct
diff --git a/doc/tutorial/basics/2_types/56_optional.txt b/doc/tutorial/basics/2_types/56_optional.txt
new file mode 100644
index 0000000..bc5f342
--- /dev/null
+++ b/doc/tutorial/basics/2_types/56_optional.txt
@@ -0,0 +1,35 @@
+cue eval -c structs.cue
+cmp stdout expect-stdout-cue
+
+-- frontmatter.toml --
+title = "Structs"
+description = ""
+
+-- text.md --
+Struct is the most important composite type in CUE.
+It's members are called fields.
+
+A struct field may be optional.
+One can use an optional field to indicate what the type should be if it were
+specified.
+A regular (or required) field, on the other hand, must be made concrete
+for a configuration to be converted to, say, JSON.
+
+It is okay for an optional field to be bottom (`_|_`).
+This just means that field may not be specified.
+
+-- structs.cue --
+a :: {
+ foo?: int
+ bar?: string
+ baz?: string
+}
+b: a & {
+ foo: 3
+ baz?: 2 // baz?: _|_
+}
+
+-- expect-stdout-cue --
+b: {
+ foo: 3
+}
diff --git a/doc/tutorial/basics/2_types/50_disjunctions.txt b/doc/tutorial/basics/2_types/60_disjunctions.txt
similarity index 79%
rename from doc/tutorial/basics/2_types/50_disjunctions.txt
rename to doc/tutorial/basics/2_types/60_disjunctions.txt
index 99bb955..2c1b1f9 100644
--- a/doc/tutorial/basics/2_types/50_disjunctions.txt
+++ b/doc/tutorial/basics/2_types/60_disjunctions.txt
@@ -8,9 +8,9 @@
-- text.md --
Disjunctions, or sum types, define a new type that is one of several things.
-In the example, `conn` defines a `protocol` field that must be one of two
-values: `"tcp"` or `"udp"`.
-It is an error for a concrete `conn`
+In the example, our `Conn` definition of earlier is augmented to define
+the possible values for `protocol`: `"tcp"` or `"udp"`.
+It is an error for a concrete `Conn`
to define anything else than these two values.
-- disjunctions.cue --
diff --git a/doc/tutorial/basics/2_types/55_defaults.txt b/doc/tutorial/basics/2_types/65_defaults.txt
similarity index 100%
rename from doc/tutorial/basics/2_types/55_defaults.txt
rename to doc/tutorial/basics/2_types/65_defaults.txt
diff --git a/doc/tutorial/basics/2_types/55_sumstruct.txt b/doc/tutorial/basics/2_types/65_sumstruct.txt
similarity index 100%
rename from doc/tutorial/basics/2_types/55_sumstruct.txt
rename to doc/tutorial/basics/2_types/65_sumstruct.txt
