doc/tutorial/basics: examples about cycles
Change-Id: If0485a10755bfb5f316dab4bd24fc650f9f448d4
diff --git a/doc/tutorial/basics/coalesce.md b/doc/tutorial/basics/coalesce.md
index dde8c77..9c4f376 100644
--- a/doc/tutorial/basics/coalesce.md
+++ b/doc/tutorial/basics/coalesce.md
@@ -1,4 +1,4 @@
-[TOC](Readme.md) [Prev](conditional.md) _Next_
+[TOC](Readme.md) [Prev](conditional.md) [Next](cycles.md)
_Expressions_
@@ -33,7 +33,7 @@
b: *list[5] | "None"
n: [null]
-v: *n[0] & string | "default"
+v: *n[0]&string | "default"
```
<!-- result -->
diff --git a/doc/tutorial/basics/cycle.md b/doc/tutorial/basics/cycle.md
new file mode 100644
index 0000000..80755e6
--- /dev/null
+++ b/doc/tutorial/basics/cycle.md
@@ -0,0 +1,37 @@
+[TOC](Readme.md) [Prev](coalesce.md) [Next](cycleref.md)
+
+_Cycles_
+
+# Reference cycles
+
+CUE can handle many types of cycles just fine.
+Because all values are final, a field with a concrete value of, say `200`,
+can only be valid if it is that value.
+So if it is unified with another expression, we can delay the evaluation of
+this until later.
+
+By postponing that evaluation, we can often break cycles.
+This is very useful for template writers that may not know what fields
+a user will want ot fill out.
+
+
+<!-- CUE editor -->
+```
+// CUE knows how to resolve the following:
+x: 200
+x: y + 100
+y: x - 100
+
+// If a cycle is not broken, CUE will just report it.
+a: b + 100
+b: a - 100
+```
+
+<!-- result -->
+```
+x: 200
+y: 100
+
+a: _|_ // cycle detected
+b: _|_ // cycle detected
+```
diff --git a/doc/tutorial/basics/cycleref.md b/doc/tutorial/basics/cycleref.md
new file mode 100644
index 0000000..f893afd
--- /dev/null
+++ b/doc/tutorial/basics/cycleref.md
@@ -0,0 +1,25 @@
+[TOC](Readme.md) [Prev](cycle.md) _Next_
+
+_Cycles_
+
+# Cycles in fields
+
+Also, we know that unifying a field with itself will result in the same value.
+Thus if we have a cycle between some fields, all we need to do is ignore
+the cycle and unify their values once to achieve the same result as
+merging them ad infinitum.
+
+<!-- CUE editor -->
+```
+labels: selectors
+labels: {app: "foo"}
+
+selectors: labels
+selectors: {name: "bar"}
+```
+
+<!-- result -->
+```
+labels: {app: "foo", name: "bar"}
+selectors: {app: "foo", name: "bar"}
+```
