diff --git a/concepts/arrays/about.md b/concepts/arrays/about.md index 62704a4a..56ff22eb 100644 --- a/concepts/arrays/about.md +++ b/concepts/arrays/about.md @@ -1,6 +1,7 @@ # About -Arrays are Factor's fixed-length, immutable sequence type. +Arrays are Factor's fixed-length sequence type: you can change the +elements but not the length. Literals use `{ … }` with whitespace between elements; the `arrays` vocabulary adds small constructors that pull values off the stack: diff --git a/concepts/arrays/introduction.md b/concepts/arrays/introduction.md index caca76f3..9c43ec76 100644 --- a/concepts/arrays/introduction.md +++ b/concepts/arrays/introduction.md @@ -1,7 +1,8 @@ # Introduction -Arrays are Factor's primary fixed-length, immutable sequence -type, written `{ … }`. The `arrays` and `sequences` vocabularies +Arrays are Factor's primary fixed-length sequence type, written +`{ … }`: you can change the elements but not the length. The `arrays` +and `sequences` vocabularies together give you small constructors that take values off the stack, plus everyday operations for joining, reversing, and looking up elements. diff --git a/concepts/sequences/about.md b/concepts/sequences/about.md index 895673f8..205739e4 100644 --- a/concepts/sequences/about.md +++ b/concepts/sequences/about.md @@ -42,10 +42,10 @@ with the others. | `find-last` | `( seq quot -- i/f elt/f )` | | `produce` | `( pred quot -- seq )` | -Arrays are immutable; the `prefix`/`suffix`/`append`/`prepend` operations all -return new sequences without modifying the original. Vectors are -mutable — `push` and `pop` work in place — but `clone` is the right -starting point if you want a fresh copy. +Arrays are fixed-length, so the `prefix`/`suffix`/`append`/`prepend` +operations all return new sequences rather than growing the original. +Vectors are resizable — `push` and `pop` work in place — but `clone` +is the right starting point if you want a fresh copy. ## Conversions diff --git a/exercises/concept/boatswains-bilge/.docs/introduction.md b/exercises/concept/boatswains-bilge/.docs/introduction.md index 735a65f7..3a71f83b 100644 --- a/exercises/concept/boatswains-bilge/.docs/introduction.md +++ b/exercises/concept/boatswains-bilge/.docs/introduction.md @@ -1,10 +1,10 @@ # Introduction -Pumps, valves, hoses — anything that holds an OS handle has to -be *released* when you're done with it. Factor's -[`destructors`][destructors] vocab wraps these in a framework -that guarantees cleanup, even when an exception unwinds the -stack midway through a routine. +Pumps, valves, hoses — anything that holds an operating-system +resource (an open file, a network connection) has to be *released* +when you're done with it. Factor's [`destructors`][destructors] vocab +wraps these in a framework that guarantees cleanup, even when an error +interrupts your code partway through. ## The class and the generic diff --git a/exercises/concept/cargo-shuffle/.docs/introduction.md b/exercises/concept/cargo-shuffle/.docs/introduction.md index 05b6fe4c..fd5da871 100644 --- a/exercises/concept/cargo-shuffle/.docs/introduction.md +++ b/exercises/concept/cargo-shuffle/.docs/introduction.md @@ -1,9 +1,10 @@ # 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**. Picture a stack of cargo crates on a quay, newest on top. +calling functions like `square(add(2, 3))`, you write a row of +**words** left to right — `2 3 + square` — that pass values to each +other through a shared **data stack**. Picture a stack of cargo crates +on a quay, newest on top. ## Comments diff --git a/exercises/concept/currency-conversion/.docs/introduction.md b/exercises/concept/currency-conversion/.docs/introduction.md index 6d959f13..8a91ebef 100644 --- a/exercises/concept/currency-conversion/.docs/introduction.md +++ b/exercises/concept/currency-conversion/.docs/introduction.md @@ -15,8 +15,8 @@ float in one calculation, the result comes out as a float: 2 3.0 + . ! => 5.0 ``` -Underscores are allowed inside number literals as digit separators -and are ignored by the parser. +You can put underscores inside a number to group the digits — +`1_000_000` — and Factor just ignores them. ## Division words diff --git a/exercises/concept/dragons-descendants/.docs/introduction.md b/exercises/concept/dragons-descendants/.docs/introduction.md index 50064b2a..954c0c02 100644 --- a/exercises/concept/dragons-descendants/.docs/introduction.md +++ b/exercises/concept/dragons-descendants/.docs/introduction.md @@ -3,7 +3,8 @@ Tuples can extend other tuples. `TUPLE: child < parent slots ;` declares a class whose instances are also instances of `parent` — they get the parent's slots in addition to their own, and the -parent's accessors work on them transparently. +parent's accessors work on them too, just as if they'd been defined on +the child. ```factor USING: accessors ; diff --git a/exercises/concept/factory-failsafe/.docs/introduction.md b/exercises/concept/factory-failsafe/.docs/introduction.md index 7f6cda81..c6756ea5 100644 --- a/exercises/concept/factory-failsafe/.docs/introduction.md +++ b/exercises/concept/factory-failsafe/.docs/introduction.md @@ -1,8 +1,8 @@ # Introduction Factor's error system has three pieces: `throw` to signal an error, -`recover` to handle one, and `ERROR:` to define a tuple-typed error -class. +`recover` to handle one, and `ERROR:` to define your own kind of +error. ## `throw` diff --git a/exercises/concept/lasagna/.docs/introduction.md b/exercises/concept/lasagna/.docs/introduction.md index 2f61f5b0..6de7f634 100644 --- a/exercises/concept/lasagna/.docs/introduction.md +++ b/exercises/concept/lasagna/.docs/introduction.md @@ -25,7 +25,8 @@ values from the top of the stack and pushes some values back. ``` A related word, `.s`, prints the *whole* data stack without consuming -anything — handy at the listener for seeing what a snippet leaves +anything — handy in the listener (Factor's interactive prompt, where +you type code and see results) for seeing what a snippet leaves behind. It's why later examples sometimes end in `.s` rather than `.`: they leave more than one value on the stack, and `.s` shows them all. diff --git a/exercises/concept/librarians-ledger/.docs/introduction.md b/exercises/concept/librarians-ledger/.docs/introduction.md index afe54bc6..813798da 100644 --- a/exercises/concept/librarians-ledger/.docs/introduction.md +++ b/exercises/concept/librarians-ledger/.docs/introduction.md @@ -13,10 +13,10 @@ for the running form. reduce ( seq init quot: ( prev elt -- next ) -- result ) ``` -`reduce` walks a sequence, threading an accumulator through a -two-argument quotation. The quotation receives the running -accumulator and the next element; whatever it leaves on the -stack becomes the new accumulator. +`reduce` goes through a sequence one item at a time, carrying along a +running result (the *accumulator*) and feeding it to a two-argument +quotation. The quotation receives the running accumulator and the next +element; whatever it leaves on the stack becomes the new accumulator. ```factor USING: math sequences ; diff --git a/exercises/concept/mixed-juices/.docs/introduction.md b/exercises/concept/mixed-juices/.docs/introduction.md index da0c02fe..8433f484 100644 --- a/exercises/concept/mixed-juices/.docs/introduction.md +++ b/exercises/concept/mixed-juices/.docs/introduction.md @@ -15,7 +15,8 @@ until ( pred body -- ) `pred` and `body` are both quotations that operate on the data stack. `while` keeps looping while `pred` leaves a truthy value; -`until` is the symmetric form (loop while `pred` leaves `f`). +`until` is the opposite: it keeps looping *until* `pred` becomes true +(that is, while `pred` leaves `f`). A single piece of state can flow on the stack between the predicate and the body: diff --git a/exercises/concept/mosaic-making/.docs/introduction.md b/exercises/concept/mosaic-making/.docs/introduction.md index b554c24b..e49917ff 100644 --- a/exercises/concept/mosaic-making/.docs/introduction.md +++ b/exercises/concept/mosaic-making/.docs/introduction.md @@ -1,10 +1,10 @@ # Introduction -Arrays are Factor's fixed-length, immutable sequence type. You -already know how to write a literal array — `{ … }` — and how to -slice and aggregate one. This exercise covers the small toolkit -that comes up when you build arrays from values on the stack and -then look up or rearrange their contents. +Arrays are Factor's fixed-length sequences: you can change the +elements, but not the length. You already know how to write a literal +array — `{ … }` — and how to slice and aggregate one. This exercise +covers the small toolkit that comes up when you build arrays from +values on the stack and then look up or rearrange their contents. ## Building from the stack diff --git a/exercises/concept/quayside-crew/.docs/introduction.md b/exercises/concept/quayside-crew/.docs/introduction.md index bd47b974..ef321fd1 100644 --- a/exercises/concept/quayside-crew/.docs/introduction.md +++ b/exercises/concept/quayside-crew/.docs/introduction.md @@ -3,7 +3,7 @@ Factor's threads are *cooperative coroutines* — they share one OS thread, hand control to each other at I/O and at explicit yield points, and never run truly simultaneously. Anything you do -*between* yields is effectively atomic. But if a compound +*between* yields happens as one uninterrupted step. But if a compound operation (read-modify-write) yields midway, another thread can slip in and change the world before you finish — and that's a race. diff --git a/exercises/concept/role-playing-game/.docs/introduction.md b/exercises/concept/role-playing-game/.docs/introduction.md index d4544ffd..0e0a1df0 100644 --- a/exercises/concept/role-playing-game/.docs/introduction.md +++ b/exercises/concept/role-playing-game/.docs/introduction.md @@ -1,6 +1,7 @@ # Introduction -A *tuple* is Factor's record/struct/class type. Each tuple class has +A *tuple* bundles several named values together into one object — what +other languages call a record, struct, or class. Each tuple class has a fixed set of named slots and Factor automatically generates getters and setters for them. diff --git a/exercises/concept/rpn-calculator/.docs/introduction.md b/exercises/concept/rpn-calculator/.docs/introduction.md index 17ec24e2..d6dac844 100644 --- a/exercises/concept/rpn-calculator/.docs/introduction.md +++ b/exercises/concept/rpn-calculator/.docs/introduction.md @@ -1,8 +1,8 @@ # Introduction -A *quotation* — code in `[ ]` brackets — is a first-class value in -Factor. You can store one in a variable, put one in an array, pass -one to another word, and *call* it later. +A *quotation* — code in `[ ]` brackets — is itself a value in Factor, +just like a number or a string. You can store one in a variable, put +one in an array, pass one to another word, and *call* it later. ## `call` diff --git a/exercises/concept/signalers-satchel/.docs/introduction.md b/exercises/concept/signalers-satchel/.docs/introduction.md index 69eb8984..0b495355 100644 --- a/exercises/concept/signalers-satchel/.docs/introduction.md +++ b/exercises/concept/signalers-satchel/.docs/introduction.md @@ -59,7 +59,7 @@ string can coerce with `>string`. ## `?head` and `?tail` — strip a marker if present Framed readings carry marker text that may or may not be there. -`?head` and `?tail` (in `sequences`) try to strip a prefix or +`?head` and `?tail` (in `splitting`) try to strip a prefix or suffix, returning the (possibly shortened) sequence *and* a boolean reporting whether the marker was found: