Add concept exercise for booleans (#331)

* Add concept exercise for booleans

* Fix format of markdown file hints.md

* Move return comments on new line in Annalyn instructions

* annalyn: update .meta/config.json

* annalyn: update .meta/design.md prerequisites

* booleans: add a .meta/config.json

* config.json: reorder fields to match docs

* config.json: add booleans concept and annalyn concept exercise

Author: mpizenberg

concepts/booleans/.meta/config.json

@@ -0,0 +1,9 @@
+{
+  "blurb": "Learn how to use booleans in an Elm program",
+  "authors": [
+    "mpizenberg"
+  ],
+  "contributors": [
+    "ceddlyburge"
+  ]
+}

concepts/booleans/about.md

@@ -0,0 +1,53 @@
+# About
+
+The `Bool` type is one of the building blocks of the language.
+It aims at describing whether something is true or false, with the respective `True` and `False` values.
+The name `Bool` is short for Boolean, which is a field of mathematics related to logical thinking, named after the work of George Boole.
+
+## Boolean operators
+
+There are two functions and two operators to manipulate values of type `Bool`.
+
+- `not : Bool -> Bool`
+  This function transforms `True` into `False` and `False` into `True`.
+- `(&&) : Bool -> Bool -> Bool`
+  This operator called "AND" takes two booleans and returns `True` if they are both `True`.
+  For example, `True && True` returns `True` but `True && False` returns `False`.
+- `(||) : Bool -> Bool -> Bool`
+  This operator called "OR" takes two booleans and returns `True` if at least one of them is `True`.
+  For example, `False || False` returns `False` but `True || False` returns `True`.
+- `xor : Bool -> Bool -> Bool`
+  This function (not operator) called "XOR" takes two booleans and returns `True` if and only if one is `True` and the other is `False`.
+
+The `&&` and `||` operators do not have the same priority.
+The priority of `&&` is higher than the one of `||`, just like with multiplication `*` and addition `+`.
+As a consequence, the expression `True || False && False` is equivalent to `True || (False && False)` which is different from `(True || False) && False`.
+While the former returns `True` the latter returns `False`.
+
+## Conditional branching
+
+Booleans are extremely useful to make branches in your code that only get executed if certain conditions are met.
+In Elm, this is done with an `if-then-else` expression, used as follows.
+
+```elm
+if someCondition then
+    doSomething
+else
+    doSomethingElse
+```
+
+The value `someCondition` can be any expression that returns a `Bool`.
+If that boolean value is `True`, the code will execute `doSomething`.
+Otherwise it is `False` and the code will execute `doSomethingElse`.
+The `else` branch is mandatory, contrary to some other programming languages.
+
+If you need to chain conditions, you can just chain the `if-then-else` expressions.
+
+```elm
+if someCondition then
+    doSomething
+else if someOtherCondition then
+    doAnotherThing
+else
+    doSomethingElse
+```

concepts/booleans/introduction.md

@@ -0,0 +1,16 @@
+# Introduction
+
+The `Bool` type is one of the building blocks of the language.
+It aims at describing whether something is true or false, with the respective `True` and `False` values.
+
+Booleans can be combined with the `&&` "AND" and the `||` "OR" operators, and negated with the `not` function.
+
+Booleans are also extremely useful to make branches in your code that only get executed if certain conditions are met.
+In Elm, this is done with an `if-then-else` expression, used as follows.
+
+```elm
+if someCondition then
+    doSomething
+else
+    doSomethingElse
+```

concepts/booleans/links.json

@@ -0,0 +1,10 @@
+[
+  {
+    "url": "https://package.elm-lang.org/packages/elm/core/latest/Basics#Bool",
+    "description": "Boolean operators"
+  },
+  {
+    "url": "https://elm-lang.org/docs/syntax#conditionals",
+    "description": "Syntax for conditional branches"
+  }
+]

config.json

@@ -2,18 +2,41 @@
   "language": "Elm",
   "slug": "elm",
   "active": true,
+  "blurb": "Elm is a friendly functional language for the Web",
+  "version": 3,
+  "online_editor": {
+    "indent_style": "space",
+    "indent_size": 4
+  },
   "status": {
     "concept_exercises": false,
     "test_runner": true,
     "representer": true,
     "analyzer": false
   },
-  "blurb": "Elm is a friendly functional language for the Web",
-  "version": 3,
-  "online_editor": {
-    "indent_style": "space",
-    "indent_size": 4
+  "files": {
+    "solution": [
+      "src/%{pascal_slug}.elm"
+    ],
+    "test": [
+      "tests/Tests.elm"
+    ],
+    "example": [
+      ".meta/src/%{pascal_slug}.example.elm"
+    ],
+    "exemplar": [
+      ".meta/Exemplar.elm"
+    ]
   },
+  "tags": [
+    "paradigm/functional",
+    "typing/static",
+    "typing/strong",
+    "execution_mode/compiled",
+    "platform/web",
+    "used_for/frontends",
+    "used_for/web_development"
+  ],
   "key_features": [
     {
       "title": "For the Web",
@@ -46,15 +69,6 @@
       "icon": "features-functional"
     }
   ],
-  "tags": [
-    "paradigm/functional",
-    "typing/static",
-    "typing/strong",
-    "execution_mode/compiled",
-    "platform/web",
-    "used_for/frontends",
-    "used_for/web_development"
-  ],
   "concepts": [
     {
       "uuid": "3e6e4a21-cc66-4c48-857b-90e1ca5298f9",
@@ -65,22 +79,13 @@
       "uuid": "e850acd6-63f3-427e-a883-222e0bd89a59",
       "slug": "basics-2",
       "name": "Basics 2"
+    },
+    {
+      "uuid": "2f7f1b64-5ee5-4600-a81d-87a2c79815a5",
+      "slug": "booleans",
+      "name": "Booleans"
     }
   ],
-  "files": {
-    "solution": [
-      "src/%{pascal_slug}.elm"
-    ],
-    "test": [
-      "tests/Tests.elm"
-    ],
-    "example": [
-      ".meta/src/%{pascal_slug}.example.elm"
-    ],
-    "exemplar": [
-      ".meta/Exemplar.elm"
-    ]
-  },
   "exercises": {
     "concept": [
       {
@@ -102,8 +107,17 @@
         ],
         "prerequisites": [ "basics-1" ],
         "status": "wip"
+      },
+      {
+        "slug": "annalyns-infiltration",
+        "name": "Annalyn's Infiltration",
+        "uuid": "9f501a73-14e3-4ada-8359-fe051530554a",
+        "concepts": [
+          "booleans"
+        ],
+        "prerequisites": [ "basics-2" ],
+        "status": "wip"
       }
-
     ],
     "practice": [
       {

exercises/concept/annalyns-infiltration/.docs/hints.md

@@ -0,0 +1,13 @@
+# Hints
+
+## General
+
+- Boolean functions and operators are described in the [Elm documentation of the Basics module][bool].
+
+[bool]: https://package.elm-lang.org/packages/elm/core/latest/Basics#Bool
+
+## 5. Count the damage that a stealth attack could do
+
+- Conditional examples are provided in the [Elm syntax guide][syntax].
+
+[syntax]: https://elm-lang.org/docs/syntax#conditionals

exercises/concept/annalyns-infiltration/.docs/instructions.md

@@ -0,0 +1,76 @@
+# Instructions
+
+In this exercise, you'll be implementing the quest logic for a new RPG game a friend is developing. The game's main character is Annalyn, a brave girl with a fierce and loyal pet dog. Unfortunately, disaster strikes, as her best friend was kidnapped while searching for berries in the forest. Annalyn will try to find and free her best friend, optionally taking her dog with her on this quest.
+
+After some time spent following her best friend's trail, she finds the camp in which her best friend is imprisoned. It turns out there are two kidnappers: a mighty knight and a cunning archer.
+
+Having found the kidnappers, Annalyn considers which of the following actions she can engage in:
+
+- Fast attack: a fast attack can be made if the knight is sleeping, as it takes time for him to get his armor on, so he will be vulnerable.
+- Stealth attack: if Annalyn reaches the sleeping knight without being detected, she deals 12 damage with a stealth attack. Otherwise, she deals only 7 damage to the knight.
+- Spy: the group can be spied upon if at least one of them is awake. Otherwise, spying is a waste of time.
+- Signal prisoner: the prisoner can be signalled using bird sounds if the prisoner is awake and the archer is sleeping, as archers are trained in bird signaling so they could intercept the message.
+- Free prisoner: if the prisoner is awake and the other two characters are sleeping, a sneaky entry into the camp can free the prisoner. This won't work if the prisoner is sleeping, as the prisoner will be startled by the sudden appearance of her friend and the knight and archer will be awoken. The prisoner can also be freed if the archer is sleeping and Annalyn has her pet dog with her, as the knight will be scared by the dog and will withdraw, and the archer can't equip his bow fast enough to prevent the prisoner from being freed.
+
+You have five tasks: to implement the logic for determining if the above actions are available based on the state of the three characters found in the forest and whether Annalyn's pet dog is present or not.
+
+## 1. Check if a fast attack can be made
+
+Implement the `canFastAttack` function that takes a boolean value that indicates if the knight is awake. This function returns `True` if a fast attack can be made based on the state of the knight. Otherwise, returns `False`:
+
+```elm
+knightIsAwake = True
+
+canFastAttack knightIsAwake
+    --> False
+```
+
+## 2. Check if the group can be spied upon
+
+Implement the `canSpy` function that takes three boolean values, indicating if the knight, archer and the prisoner, respectively, are awake. The function returns `True` if the group can be spied upon, based on the state of the three characters. Otherwise, returns `False`:
+
+```elm
+knightIsAwake = False
+archerIsAwake = True
+prisonerIsAwake = False
+
+canSpy knightIsAwake archerIsAwake prisonerIsAwake
+    --> True
+```
+
+## 3. Check if the prisoner can be signalled
+
+Implement the `canSignalPrisoner` function that takes two boolean values, indicating if the archer and the prisoner, respectively, are awake. The function returns `True` if the prisoner can be signalled, based on the state of the two characters. Otherwise, returns `False`:
+
+```elm
+archerIsAwake = False
+prisonerIsAwake = True
+
+canSignalPrisoner archerIsAwake prisonerIsAwake
+    --> True
+```
+
+## 4. Check if the prisoner can be freed
+
+Implement the `canFreePrisoner` function that takes four boolean values. The first three parameters indicate if the knight, archer and the prisoner, respectively, are awake. The last parameter indicates if Annalyn's pet dog is present. The function returns `True` if the prisoner can be freed based on the state of the three characters and Annalyn's pet dog presence. Otherwise, it returns `False`:
+
+```elm
+knightIsAwake = False
+archerIsAwake = True
+prisonerIsAwake = False
+petDogIsPresent = False
+
+canFreePrisoner knightIsAwake archerIsAwake prisonerIsAwake petDogIsPresent
+    --> False
+```
+
+## 5. Count the damage that a stealth attack could do
+
+Implement the `stealthAttackDamage` function that takes a boolean value indicating if Annalyn was detected. This function returns 7 if she was detected, 12 otherwise.
+
+```elm
+annalynIsDetected = True
+
+stealthAttackDamage annalynIsDetected
+    --> 7
+```

exercises/concept/annalyns-infiltration/.docs/introduction.md

@@ -0,0 +1,42 @@
+# Introduction
+
+The `Bool` type is one of the building blocks of the language.
+It aims at describing whether something is true or false, with the respective `True` and `False` values.
+The name `Bool` is short for Boolean, which is a field of mathematics related to logical thinking, named after the work of George Boole.
+
+## Boolean operators
+
+There are two functions and two operators to manipulate values of type `Bool`.
+
+- `not : Bool -> Bool`
+  This function transforms `True` into `False` and `False` into `True`.
+- `(&&) : Bool -> Bool -> Bool`
+  This operator called "AND" takes two booleans and returns `True` if they are both `True`.
+  For example, `True && True` returns `True` but `True && False` returns `False`.
+- `(||) : Bool -> Bool -> Bool`
+  This operator called "OR" takes two booleans and returns `True` if at least one of them is `True`.
+  For example, `False || False` returns `False` but `True || False` returns `True`.
+- `xor : Bool -> Bool -> Bool`
+  This function (not operator) called "XOR" takes two booleans and returns `True` if and only if one is `True` and the other is `False`.
+
+The `&&` and `||` operators do not have the same priority.
+The priority of `&&` is higher than the one of `||`, just like with multiplication `*` and addition `+`.
+As a consequence, the expression `True || False && False` is equivalent to `True || (False && False)` which is different from `(True || False) && False`.
+While the former returns `True` the latter returns `False`.
+
+## Conditional branching
+
+Booleans are extremely useful to make branches in your code that only get executed if certain conditions are met.
+In Elm, this is done with an `if-then-else` expression, used as follows.
+
+```elm
+if someCondition then
+    doSomething
+else
+    doSomethingElse
+```
+
+The value `someCondition` can be any expression that returns a `Bool`.
+If that boolean value is `True`, the code will execute `doSomething`.
+Otherwise it is `False` and the code will execute `doSomethingElse`.
+The `else` branch is mandatory, contrary to some other programming languages.

exercises/concept/annalyns-infiltration/.meta/Exemplar.elm

@@ -0,0 +1,30 @@
+module AnnalynsInfiltration exposing (canFastAttack, canFreePrisoner, canSignalPrisoner, canSpy, stealthAttackDamage)
+
+
+canFastAttack : Bool -> Bool
+canFastAttack knightIsAwake =
+    not knightIsAwake
+
+
+canSpy : Bool -> Bool -> Bool -> Bool
+canSpy knightIsAwake archerIsAwake prisonerIsAwake =
+    knightIsAwake || archerIsAwake || prisonerIsAwake
+
+
+canSignalPrisoner : Bool -> Bool -> Bool
+canSignalPrisoner archerIsAwake prisonerIsAwake =
+    not archerIsAwake && prisonerIsAwake
+
+
+canFreePrisoner : Bool -> Bool -> Bool -> Bool -> Bool
+canFreePrisoner knightIsAwake archerIsAwake prisonerIsAwake petDogIsPresent =
+    not knightIsAwake && not archerIsAwake && prisonerIsAwake || not archerIsAwake && petDogIsPresent
+
+
+stealthAttackDamage : Bool -> Int
+stealthAttackDamage annalynIsDetected =
+    if annalynIsDetected then
+        7
+
+    else
+        12

exercises/concept/annalyns-infiltration/.meta/config.json

@@ -0,0 +1,15 @@
+{
+  "blurb": "Learn usage of Booleans while helping Annalyn rescue her friend",
+  "authors": [
+    "mpizenberg"
+  ],
+  "contributors": [
+    "ceddlyburge"
+  ],
+  "forked_from": ["fsharp/AnnalynsInfiltration"],
+  "files": {
+    "solution": ["src/AnnalynsInfiltration.elm"],
+    "test": ["tests/Tests.elm"],
+    "exemplar": [".meta/Exemplar.elm"]
+  }
+}