@@ -0,0 +1,90 @@
1+Blocks
2+======
3+
4+Blocks are collections of statements wrapped in braces `{ ... }`. Blocks must return a value of the same type on every branch of execution.
5+
6+The following types of statement are supported:
7+
8+- Variable introduction
9+- Variable assignment
10+- For loops
11+- While loops
12+- If-Then-Else statements
13+
14+Here is an example of a power function defined using a block::
15+
16+ pow n p = {
17+ var m = n;
18+ for (i <- 0 until p) {
19+ m = m * n;
20+ }
21+ return m;
22+ }
23+
24+Blocks enable local mutation of their variables, but mutation is not allowed in general. The type system prevents mutable variables from escaping their scope.
25+
26+That is, while the example above is valid, the following does not compile::
27+
28+ incr n = {
29+ n = n + 1;
30+ return n;
31+ }
32+
33+The variable `n` is not mutable, and so the assignment in the first line of the `do` block is not allowed.
34+
35+This function can be rewritten as follows::
36+
37+ incr n = {
38+ var m = n;
39+ m = m + 1;
40+ return m;
41+ }
42+
43+For Loops
44+---------
45+
46+For loops iterate over a range of numbers::
47+
48+ total = {
49+ var n = 0;
50+ for (i <- 0 until 10) {
51+ n = n + i;
52+ }
53+ return n;
54+ }
55+
56+The bounds `0` and `10` are inclusive and exclusive respectively.
57+
58+While Loops
59+------------
60+
61+While loops repeat a set of statements while a boolean expression evaluates to `true`::
62+
63+ log2 n = {
64+ var count = 0;
65+ var m = n;
66+ while (m > 1) {
67+ m = m / 2;
68+ count = count + 1;
69+ }
70+ return count;
71+ }
72+
73+If-Then-Else Statements
74+-----------------------
75+
76+Else branches are optional, and may contain further `if` statements, just as in Javascript:
77+
78+ collatz n = {
79+ var count = 0;
80+ var m = n;
81+ while (m > 1) {
82+ if (m % 2 == 0) {
83+ m = m / 2;
84+ } else {
85+ m = m * 3 + 1;
86+ }
87+ count = count + 1;
88+ }
89+ return count;
90+ }