From eae7690d755d860021d204db7b84435b6f8d5597 Mon Sep 17 00:00:00 2001 From: Eric Willigers Date: Sun, 21 Jun 2026 10:11:29 +1000 Subject: [PATCH 1/2] How words compose --- .../cargo-shuffle/.docs/introduction.md | 25 +++++++++++++++---- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/exercises/concept/cargo-shuffle/.docs/introduction.md b/exercises/concept/cargo-shuffle/.docs/introduction.md index 2ad702d..600e8e2 100644 --- a/exercises/concept/cargo-shuffle/.docs/introduction.md +++ b/exercises/concept/cargo-shuffle/.docs/introduction.md @@ -19,11 +19,10 @@ left to right. 1 2 3 ! stack (bottom → top): 1 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. `.` pops -the top value and prints it; `.s` prints the *whole* stack without -consuming anything, which is handy for seeing what a snippet left -behind. +Every word reads its inputs from the top of the stack and writes its +outputs back there. `.` pops the top value and prints it; `.s` prints +the *whole* stack without consuming anything, which is handy for +seeing what a snippet left behind. ## Stack effects @@ -65,6 +64,22 @@ crate to the top. The wider family (`-rot`, `dupd`, `swapd`, `2dup`, …) follows the same idea; you will meet those words later. +## How words compose + +Words written in a row run **left to right**: each word acts on the +stack the word before it left behind. So `dup over` just means "run +`dup`, then run `over` on what `dup` left." Here is what `swap nip` +does to the stack `1 2` (bottom → top), one word at a time: + +```factor +1 2 ! 1 2 the starting crates +swap ! 2 1 swap flipped the top two +nip ! 1 nip dropped the 2nd-from-top crate (the 2) +``` + +Concretely, `dup over` on `1 2` runs `dup` first (leaving `1 2 2`), +then `over` on that (leaving `1 2 2 2`). + ## Naming conventions Words use `lowercase-kebab-case`: lowercase letters joined by hyphens. From 7342b7b1bcded7a3d0b52c94c25f2a43e63aac3b Mon Sep 17 00:00:00 2001 From: Eric Willigers Date: Sun, 21 Jun 2026 10:28:41 +1000 Subject: [PATCH 2/2] reword for general audience --- .../concept/backyard-birdwatcher/.docs/introduction.md | 6 +++--- .../concept/currency-conversion/.docs/introduction.md | 4 ++-- .../high-school-sweetheart/.docs/introduction.md | 10 ++++++---- exercises/concept/lasagna/.docs/introduction.md | 4 ++-- 4 files changed, 13 insertions(+), 11 deletions(-) diff --git a/exercises/concept/backyard-birdwatcher/.docs/introduction.md b/exercises/concept/backyard-birdwatcher/.docs/introduction.md index 92c396e..43cdd39 100644 --- a/exercises/concept/backyard-birdwatcher/.docs/introduction.md +++ b/exercises/concept/backyard-birdwatcher/.docs/introduction.md @@ -48,9 +48,9 @@ tail ( seq n -- tailseq ) ! drop first n { 1 2 3 4 5 } 3 tail . ! => { 4 5 } ``` -Both throw if `n` is larger than the sequence. `index-or-length` -clamps `n` to the sequence's length, so chaining it in turns a -potentially-out-of-range slice into a safe one: +Both throw if `n` is larger than the sequence. If `n` is too big, +`index-or-length` shrinks it down to the sequence's length, so the +slice that follows can't run off the end: ``` index-or-length ( seq n -- seq n' ) diff --git a/exercises/concept/currency-conversion/.docs/introduction.md b/exercises/concept/currency-conversion/.docs/introduction.md index b744a9d..6d959f1 100644 --- a/exercises/concept/currency-conversion/.docs/introduction.md +++ b/exercises/concept/currency-conversion/.docs/introduction.md @@ -7,8 +7,8 @@ point numbers and pick the right division word for the job. ## Integers and floats Factor distinguishes integers (`1`, `42`, `1_000_000`) from floating- -point numbers (`1.0`, `3.14`, `6.02e23`). Mixed arithmetic auto- -promotes to a float: +point numbers (`1.0`, `3.14`, `6.02e23`). If you mix an integer and a +float in one calculation, the result comes out as a float: ```factor 2 3 + . ! => 5 diff --git a/exercises/concept/high-school-sweetheart/.docs/introduction.md b/exercises/concept/high-school-sweetheart/.docs/introduction.md index 296f097..6e57c23 100644 --- a/exercises/concept/high-school-sweetheart/.docs/introduction.md +++ b/exercises/concept/high-school-sweetheart/.docs/introduction.md @@ -1,7 +1,9 @@ # Introduction -Factor's *function composition* is just the order you write words. A -word's body is itself a sequence of words: each one consumes some +In Factor, you combine words just by writing them one after another — +the order you write them in *is* how they join up. (Programmers call +this *function composition*.) A word's body is itself a sequence of +words: each one consumes some values from the stack and pushes its result, and the next word picks up where the previous left off. So defining @@ -12,8 +14,8 @@ up where the previous left off. So defining already *is* the composition of `cleanupname`, `first`, and `1string`. -This exercise also introduces **quotations** — Factor's term for an -anonymous, deferred sequence of words. +This exercise also introduces **quotations** — a piece of code you can +store as a value and run later, instead of running it on the spot. ## Quotations diff --git a/exercises/concept/lasagna/.docs/introduction.md b/exercises/concept/lasagna/.docs/introduction.md index d01e1b4..2f61f5b 100644 --- a/exercises/concept/lasagna/.docs/introduction.md +++ b/exercises/concept/lasagna/.docs/introduction.md @@ -37,8 +37,8 @@ them needs `math` in its `USING:` line. 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. +The names inside are just there to help you read it. Factor doesn't +use them — it only tracks the *order* values sit in on the stack. ```factor ! + is specified as ( x y -- sum )