doc/tutorial/basics: update some sections
Change-Id: Iea5da5ad88c7b0d0637f8b93650b89ee881286a5
Reviewed-on: https://cue-review.googlesource.com/c/cue/+/3621
Reviewed-by: Marcel van Lohuizen <mpvl@golang.org>
diff --git a/doc/tutorial/basics/0_intro/10_json.txt b/doc/tutorial/basics/0_intro/10_json.txt
index c8b7ac4..b7815b0 100644
--- a/doc/tutorial/basics/0_intro/10_json.txt
+++ b/doc/tutorial/basics/0_intro/10_json.txt
@@ -2,17 +2,31 @@
cmp stdout expect-stdout-cue
-- frontmatter.toml --
-title = "Quotes are Optional for Field Names"
+title = "JSON Superset"
description = ""
-- text.md --
+CUE is a superset of JSON.
+It adds the following conveniences:
+
+- C-style comments,
+- quotes may be omitted from field names without special characters,
+- commas at the end of fields are optional,
+- comma after last element in list is allowed,
+- outer curly braces are optional.
+
+<!--
+{{< alert color="info">}}
+CUE borrows a trick from Go to make commas optional:
+the formal grammar still requires commas,
+but the scanner inserts commas according to a small set
+of simple rules.
+{{< /alert >}}
+-->
+
JSON objects are called structs in CUE.
An object member is called a field.
-
-Double quotes may be omitted from field names if their name contains no
-special characters and does not start with a number:
-
-- json.cue --
one: 1
two: 2
diff --git a/doc/tutorial/basics/0_intro/20_cue.txt b/doc/tutorial/basics/0_intro/20_cue.txt
index 19579cc..de16e7d 100644
--- a/doc/tutorial/basics/0_intro/20_cue.txt
+++ b/doc/tutorial/basics/0_intro/20_cue.txt
@@ -1,6 +1,6 @@
-- frontmatter.toml --
-title = "Commas are Optional after Fields"
+title = "Types are values"
description = ""
-- text.md --
diff --git a/doc/tutorial/basics/2_types/20_duplicates.txt b/doc/tutorial/basics/0_intro/30_duplicates.txt
similarity index 82%
rename from doc/tutorial/basics/2_types/20_duplicates.txt
rename to doc/tutorial/basics/0_intro/30_duplicates.txt
index dce9b26..e1187ae 100644
--- a/doc/tutorial/basics/2_types/20_duplicates.txt
+++ b/doc/tutorial/basics/0_intro/30_duplicates.txt
@@ -13,18 +13,14 @@
For structs, fields are merged and duplicated fields are handled recursively.
For lists, all elements must match accordingly
-([we discuss open-ended lists later](lists.md).)
+<!-- ([we discuss open-ended lists later](lists.md).) -->
-- dup.cue --
a: 4
a: 4
-s: {
- x: 1
-}
-s: {
- y: 2
-}
+s: { b: 2 }
+s: { c: 2 }
l: [ 1, 2 ]
l: [ 1, 2 ]
@@ -32,7 +28,7 @@
-- expect-stdout-cue --
a: 4
s: {
- x: 1
- y: 2
+ b: 2
+ c: 2
}
l: [1, 2]
diff --git a/doc/tutorial/basics/0_intro/35_duplicates.txt b/doc/tutorial/basics/0_intro/40_constraints.txt
similarity index 61%
rename from doc/tutorial/basics/0_intro/35_duplicates.txt
rename to doc/tutorial/basics/0_intro/40_constraints.txt
index 4085030..363edaf 100644
--- a/doc/tutorial/basics/0_intro/35_duplicates.txt
+++ b/doc/tutorial/basics/0_intro/40_constraints.txt
@@ -1,4 +1,4 @@
-cue eval dup.cue
+cue eval check.cue
cmp stdout expect-stdout-cue
-- frontmatter.toml --
@@ -15,27 +15,30 @@
They can be applied to CUE data, or directly to YAML or JSON.
But constraints can also reduce boilerplate.
-If a constraints defines a concrete value, there is no need
+If a constraint defines a concrete value, there is no need
to specify it in values to which this constraint applies.
--- dup.cue --
-a: 4
-a: 4
-
-s: {
- x: 1
-}
-s: {
- y: 2
+-- check.cue --
+schema: {
+ name: string
+ age: int
+ human: true // always true
}
-l: [ 1, 2 ]
-l: [ 1, 2 ]
+viola: schema
+viola: {
+ name: "Viola"
+ age: 38
+}
-- expect-stdout-cue --
-a: 4
-s: {
- x: 1
- y: 2
+schema: {
+ name: string
+ age: int
+ human: true
}
-l: [1, 2]
+viola: {
+ name: "Viola"
+ age: 38
+ human: true
+}
diff --git a/doc/tutorial/basics/0_intro/43_schema.txt b/doc/tutorial/basics/0_intro/43_schema.txt
new file mode 100644
index 0000000..0293122
--- /dev/null
+++ b/doc/tutorial/basics/0_intro/43_schema.txt
@@ -0,0 +1,40 @@
+cue export schema.cue
+cmp stdout expect-stdout-cue
+
+-- frontmatter.toml --
+title = "Definitions"
+description = ""
+
+-- text.md --
+In CUE, schema are typically written as Definitions,
+using a `::` instead of `:`.
+This tells CUE that they are to be used for validation and should
+not be output as data; it is okay for them to remain unspecified.
+
+A definition also tells CUE the full set of allowed fields.
+In other words, definitions define "closed" structs.
+Including a `...` in struct keeps it open.
+
+-- schema.cue --
+Conn :: {
+ address: string
+ port: int
+ protocol: string
+ // ... // uncomment this to allow any field
+}
+
+lossy: Conn & {
+ address: "1.2.3.4"
+ port: 8888
+ protocol: "udp"
+ // foo: 2 // uncomment this to get an error
+}
+
+-- expect-stdout-cue --
+{
+ "lossy": {
+ "address": "1.2.3.4",
+ "port": 8888,
+ "protocol": "udp"
+ }
+}
diff --git a/doc/tutorial/basics/0_intro/32_validation.txt b/doc/tutorial/basics/0_intro/47_validation.txt
similarity index 100%
rename from doc/tutorial/basics/0_intro/32_validation.txt
rename to doc/tutorial/basics/0_intro/47_validation.txt
diff --git a/doc/tutorial/basics/0_intro/30_order.txt b/doc/tutorial/basics/0_intro/50_order.txt
similarity index 88%
rename from doc/tutorial/basics/0_intro/30_order.txt
rename to doc/tutorial/basics/0_intro/50_order.txt
index b38cd3e..e7b2e7c 100644
--- a/doc/tutorial/basics/0_intro/30_order.txt
+++ b/doc/tutorial/basics/0_intro/50_order.txt
@@ -13,8 +13,6 @@
that makes it easy for humans _and_ machines to reason over values and
makes advanced tooling and automation possible.
-If you can think of an example where order matters, it is not valid CUE.
-
-- order.cue --
a: {x: 1, y: int}
a: {x: int, y: 2}
diff --git a/doc/tutorial/basics/0_intro/40_fold.txt b/doc/tutorial/basics/0_intro/55_fold.txt
similarity index 100%
rename from doc/tutorial/basics/0_intro/40_fold.txt
rename to doc/tutorial/basics/0_intro/55_fold.txt
diff --git a/doc/tutorial/basics/0_intro/50_boilerplate.txt b/doc/tutorial/basics/0_intro/80_boilerplate.txt
similarity index 93%
rename from doc/tutorial/basics/0_intro/50_boilerplate.txt
rename to doc/tutorial/basics/0_intro/80_boilerplate.txt
index 2924ee4..75ed27b 100644
--- a/doc/tutorial/basics/0_intro/50_boilerplate.txt
+++ b/doc/tutorial/basics/0_intro/80_boilerplate.txt
@@ -1,7 +1,8 @@
-- frontmatter.toml --
-title = "Templating"
+title = "Boilerplate"
description = ""
+draft = true
-- text.md --
Constraints specify what values are allowed.
diff --git a/doc/tutorial/basics/2_types/50_disjunctions.txt b/doc/tutorial/basics/2_types/50_disjunctions.txt
index 81a7eda..99bb955 100644
--- a/doc/tutorial/basics/2_types/50_disjunctions.txt
+++ b/doc/tutorial/basics/2_types/50_disjunctions.txt
@@ -14,20 +14,20 @@
to define anything else than these two values.
-- disjunctions.cue --
-conn: {
+Conn :: {
address: string
port: int
protocol: "tcp" | "udp"
}
-lossy: conn & {
+lossy: Conn & {
address: "1.2.3.4"
port: 8888
protocol: "udp"
}
-- expect-stdout-cue --
-conn: {
+Conn :: {
address: string
port: int
protocol: "tcp" | "udp"
diff --git a/doc/tutorial/basics/2_types/75_rangedef.txt b/doc/tutorial/basics/2_types/75_bounddef.txt
similarity index 92%
rename from doc/tutorial/basics/2_types/75_rangedef.txt
rename to doc/tutorial/basics/2_types/75_bounddef.txt
index 1ef0b89..3125ff7 100644
--- a/doc/tutorial/basics/2_types/75_rangedef.txt
+++ b/doc/tutorial/basics/2_types/75_bounddef.txt
@@ -1,15 +1,15 @@
-cue eval -i range.cue
+cue eval -i bound.cue
cmp stdout expect-stdout-cue
-- frontmatter.toml --
-title = "Predefined Ranges"
+title = "Predefined Bounds"
description = ""
-- text.md --
CUE numbers have arbitrary precision.
Also there is no unsigned integer type.
-CUE defines the following predefined identifiers to restrict the ranges of
+CUE defines the following predefined identifiers to restrict the bounds of
integers to common values.
```
@@ -28,7 +28,7 @@
uint128 >=0 & <=340_282_366_920_938_463_463_374_607_431_768_211_455
```
--- range.cue --
+-- bound.cue --
positive: uint
byte: uint8
word: int32
diff --git a/doc/tutorial/basics/2_types/20_selectors.txt b/doc/tutorial/basics/4_references/20_selectors.txt
similarity index 100%
rename from doc/tutorial/basics/2_types/20_selectors.txt
rename to doc/tutorial/basics/4_references/20_selectors.txt
