leap: add approaches (#1139)

Author: MatthijsBlom

exercises/practice/leap/.approaches/conditional-expression/content.md

@@ -0,0 +1,118 @@
+# Conditional expression
+
+```haskell
+isLeapYear :: Integer -> Bool
+isLeapYear year =
+  if divisibleBy 100
+    then divisibleBy 400
+    else divisibleBy 4
+  where
+    divisibleBy d = year `mod` d == 0
+```
+
+
+## Conditional expressions
+
+A _conditional expression_ (`if … then … else …`) is a compound expression that uses a test to determine which of two alternatives to evaluate to.
+Many other languages feature a similar construct, often termed 'ternary operator'.
+They are also known as _`if` expressions_.
+
+When `p` is some expression of type `Bool` and `t` and `f` are any two expressions of the same type, then `if p then t else f` will
+
+- evaluate to `t` if `p` evaluates to `True`, and
+- evaluate to `f` if `p` evaluates to `False`.
+
+~~~~exercism/note
+Conditional expressions are [syntactic sugar][wikipedia-syntactic-sugar] for certain `case` expressions:
+
+```haskell
+_ = if p then t else f
+-- is an abbreviation of
+_ = case p of
+  True  -> t
+  False -> f
+```
+~~~~
+
+
+## In this approach
+
+This approach uses exactly two tests to determine whether a year is a leap year.
+
+The first test is for divisibility by 100.
+Once we know if the year is a multiple of 100, we know which further test to perform.
+
+- If the year is evenly divisible by 100, then `divisibleBy 100` will evaluate to `True` and the entire `if` expression will evaluate to whatever `divisibleBy 400` evaluates to.
+- If the year is _not_ evenly divisible by 100, then `divisibleBy 100` is `False` and so the `if` expression evaluates to `divisibleBy 4`.
+
+
+## When to use `if`?
+
+`if` expressions might be a good fit when you
+
+- need an expression that
+- chooses between exactly two options
+- depending on a single `Boolean`.
+
+When you have something other than a `Boolean`, use `case` instead.
+
+When you do not strictly need an expression, an alternative is to [use guards][guards].
+
+When you need to choose between more than two options, guards might be the solution.
+However, guards are not expressions and so are not always applicable.
+In such cases you might want to break out a multi-way `if`, available through the [`MultiWayIf` language extension][multiwayif-extension]:
+
+```haskell
+{- LANGUAGE MultiWayIf -}  -- at the top of the file
+
+_ = if | condition   -> expression
+       | proposition -> branch
+       | otherwise   -> alternative
+-- which is syntactic sugar for
+_ = case () of
+  _ | condition   -> expression
+  _ | proposition -> branch
+  _ | otherwise   -> alternative
+```
+
+For more on this question, see [Guards vs. if-then-else vs. cases in Haskell][so-guards-if-cases] on StackOverflow.
+
+
+## An example of lazy evaluation
+
+Just like 'ternary operators' in other languages, conditional expressions evaluate lazily.
+Specifically, only the relevant branch is evaluated:
+
+```haskell
+ghci> error "Crash!"  -- for demonstration
+*** Exception: Crash!
+ghci> if even 42 then "Success!" else error "Crash!"
+"Success!"
+```
+
+Notice how evaluating the entire `if` expression does not result in a crash, even though one of its branches would if it were evaluated.
+
+In our solution above we have
+
+| year | `divisibleBy 100` | `divisibleBy 400` | `divisibleBy 4` | is leap year |
+| ---- | ----------------- | ----------------- | --------------- | ------------ |
+| 2020 | `False`           | not evaluated     | `True`          | `True`       |
+| 2019 | `False`           | not evaluated     | `False`         | `False`      |
+| 2000 | `True`            | `True`            | not evaluated   | `True`       |
+| 1900 | `True`            | `False`           | not evaluated   | `False`      |
+
+
+[guards]:
+    https://exercism.org/tracks/haskell/exercises/leap/approaches/guards
+    "Approach: a sequence of guards"
+
+
+[multiwayif-extension]:
+    https://downloads.haskell.org/ghc/latest/docs/users_guide/exts/multiway_if.html
+    "GHC Users Guide: Multi-way if-expressions"
+[so-guards-if-cases]:
+    https://stackoverflow.com/questions/9345589/
+    "StackOverflow: Guards vs. if-then-else vs. cases in Haskell"
+[wikipedia-syntactic-sugar]:
+    https://en.wikipedia.org/wiki/Syntactic_sugar
+    "Wikipedia: Syntactic sugar"

exercises/practice/leap/.approaches/conditional-expression/snippet.txt

@@ -0,0 +1,7 @@
+isLeapYear :: Integer -> Bool
+isLeapYear year =
+  if divisibleBy 100
+    then divisibleBy 400
+    else divisibleBy 4
+  where
+    divisibleBy d = year `mod` d == 0

exercises/practice/leap/.approaches/config.json

@@ -0,0 +1,36 @@
+{
+    "introduction": {
+        "authors": [
+            "MatthijsBlom"
+        ]
+    },
+    "approaches": [
+        {
+            "uuid": "a89d3a43-affc-4dc7-97b7-d5ce9353a8d5",
+            "slug": "logical-expression",
+            "title": "Logical expression",
+            "blurb": "Use logical operators to combine several tests into one.",
+            "authors": [
+                "MatthijsBlom"
+            ]
+        },
+        {
+            "uuid": "a6fbc4d9-911b-42cc-aa88-e015dd1f03b0",
+            "slug": "guards",
+            "title": "Guards",
+            "blurb": "Use a sequence of guards.",
+            "authors": [
+                "MatthijsBlom"
+            ]
+        },
+        {
+            "uuid": "708be8e8-0a2e-437d-8b39-6df37326890f",
+            "slug": "conditional-expression",
+            "title": "Conditional expression",
+            "blurb": "Use a single conditional expression.",
+            "authors": [
+                "MatthijsBlom"
+            ]
+        }
+    ]
+}

exercises/practice/leap/.approaches/guards/content.md

@@ -0,0 +1,186 @@
+# Guards
+
+```haskell
+isLeapYear :: Integer -> Bool
+isLeapYear year
+  | indivisibleBy 4   = False
+  | indivisibleBy 100 = True
+  | indivisibleBy 400 = False
+  | otherwise         = True
+  where
+    indivisibleBy d = year `mod` d /= 0
+```
+
+## Guards
+
+Guards can optionally be added to patterns to constrain when they should match.
+For example, in
+
+```haskell
+ageCategory = case age of
+  Just n | n >= 24 -> "Adult"
+  Just n           -> "Nonadult"
+  Nothing          -> "Eternal"
+```
+
+the pattern `Just n` will match both values `Just 5` and `Just 39`, but the pattern `Just n | n >= 24` will only match the latter.
+Because patterns are checked in order, here
+
+- `Just 39` will match the first pattern and so result in `"Adult"`, but
+- `Just 5` will fall through to be matched to the second pattern, which will match, resulting in `"Nonadult"`.
+
+Patterns may contain multiple guards in sequence.
+These will then be checked in order just like patterns.
+The following variant on the above example produces exactly the same result.
+
+```haskell
+ageCategory = case age of
+  Just n | n >= 24   -> "Adult"
+         | otherwise -> "Nonadult"
+  Nothing            -> "Eternal"
+```
+
+Here there is one fewer pattern, but the first one contains one more guard.
+`otherwise` is a synonym of `True`: it is the guard that always succeeds.
+
+Sequences of guards are analogous to `if`–`else if` chains in other languages.
+
+
+## In this approach
+
+When there are not many cases to match against, it is common to use _function definition [syntactic sugar][wikipedia-syntactic-sugar]_ instead of `case` because sometimes that is a bit nicer to read.
+
+```haskell
+categorize (Just n)
+  | n >= 24        = "Adult"
+  | otherwise      = "Nonadult"
+categorize Nothing = "Eternal"
+-- is equivalent to / an abbreviation of
+categorize age = case age of
+  Just n | n >= 24   -> "Adult"
+         | otherwise -> "Nonadult"
+  Nothing            -> "Eternal"
+```
+
+In the case of Leap, there aren't any interesting patterns to match against, so we only match against a name.
+
+```haskell
+-- A "binding pattern", just like `n` above.
+--          👇
+isLeapYear year
+  | ...
+```
+
+It turns out that, if we are careful to ask questions in the right order, we can always potentially attain certainty about the answer by asking one more question.
+
+- If the year is not divisible by 4, then it is _certainly not_ a leap year.
+- If it is, then it _might_ be a leap year.
+  - If divisible by 4 but not by 100, then it _certainly is_ a leap year.
+  - If also divisible by 100, then it _might_ be a leap year.
+    - If divisible by 4 and 100 but not by 400, then it is _certainly not_ a leap year.
+    - Otherwise, i.e. if also divisible by 400, then it _certainly is_ a leap year.
+
+We can encode this sequence of checks using guards as follows.
+
+```haskell
+isLeapYear year
+  | indivisibleBy 4   = False
+  | indivisibleBy 100 = True
+  | indivisibleBy 400 = False
+  | otherwise         = True
+  where
+    indivisibleBy d = year `mod` d /= 0
+```
+
+We need not start checking for divisibility by 4 specifically.
+Starting with 400 is also possible, but our checks and outcomes will be flipped:
+
+```haskell
+isLeapYear :: Integer -> Bool
+isLeapYear year
+  | divisibleBy 400 = True
+  | divisibleBy 100 = False
+  | divisibleBy   4 = True
+  | otherwise       = False
+  where
+    divisibleBy d = year `mod` d == 0
+```
+
+Starting with 100 is more complicated: both years divisible by 100 and years not divisible by 100 sometimes are and sometimes aren't leap years.
+Using guards is still possible, but it necessarily looks different:
+
+```haskell
+isLeapYear year
+  | divisibleBy 100 = divisibleBy 400
+  | otherwise       = divisibleBy   4
+  where
+    divisibleBy d = year `mod` d == 0
+```
+
+This is very similar to the [conditional expression approach][conditional-expression].
+
+
+
+## When to use guards?
+
+Many beginning Haskellers write code like
+
+```haskell
+fromMaybe :: a -> Maybe a -> a
+fromMaybe x m
+  | isJust m  = fromJust m
+  | otherwise = x
+```
+
+or
+
+```haskell
+fromMaybe :: a -> Maybe a -> a
+fromMaybe x m
+  | m == Nothing = x
+  | otherwise    = fromJust m
+```
+
+Don't do this.
+Use `case` instead, whenever possible.
+The compiler will be much more able to help you if you do, such as by checking that you have covered all possible cases.
+It is also nicer to read.
+
+Use guards
+
+- to narrow down when patterns should match, or
+- in lieu of other languages' `if`–`else if` chains.
+
+Because guards are not themselves expressions, the latter use is not always possible.
+In such cases, the [`MultiWayIf` language extension][multiwayif-extension] has your back:
+
+```haskell
+{- LANGUAGE MultiWayIf -}  -- at the top of the file
+
+_ = if | condition   -> expression
+       | proposition -> branch
+       | otherwise   -> alternative
+-- which is syntactic sugar for
+_ = case () of
+  _ | condition   -> expression
+  _ | proposition -> branch
+  _ | otherwise   -> alternative
+```
+
+For more on this question, see [Guards vs. if-then-else vs. cases in Haskell][so-guards-if-cases] on StackOverflow.
+
+
+[conditional-expression]:
+    https://exercism.org/tracks/haskell/exercises/leap/approaches/conditional-expression
+    "Approach: a conditional expression"
+
+
+[multiwayif-extension]:
+    https://downloads.haskell.org/ghc/latest/docs/users_guide/exts/multiway_if.html
+    "GHC Users Guide: Multi-way if-expressions"
+[so-guards-if-cases]:
+    https://stackoverflow.com/questions/9345589/
+    "StackOverflow: Guards vs. if-then-else vs. cases in Haskell"
+[wikipedia-syntactic-sugar]:
+    https://en.wikipedia.org/wiki/Syntactic_sugar
+    "Wikipedia: Syntactic sugar"

exercises/practice/leap/.approaches/guards/snippet.txt

@@ -0,0 +1,8 @@
+isLeapYear :: Integer -> Bool
+isLeapYear year
+  | indivisibleBy   4 = False
+  | indivisibleBy 100 = True
+  | indivisibleBy 400 = False
+  | otherwise         = True
+  where
+    indivisibleBy d = year `mod` d /= 0