docs/tour: import cuelang.org/docs/tutorials/tour/types/

This change imports the contents of
https://cuelang.org/docs/tutorials/tour/types/ into /docs/tour/types/.

Minimal formatting changes have been made, to align content with alpha's
preprocessor and hugo capabilities, with the following exception:

- the faux-table in content/docs/tour/types/bounddef/en.md has had ":"
  added at the end of each line's "field names", to allow the file to be
  treated as CUE instead of the source's raw text. This allows the
  content to be formatted automatically.

The overall delta from the source material is shown by this shell
command:

   for PAGE in types bottom numbers stringlit stringraw bytes closed defs optional disjunctions defaults sumstruct bounds bounddef lists templates ; do git diff 4b2c488:content/en/docs/tutorials/tour/types/$PAGE.md content/docs/tour/types/$PAGE/en.md; done

A sub-optimal method is used for replicating the side-by-side layout of
the existing tour when the command that's executed needs to be displayed
(as it's not a simple `cue eval` or `cue export`). This is documented,
with a nicer/preprocessor solution requested, in cue-lang/cue#2667

For cue-lang/docs-and-content#25

Preview-Path: /docs/tour/types/
Change-Id: I47c8bb624b364691396d2162a0e83d69140d72d2
Signed-off-by: Jonathan Matthews <[email protected]>
Dispatch-Trailer: {"type":"trybot","CL":1171469,"patchset":2,"ref":"refs/changes/69/1171469/2","targetBranch":"alpha"}

content/docs/tour/types/_en.md

@@ -0,0 +1,9 @@
+---
+title: "Types and Values"
+---
+
+This tour demonstrates the hierarchy of primitive and complex types that CUE
+makes available, along with common methods for constraining and combining these
+types.
+
+## Contents

content/docs/tour/types/bottom/en.md

@@ -0,0 +1,34 @@
+---
+title: "Bottom / Error"
+weight: 2
+---
+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 conflicting 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 value,
+whereas `_|_` is not.
+
+{{{with code "en" "bottom"}}}
+exec cue eval -i bottom.cue
+cmp stdout '$ cue eval -i bottom.cue'
+-- bottom.cue --
+a: 4
+a: 5
+
+l: [ 1, 2]
+l: [ 1, 3]
+
+list: [0, 1, 2]
+val: list[3]
+-- $ cue eval -i bottom.cue --
+a: _|_ // a: conflicting values 5 and 4
+l: [1, _|_, // l.1: conflicting values 3 and 2
+]
+list: [0, 1, 2]
+val: _|_ // val: index out of range [3] with length 3
+{{{end}}}

content/docs/tour/types/bottom/gen_cache.cue

@@ -0,0 +1,20 @@
+package site
+{
+	content: {
+		docs: {
+			tour: {
+				types: {
+					bottom: {
+						page: {
+							cache: {
+								code: {
+									bottom: "nVWmtoCwxo2MltMzeeFZCXDasDDlZM7LFe6yfnQG1SU="
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/tour/types/bottom/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: tour: types: bottom: {}

content/docs/tour/types/bounddef/en.md

@@ -0,0 +1,43 @@
+---
+title: "Predefined Bounds"
+weight: 14
+---
+CUE numbers have arbitrary precision.
+Also there is no unsigned integer type.
+
+CUE defines the following predefined identifiers to restrict the bounds of
+integers to common values.
+
+{{{with code "en" "defined"}}}
+-- in.cue --
+uint:   >=0
+uint8:  >=0 & <=255
+int8:   >=-128 & <=127
+uint16: >=0 & <=65536
+int16:  >=-32_768 & <=32_767
+rune:   >=0 & <=0x10FFFF
+uint32: >=0 & <=4_294_967_296
+int32:  >=-2_147_483_648 & <=2_147_483_647
+uint64: >=0 & <=18_446_744_073_709_551_615
+int64:  >=-9_223_372_036_854_775_808 & <=9_223_372_036_854_775_807
+int128: >=-170_141_183_460_469_231_731_687_303_715_884_105_728 &
+		<=170_141_183_460_469_231_731_687_303_715_884_105_727
+uint128: >=0 & <=340_282_366_920_938_463_463_374_607_431_768_211_455
+{{{end}}}
+
+{{{with code "en" "failure"}}}
+exec cue eval -ic bound.cue
+cmp stdout '$ cue eval -ic bound.cue'
+-- bound.cue --
+#positive: uint
+#byte:     uint8
+#word:     int32
+
+a: #positive & -1
+b: #byte & 128
+c: #word & 2_000_000_000
+-- $ cue eval -ic bound.cue --
+a: _|_ // a: invalid value -1 (out of bound >=0)
+b: 128
+c: 2000000000
+{{{end}}}

content/docs/tour/types/bounddef/gen_cache.cue

@@ -0,0 +1,21 @@
+package site
+{
+	content: {
+		docs: {
+			tour: {
+				types: {
+					bounddef: {
+						page: {
+							cache: {
+								code: {
+									defined: "MohhkFjPJDw6JacZKpy05dq6V7IvtCjcSRoAeVyZzOQ="
+									failure: "HvILLQ/uSPtoJEAq/x+mzGPoWMXdigD18sCAU9YwMIg="
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/tour/types/bounddef/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: tour: types: bounddef: {}

content/docs/tour/types/bounds/en.md

@@ -0,0 +1,39 @@
+---
+title: "Bounds"
+weight: 13
+---
+Bounds define a lower bound, upper bound, or inequality for a certain value.
+They work on numbers, strings, bytes and null.
+
+The bound is defined for all values for which the corresponding comparison
+operation is defined.
+For instance `>5.0` allows all floating point values greater than `5.0`,
+whereas `<0` allows all negative numbers (int or float).
+
+
+{{{with code "en" "failure"}}}
+exec cue eval -ic bounds.cue
+cmp stdout '$ cue eval -ic bounds.cue'
+-- bounds.cue --
+#rn: >=3 & <8 // type int | float
+
+#ri: >=3 & <8 & int // type int
+
+#rf: >=3 & <=8.0 // type float
+#rs: >="a" & <"mo"
+
+a: #rn & 3.5
+b: #ri & 3.5
+c: #rf & 3
+d: #rs & "ma"
+e: #rs & "mu"
+
+r1: #rn & >=5 & <10
+-- $ cue eval -ic bounds.cue --
+a:  3.5
+b:  _|_ // b: conflicting values int and 3.5 (mismatched types int and float)
+c:  3
+d:  "ma"
+e:  _|_ // e: invalid value "mu" (out of bound <"mo")
+r1: >=5 & <8
+{{{end}}}

content/docs/tour/types/bounds/gen_cache.cue

@@ -0,0 +1,20 @@
+package site
+{
+	content: {
+		docs: {
+			tour: {
+				types: {
+					bounds: {
+						page: {
+							cache: {
+								code: {
+									failure: "i2XOqSgd0R4pfPqroxbF1GW311kDl7jEuSD1Ax4gNTY="
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/tour/types/bounds/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: tour: types: bounds: {}

content/docs/tour/types/bytes/en.md

@@ -0,0 +1,24 @@
+---
+title: "Bytes"
+weight: 6
+---
+CUE distinguishes between a `string` and a `bytes` type.
+Bytes are converted to base64 when emitting JSON.
+Byte literals are defined with single quotes.
+The following additional escape sequences are allowed in byte literals:
+
+{{{with code "en" "escapes"}}}
+-- in.txt --
+    \xnn   // arbitrary byte value defined as a 2-digit hexadecimal number
+    \nnn   // arbitrary byte value defined as a 3-digit octal number
+{{{end}}}
+<!-- jba: this contradicts the spec, which has \nnn (no leading zero) -->
+
+{{{with code "en" "bytes"}}}
+-- in.cue --
+a: '\x03abc'
+-- out.json --
+{
+    "a": "A2FiYw=="
+}
+{{{end}}}

content/docs/tour/types/bytes/gen_cache.cue

@@ -0,0 +1,21 @@
+package site
+{
+	content: {
+		docs: {
+			tour: {
+				types: {
+					bytes: {
+						page: {
+							cache: {
+								code: {
+									escapes: "8vtA7ViI2sFYm8xmKowJXMB5ndr3JrCrE1tYBSagbyY="
+									bytes:   "/VCm4S2hcboOQNMR4h3VBDKFP2jW6AREcy5wdBCnWkc="
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/tour/types/bytes/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: tour: types: bytes: {}

content/docs/tour/types/closed/en.md

@@ -0,0 +1,35 @@
+---
+title: "Closed structs"
+weight: 7
+---
+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 `close` builtin,
+but are more commonly defined using a _definition_, defined next.
+
+{{{with code "en" "structs"}}}
+exec cue eval -i structs.cue
+cmp stdout '$ cue eval -i structs.cue'
+-- structs.cue --
+a: close({
+	field: int
+})
+
+b: a & {
+	feild: 3
+}
+-- $ cue eval -i structs.cue --
+a: {
+    field: int
+}
+b: {
+    field: int
+    feild: _|_ // b.feild: field not allowed
+}
+{{{end}}}

content/docs/tour/types/closed/gen_cache.cue

@@ -0,0 +1,20 @@
+package site
+{
+	content: {
+		docs: {
+			tour: {
+				types: {
+					closed: {
+						page: {
+							cache: {
+								code: {
+									structs: "5IUiLlZhc0s9SnEL9/LM8hFFJhAIWaR2G2SdH7i+yDI="
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/tour/types/closed/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: tour: types: closed: {}

content/docs/tour/types/defaults/en.md

@@ -0,0 +1,27 @@
+---
+title: "Default Values"
+weight: 11
+---
+Elements of a disjunction may be marked as preferred.
+If there is only one mark, or the users constraints a field enough such that
+only one mark remains, that value is the default value.
+
+In the example, `replicas` defaults to `1`.
+In the case of `protocol`, however, there are multiple definitions with
+different, mutually incompatible defaults.
+In that case, both `"tcp"` and `"udp"` are preferred and one must explicitly
+specify either `"tcp"` or `"udp"` as if no marks were given.
+
+{{{with code "en" "defaults"}}}
+#nofmt(in.cue) https://github.com/cue-lang/cue/issues/722
+-- in.cue --
+// any positive number, 1 is the default
+replicas: uint | *1
+
+// the default value is ambiguous
+protocol: *"tcp" | "udp"
+protocol: *"udp" | "tcp"
+-- out.cue --
+replicas: 1
+protocol: "tcp" | "udp"
+{{{end}}}

content/docs/tour/types/defaults/gen_cache.cue

@@ -0,0 +1,20 @@
+package site
+{
+	content: {
+		docs: {
+			tour: {
+				types: {
+					defaults: {
+						page: {
+							cache: {
+								code: {
+									defaults: "GYWvuj2K32SEjbWwJoXXWPynXA6rQz9Y7aC/802wPYU="
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/tour/types/defaults/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: tour: types: defaults: {}