From 686f7b435d9974bfffa273168792ee0bb2ca1db8 Mon Sep 17 00:00:00 2001
From: Jeff <dev@jeffa.io>
Date: Tue, 17 Oct 2023 16:21:59 -0400
Subject: [PATCH] Write README and examples

---
 README.md            | 59 ++++++++++++++++++++++++++++++++++++++++++++
 examples/for_loop.ds |  8 +++---
 2 files changed, 64 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 01aeaef..da330e0 100644
--- a/README.md
+++ b/README.md
@@ -118,6 +118,65 @@ reminder = {
 (output reminder.message)
 ```
 
+### Loops
+
+A **while** loop continues until a predicate is false.
+
+```dust
+i = 0
+while i < 10 {
+    (output i)
+    i += 1
+}
+```
+
+A **for** loop operates on a list without mutating it or the items inside. It does not return a value.
+
+```dust
+list = [ 1, 2, 3 ]
+
+for number in list {
+    number += 1 # This modifies x *only* in this block scope
+}
+
+(output list)
+# Output: [ 1 2 3 ]
+# The original list is left unchanged.
+```
+
+To mutate the values in a list, use a **transform** loop, which returns a new modified list.
+
+```dust
+list = transform number in [1 2 3] {
+    number - 1
+}
+
+(output list)
+# Output: [ 0 1 2 ]
+```
+
+To filter out some of the values in a list, use a **filter** loop.
+
+```dust
+list = filter number in [1 2 3] {
+    number >= 2
+}
+
+(output list)
+# Output: [ 2 3 ]
+```
+
+A **find** loop will return a single value, the first item that satisfies the predicate.
+
+```dust
+found = find number in [1 2 1] {
+    number != 1
+}
+
+(output found)
+# Output: 2
+```
+
 ### Tables
 
 Tables are strict collections, each row must have a value for each column. If a value is "missing" it should be set to an appropriate value for that type. For example, a string can be empty and a number can be set to zero. Dust table declarations consist of a list of column names, which are identifiers enclosed in pointed braces. The column names are followed by a pair of curly braces filled with list values. Each list will become a row in the new table.
diff --git a/examples/for_loop.ds b/examples/for_loop.ds
index 453a296..3019d6b 100644
--- a/examples/for_loop.ds
+++ b/examples/for_loop.ds
@@ -1,6 +1,8 @@
-i = 0
-for i in [1 2 3] {
+list = [1 2 3]
+
+for i in list {
 	i += 1
 	(output i)
 }
-(output i)
+
+(output list)