Tutorial updates, + new loops tutorial (#2622)

- Various minor tutorial improvements
- Move conditional tutorial after `world101` (world101 does not require conditionals)
- Add new loops tutorial after conditionals and before `farming`, which prompts you to implement a while loop using recursion.

Author: byorgey

data/scenarios/Tutorials/00-ORDER.txt

@@ -15,6 +15,7 @@ def.yaml
 lambda.yaml
 require.yaml
 stock.yaml
-conditionals.yaml
 world101.yaml
+conditionals.yaml
+loops.yaml
 farming.yaml

data/scenarios/Tutorials/build.yaml

@@ -16,6 +16,10 @@ objectives:
       - |
         **TIP:** Newly built robots start out facing the same
         direction as their parent, which in the tutorials will always be north.
+      - |
+        **TIP:** If you make a mistake, not to worry.  You have enough materials
+        for several tries; or, you can always hit **Ctrl+Q** and
+        select "Start over".
     condition: |
       try {
         teleport self (0,-1);

data/scenarios/Tutorials/conditionals.yaml

@@ -5,13 +5,15 @@ description: |
 objectives:
   - goal:
       - |
-        The 4x4 gray square contains 4 `very small rock`{=entity}s --- so
-        small they cannot be seen!  Your goal is to collect all of
-        them and bring them back to your base; you win when you have
-        all 4.  There is one rock in each row and column, but
-        otherwise you can't be sure where they are.  Your best bet is
-        to sweep over the entire 4x4 square and pick up a `very small rock`{=entity}
-        any time you detect one.
+        Before making more progress in the world, you'll need to learn
+        how to use a few more language features. The 4x4 gray square
+        contains 4 `very small rock`{=entity}s --- so small they
+        cannot be seen!  Your goal is to collect all of them and bring
+        them back to your base; you win when you have all 4.  There is
+        one rock in each row and column, but otherwise you can't be
+        sure where they are.  Your best bet is to sweep over the
+        entire 4x4 square and pick up a `very small rock`{=entity} any
+        time you detect one.
       - |
         The `ishere` command, with type `Text -> Cmd Bool`{=type}, can be used
         for detecting the presence of a specific item such as a `very small rock`{=entity}.

data/scenarios/Tutorials/farming.yaml

@@ -11,21 +11,16 @@ objectives:
         are somewhat rare in the wild.  Therefore, it makes sense to farm
         them in order to create a reliable supply.
       - |
-        In this scenario, you are a bit farther along: in particular,
+        In this example scenario, you are a bit farther along: in particular,
         you now have a few `harvester`{=entity}s, a few `lambda`{=entity}s, a few `logger`{=entity}s,
         some `branch predictor`{=entity}s which
         allow robots to evaluate conditional expressions, and some
-        `strange loop`{=entity}s which enable recursive functions.  For example,
-        one simple, useful recursive function is
+        `strange loop`{=entity}s which enable recursive functions.
       - |
-        ```
-        def forever = \c. c ; forever c end
-        ```
-      - |
-        Your goal is to acquire 256 `lambda`{=entity}s.  Of course, in order to
-        accomplish this in a reasonable amount of time, it makes sense to plant
+        Your goal is to acquire 256 `lambda`{=entity}s.  Of course,
+        now that you know how to write conditionals and loops, it makes sense to plant
         a field of `lambda`{=entity}s and then program one or more robots to
-        harvest them in an automated way.
+        harvest them in an automated way!
       - |
         **TIP:** the `ishere` command can be used to test for the presence of a
         (fully-grown) `lambda`{=entity}, and the `has` command can be used to test whether
@@ -41,7 +36,7 @@ objectives:
       - Congratulations!  You have completed the most difficult simulated exercise and are ready to begin exploring the new planet in earnest.  Of course there is much more remaining to explore in the world, and many additional programming language features to unlock.
       - |
         To finally complete this tutorial, there is only one thing left for you to do:
-        use one of your lambdas to make some delicious `curry`{=entity}.
+        use your `lambda`{=entity}s to make some delicious `curry`{=entity}.
       - Afterwards, you will return to the menu where you can select "Classic game" for the complete game experience.  Or, play a "Creative game" if you just want to play around with programming robots, without any constraints or need to collect resources.  You could also choose to redo some tutorial scenarios, or explore the other challenge scenarios listed in the menu.
       - Now go forth and build your swarm!
     condition: |

data/scenarios/Tutorials/loops.yaml

@@ -0,0 +1,90 @@
+version: 1
+name: Loops
+description: |
+  Learn how to implement loops.
+objectives:
+  - goal:
+      - |
+        The previous tutorial taught you how to use conditional
+        expressions; this one will guide you through using loops.
+      - |
+        To the east of your base lies a path of `rock`{=entity}s.  The
+        path extends in a straight line for an unknown distance, and at
+        the end of the path lies a lump of `gold`{=entity}.  You must
+        program a robot to go and fetch it!
+      - |
+        Some kind of `while`{=snippet} loop would obviously come in
+        handy here. However, the Swarm language does not have loops,
+        only recursion, which is enabled by the `strange loop`{=entity}
+        device.  You can use recursion to implement your own control
+        structures.  For example, a simple loop that repeats forever
+        can be written like this:
+        ```
+        def forever : Cmd Unit -> Cmd Unit = \body.
+          body; forever body
+        end
+        ```
+      - |
+        Now replace the `pure ()` below with your own code to
+        implement a while loop function:
+        ```
+        def while : Cmd Bool -> Cmd Unit -> Cmd Unit = \cond. \body.
+          pure ()
+        end
+        ```
+      - |
+        This function should take a condition (a `Cmd Bool`{=type}, for
+        example, `ishere "rock"`) and a command, and execute the
+        command repeatedly as long as the condition returns `True`.
+    condition: |
+      try {as base {has "gold"}} {pure false}
+solution: |
+  def while : Cmd Bool -> Cmd a -> Cmd Unit = \test. \body.
+    b <- test;
+    if b {body; while test body} {}
+  end
+
+  def follow = while (ishere "rock") move end
+
+  build {
+    turn east; move;
+    follow;
+    grab; turn back; move;
+    follow;
+    give base "gold"
+  }
+robots:
+  - name: base
+    heavy: true
+    loc: [0, 0]
+    dir: north
+    display:
+      char: Ω
+      attr: robot
+    devices:
+      - logger
+      - 3D printer
+      - dictionary
+      - toolkit
+    inventory:
+      - [8, compass]
+      - [8, solar panel]
+      - [8, logger]
+      - [8, treads]
+      - [8, grabber]
+      - [8, scanner]
+      - [8, lambda]
+      - [8, strange loop]
+      - [8, branch predictor]
+      - [8, toolkit]
+entities:
+known: [rock, gold]
+world:
+  scrollable: false
+  dsl: |
+    let path_len = 173 in
+    overlay
+    [ {grass}
+    , mask (y == 0 && x > 0 && x < path_len) {rock}
+    , mask (y == 0 && x == path_len) {gold}
+    ]

data/scenarios/Tutorials/require.yaml

@@ -15,7 +15,7 @@ objectives:
         ```
         build {require "boat"; move}
         ```
-        Then a `boat`{=entity} will be equipped on the new robot in addition to `treads`{=entity}.
+        then a `boat`{=entity} will be equipped on the new robot in addition to `treads`{=entity}.
       - |
         Unlike other devices used so far in the tutorial, `boat`{=entity} does not provide any commands,
         but robots that have it equipped will not drown in the `water`{=entity}.

data/scenarios/Tutorials/stock.yaml

@@ -7,14 +7,14 @@ objectives:
       - |
         In the previous tutorial challenge, you learned how to use `require`{=snippet}
         to require specific devices to be equipped.
-        Sometimes, instead of requiring entities to be equiped as devices, you need them to be stocked in your inventory.
+        Sometimes, instead of requiring entities to be equipped as devices, you need them to be stocked in your inventory.
       - |
         In this case, you can write `stock <int> <name>`{=snippet} to ensure that a certain number
         of copies of a certain entity are placed in your inventory. For example:
         ```
         build {stock 2 "flower"; move; place "flower"; move; place "flower"}
         ```
-        This would build a robot with two `flower`{=entity}s in its inventory which the robot can then place.
+        This would build a robot with two `flower`{=entity}s in its inventory which the robot can then `place`.
       - Your goal in this challenge is to cover the entire 4x4 gray area with `rock`{=entity}s!
       - |
         **TIP:** You can define commands to simplify your task, for example:

data/scenarios/Tutorials/type-errors.yaml

@@ -12,6 +12,8 @@ objectives:
       - "Some other type errors for you to try:"
       - |
         `turn move`{=snippet}
+      - |
+        `3 + "hi"`{=snippet}
       - |
         `place tree`{=snippet} (without double quotes around `tree`{=snippet})
       - |
@@ -30,6 +32,17 @@ entities:
       char: 'W'
     description:
       - Do `place "win"` once you are done with this challenge.
+      - "Some expressions for you to try:"
+      - |
+        `turn 1`{=snippet}
+      - |
+        `turn move`{=snippet}
+      - |
+        `3 + "hi"`{=snippet}
+      - |
+        `place tree`{=snippet}
+      - |
+        `move move`{=snippet}
     properties: [known, pickable]
 solution: |
   place "win"

data/scenarios/Tutorials/types.yaml

@@ -34,6 +34,20 @@ entities:
       char: 'W'
     description:
       - Do `place "win"` once you are done with this challenge.
+      - |
+        Some expressions for you to try:
+      - |
+        `north`
+      - |
+        `move; move`
+      - |
+        `grab`
+      - |
+        `make`
+      - |
+        `3`
+      - |
+        `"tree"`
     properties: [known, pickable]
 solution: |
   place "win"

src/swarm-lang/Swarm/Language/Typecheck.hs

@@ -518,7 +518,7 @@ instance PrettyPrec TypeErr where
     EscapedSkolem x ->
       "Skolem variable" <+> ppr x <+> "would escape its scope"
     UnboundVar x ->
-      "Unbound variable" <+> ppr x
+      "Undefined variable" <+> ppr x
     UnboundType x ->
       "Undefined type" <+> ppr x
     DefNotTopLevel t ->
@@ -1287,11 +1287,11 @@ check s@(CSyntax l t cs) expected = addLocToTypeErr l $ case t of
     -- > let y : Int = 3 in y + 2
     -- 5
     -- > y
-    -- 1:1: Unbound variable y
+    -- 1:1: Undefined variable y
     -- > let y = 3 in def x = 5 end; pure (x + y)
     -- 8
     -- > y
-    -- 1:1: Unbound variable y
+    -- 1:1: Undefined variable y
     -- > x
     -- 5
     let mreqs = case ls of