lasagna concept exercise (#173)

Author: keiravillekode

config.json

@@ -31,14 +31,26 @@
   },
   "exercises": {
     "concept": [
+      {
+        "slug": "lasagna",
+        "name": "Leah's Luscious Lasagna",
+        "uuid": "a35d8564-a135-4930-9497-c47ae93857a5",
+        "concepts": [
+          "stack-effect"
+        ],
+        "prerequisites": [],
+        "status": "wip"
+      },
       {
         "slug": "annalyns-infiltration",
         "name": "Annalyns Infiltration",
         "uuid": "57a3408b-1c45-4860-9605-47eb6651fb81",
         "concepts": [
+          "booleans"
+        ],
+        "prerequisites": [
           "stack-effect"
         ],
-        "prerequisites": [],
         "status": "wip"
       }
     ],

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

@@ -1,36 +1,44 @@
 # Introduction
 
-## Booleans in Factor
+This exercise builds on the data stack and stack-effect notation you
+met in [Leah's Luscious Lasagna][lasagna]. Here you will write words
+that combine boolean values.
 
-True and false are written as the words `t` and `f`. `f` is Factor's only
-falsy value — everything else, including `0` and empty collections, is
+## Booleans
+
+The two boolean literals are `t` and `f`. `f` is Factor's only falsy
+value — everything else, including `0` and empty collections, is
 truthy.
 
 ```factor
-t .
-! => t
-
-f .
-! => f
+t .    ! => t
+f .    ! => f
 ```
 
-## Boolean operators
+## Boolean words
 
-Three words in the `kernel` vocabulary handle the common cases:
+Three boolean words live in the `kernel` vocabulary and are available
+without a `USING:` line:
 
-- `and` — returns truthy when both inputs are truthy.
-- `or`  — returns truthy when either input is truthy.
-- `not` — inverts its argument.
+```
+and ( x y -- ? )    ! true when both inputs are truthy
+or  ( x y -- ? )    ! true when either input is truthy
+not ( x   -- ? )    ! inverts its argument
+```
 
 ```factor
 t t and .    ! => t
 t f and .    ! => f
-
 f t or .     ! => t
-
 t not .      ! => f
 ```
 
-Because Factor is concatenative, these words consume their arguments from
-the data stack. If your arguments are on the stack in the "wrong" order for
-a particular operator, use `swap` to flip them.
+The `?` in each output is the stack-effect convention for "a boolean".
+
+## Swapping the top two values
+
+If two values are on the stack in the wrong order for the next word,
+`swap ( x y -- y x )` flips the top two. You will need it for one of
+the tasks below.
+
+[lasagna]: https://exercism.org/tracks/factor/exercises/lasagna

exercises/concept/lasagna/.docs/hints.md

@@ -0,0 +1,31 @@
+# Hints
+
+## General
+
+- You will need to define a constant and three words that operate on
+  the stack.
+- The arithmetic words `+`, `-`, and `*` all live in the `math`
+  vocabulary. Add `math` to your `USING:` line.
+
+## 1. Store the expected bake time in a constant
+
+- Use `CONSTANT:` to define `expected-bake-time` near the top of the
+  file, above the word definitions.
+
+## 2. Calculate the preparation time in minutes
+
+- Use `*` with stack effect `( x y -- product )` to multiply the number
+  of layers by `2`.
+
+## 3. Calculate the remaining oven time in minutes
+
+- Push `expected-bake-time` and then subtract the current time.
+- Remember that `-` computes `deeper - top`. If you push values in the
+  order `current-time`, `expected-bake-time`, you will need `swap` to
+  get the subtraction the right way around.
+
+## 4. Calculate the total working time in minutes
+
+- Reuse the `preparation-time` word you defined in task 2.
+- Only one of the two inputs should go to `preparation-time`; the other
+  should be added to the result.

exercises/concept/lasagna/.docs/instructions.md

@@ -0,0 +1,54 @@
+# Instructions
+
+In this exercise you're going to write some code to help you cook a
+brilliant lasagna from your favorite cooking book.
+
+You have four tasks, all related to the time spent cooking the lasagna.
+
+## 1. Store the expected bake time in a constant
+
+Define the `expected-bake-time` constant, which should return how many
+minutes the lasagna needs to bake in the oven.
+
+According to the cooking book, lasagna needs to be in the oven for a
+total of 40 minutes.
+
+```factor
+expected-bake-time .
+! => 40
+```
+
+## 2. Calculate the preparation time in minutes
+
+Define the `preparation-time` word. It takes the number of layers you
+added to the lasagna off the stack and leaves behind how many minutes
+you spent preparing it, assuming each layer takes 2 minutes to prepare.
+
+```factor
+4 preparation-time .
+! => 8
+```
+
+## 3. Calculate the remaining oven time in minutes
+
+Define the `remaining-time` word. It takes the number of minutes the
+lasagna has already spent in the oven and leaves behind how many
+minutes it still has to remain in there.
+
+```factor
+25 remaining-time .
+! => 15
+```
+
+## 4. Calculate the total working time in minutes
+
+Define the `total-working-time` word. It takes two arguments off the
+stack — first the number of layers in the lasagna, then the number of
+minutes the lasagna has already been in the oven — and leaves behind
+the total time spent cooking so far: the preparation time plus the
+time already in the oven.
+
+```factor
+3 20 total-working-time .
+! => 26
+```

exercises/concept/lasagna/.docs/introduction.md

@@ -0,0 +1,119 @@
+# Introduction
+
+Welcome to Factor! Factor is a *concatenative* language: instead of
+calling functions with parenthesised arguments, you write a sequence of
+words that pass values to each other through a shared **data stack**.
+
+## Comments
+
+A `!` starts a line comment — Factor ignores everything from `!` to the
+end of the line. The examples below use `!` both to annotate what code
+does and to show what it would print.
+
+## The data stack
+
+Writing a literal pushes it onto the top of the stack. Code is read
+left to right.
+
+```factor
+2 3    ! stack (bottom → top): 2 3
+```
+
+There is no other way to pass data around — every word reads its
+inputs from the top of the stack and writes its outputs back there.
+
+## Words
+
+A **word** is Factor's name for a function. Calling a word pops some
+values from the top of the stack and pushes some values back.
+`.` pops the top value and prints it; the integer arithmetic words
+`+`, `-`, `*` pop two numbers and push the result:
+
+```factor
+2 3 + .    ! prints 5
+8 3 - .    ! prints 5    (8 - 3, not 3 - 8)
+2 3 * .    ! prints 6
+```
+
+The arithmetic words live in the `math` vocabulary, so a file that uses
+them needs `math` in its `USING:` line.
+
+## Stack effects
+
+Every word is documented with a **stack effect** of the form
+`( inputs -- outputs )`. It is the word's contract: this word pops the
+inputs off the top of the stack and leaves the outputs in their place.
+The names inside are documentation for humans — the stack itself is
+positional, not named.
+
+```factor
+! + is specified as ( x y -- sum )
+! . is specified as ( x   --     )
+```
+
+The top of the stack is the *right-hand* input. So `8 3 -` has `3` on
+top, the stack effect is `( x y -- difference )`, and the result is
+`8 - 3`.
+
+A trailing `?` in the outputs is the convention for "a boolean", but
+the lasagna exercise uses only numbers.
+
+## Defining a word
+
+`:` starts a word definition, the stack effect comes next, then the
+body, then `;` ends it.
+
+```factor
+: square ( x -- x^2 ) dup * ;
+
+4 square .    ! => 16
+```
+
+Factor's compiler checks that the body actually matches the declared
+stack effect: a word that claims `( x -- y )` but leaves zero or two
+values on the stack will not compile.
+
+## Constants
+
+`CONSTANT:` defines a name for a fixed value. A constant is itself a
+word — calling it pushes the value onto the stack:
+
+```factor
+CONSTANT: pi 3
+
+pi pi * .    ! => 9
+```
+
+`CONSTANT:` is core syntax and does not need a `USING:` line. Place
+constants at the top of the file, before any word that uses them.
+
+## Calling one word from another
+
+A word's body can call any word already in scope, including ones you
+defined earlier in the same file:
+
+```factor
+: double    ( x -- 2x ) 2 * ;
+: quadruple ( x -- 4x ) double double ;
+
+5 quadruple .    ! => 20
+```
+
+This is how the last task in the exercise reuses an earlier one.
+
+## Swapping the top two values
+
+If two values are on the stack in the wrong order for the next word,
+`swap` flips the top two:
+
+```
+swap ( x y -- y x )
+```
+
+`swap` lives in the `kernel` vocabulary.
+
+## Naming conventions
+
+Words and constants both use `lowercase-kebab-case`: lowercase letters
+joined by hyphens (for example, `expected-bake-time`,
+`preparation-time`).

exercises/concept/lasagna/.docs/source.md

@@ -0,0 +1,7 @@
+# Source
+
+Forked from the Julia track's ["Lasagna" exercise][julia-source], which is in turn based on the F# track's ["Lucian's Luscious Lasagna" exercise][fsharp-source], designed by [Erik Schierboom][erik].
+
+[julia-source]: https://github.com/exercism/julia/tree/main/exercises/concept/lasagna
+[fsharp-source]: https://github.com/exercism/fsharp/tree/main/exercises/concept/lucians-luscious-lasagna
+[erik]: https://github.com/ErikSchierboom

exercises/concept/lasagna/.meta/config.json

@@ -0,0 +1,20 @@
+{
+  "authors": [
+    "keiravillekode"
+  ],
+  "files": {
+    "solution": [
+      "lasagna/lasagna.factor"
+    ],
+    "test": [
+      "lasagna/lasagna-tests.factor"
+    ],
+    "exemplar": [
+      ".meta/exemplar.factor"
+    ]
+  },
+  "forked_from": [
+    "julia/lasagna"
+  ],
+  "blurb": "Learn about stack effects in Factor by cooking delicious lasagna."
+}

exercises/concept/lasagna/.meta/design.md

@@ -0,0 +1,31 @@
+# Design
+
+## Goal
+
+Introduce a complete novice to Factor by way of a tiny cooking-themed exercise. This is the first exercise on the track, so it has to teach the fundamentals from scratch: the data stack, words operating on it, and the stack-effect notation that documents every word.
+
+## Learning objectives
+
+- Understand that Factor passes values via a last-in-first-out data stack.
+- Read and write a stack effect of the form `( inputs -- outputs )`.
+- Define a word with `:` ... `;` and have its body match the declared stack effect.
+- Define a constant with `CONSTANT:` and use it as a word.
+- Use the integer arithmetic words `+`, `-`, `*`.
+- Define a word whose body calls another word already in scope.
+- Use `swap` to reorder the top two values when the operator wants them flipped.
+
+## Out of scope
+
+- Locals (`::`, named parameters).
+- Combinators beyond `swap` (`dup`, `dip`, `bi`, `tri`, …).
+- Floating-point arithmetic and the difference between `/` and `/i`.
+- Vocabulary visibility, private words.
+- Tests-framework internals beyond `unit-test`.
+
+## Concepts
+
+- `stack-effect`: every Factor word is documented as `( inputs -- outputs )` and its body must leave exactly that on the stack. This exercise is a student's first encounter with the notation and the calling convention behind it.
+
+## Prerequisites
+
+There are no prerequisites — this is the first concept exercise on the Factor track.

exercises/concept/lasagna/.meta/exemplar.factor

@@ -0,0 +1,13 @@
+USING: kernel math ;
+IN: lasagna
+
+CONSTANT: expected-bake-time 40
+
+: preparation-time ( layers -- minutes )
+    2 * ;
+
+: remaining-time ( current-time -- remaining )
+    expected-bake-time swap - ;
+
+: total-working-time ( layers current-time -- minutes )
+    swap preparation-time + ;

exercises/concept/lasagna/lasagna/lasagna-tests.factor

@@ -0,0 +1,16 @@
+USING: lasagna tools.test ;
+IN: lasagna.tests
+
+! TASK: 1 expected bake time
+{ 40 } [ expected-bake-time ] unit-test
+
+! TASK: 2 preparation time
+{ 2 } [ 1 preparation-time ] unit-test
+{ 8 } [ 4 preparation-time ] unit-test
+
+! TASK: 3 remaining time
+{ 15 } [ 25 remaining-time ] unit-test
+
+! TASK: 4 total working time
+{ 32 } [ 1 30 total-working-time ] unit-test
+{ 16 } [ 4 8 total-working-time ] unit-test