Text function tables, move things around, mention leading axis

1 files changed, 123 insertions, 93 deletions

diff --git a/rprt.md b/rprt.md
index 5f45ef1..2b06cc4 100644
--- a/rprt.md
+++ b/rprt.md
@@ -21,6 +21,87 @@ All functions work with two core types:
 
 2. **Text** — string data
 
+### Function Types
+
+A **Selection function** is something of signature `Selection × Selection → Selection`.
+
+A **Text function** is something of signature `Selection × Text → Selection`.
+
+Following APL conventions, functions may have nullary, monadic, and dyadic forms. In these cases the number of arguments that they take varies (though not their types).
+
+### [Leading axis theory](https://aplwiki.com/wiki/Leading_axis_theory) and broadcasting
+
+The leading axis is the buffer selection, followed by the range _index_, followed by the character position in each range. When broadcasting occurs axes are aligned.
+
+TODO `α F ω` explain
+
+### Trains
+
+TODO
+
+## 1.2 The Editor State Monad
+
+All RPRT expressions evaluate within an implicit `EditorState` monad containing:
+- Buffer contents (for all open buffers)
+- Current buffer
+- Current selection
+- File/buffer mappings
+
+Selection and Text functions have signatures `EditorState Selection` and `EditorState Text` respectively.
+
+## 1.3 Type Coercion
+
+When a Text argument is required, a Selection is implicitly coerced to Text by extracting its contents. This coercion has no side effects.
+
+| Input rank | Coerced Text                                                     |
+|------------|------------------------------------------------------------------|
+| 0          | Empty string (position has no extent)                            |
+| 1          | Contents of the range                                            |
+| 2          | Contents of each range (text function broadcasts per range)      |
+| 3          | Contents per buffer per range (broadcasts per buffer then range) |
+
+For ranks 2 and 3, the selection provides multiple text values.
+
+## 1.4 Evaluation Contexts
+
+**Top-level Selection:** Sets the editor's current selection.
+```
+α           # Finds pattern AND sets editor selection to it
+```
+
+**All text operations:** Modify editor content. Note that `F` returns a selection, so at the top level this also changes the current selection.
+```
+α F τ       # F modifies contents, sets selection to changed region.
+α F (β G τ) # Inner G modifies contents but doesn't set selection. F modifies contents and sets the new selection.
+```
+
+**Buffer switching statement:** The `b` statement changes the current buffer in the EditorState.
+```
+b "name"    # Switch current buffer to "name"
+/pattern/   # Searches in "name"
+```
+
+The `b` statement is not a function and cannot be composed. It only appears as a top-level statement.
+
+## 1.5 The Grouping Operator `{}`
+
+The grouping operator `{}` provides transactional semantics: all operations within see the same input editor state, and their modifications are merged with position tracking where possible. Any error aborts the entire evaluation.
+
+**Syntax:** `{ op₁ , op₂ , ... , opₙ }`
+
+**Semantics:**
+- Captures editor state on entry
+- All operations execute with the original positions
+- Returns the union of all resulting Selections
+
+# 1.6 Composition and Parsing
+
+**Precedence:** Following BQN rules:
+- Operators bind tighter than functions
+- Functions and operators apply left-to-right
+- Dyadic functions are infix
+
+
 # 2. Selection Functions
 
 Selection functions produce Selection outputs and take zero (nullary functions), one (monadic functions), or two (dyadic functions) inputs of type Selection.
@@ -133,90 +214,60 @@ The complement operator `~` takes a selection function and produces a new select
 | 2                     | 2                      | The selection corresponding to the ranges between the selections |
 | 3                     | 3                      | The broadcast of `~` to each buffer                              |
 
-# 3. Text Functions and Editor State
+# 3. Text Functions
 
-## 3.1 The Editor State Monad
-
-All RPRT expressions evaluate within an implicit `EditorState` monad containing:
-- Buffer contents (for all open buffers)
-- Current buffer
-- Current selection
-- File/buffer mappings
-
-Selection and Text functions have signatures `EditorState Selection` and `EditorState Text` respectively.
-
-## 3.2 Type Coercion
-
-When a Text argument is required, a Selection is implicitly coerced to Text by extracting its contents. This coercion has no side effects.
-
-| Input rank | Coerced Text                                                     |
-|------------|------------------------------------------------------------------|
-| 0          | Empty string (position has no extent)                            |
-| 1          | Contents of the range                                            |
-| 2          | Contents of each range (text function broadcasts per range)      |
-| 3          | Contents per buffer per range (broadcasts per buffer then range) |
-
-For ranks 2 and 3, the selection provides multiple text values. Text operations broadcast accordingly: if `α F β` where β is rank 2, the operation applies once per range in β, using the contents of each range as the text argument.
-
-
-## 3.3 Text Operations
+## 3.1 Text Operations
 
 Text operations have signature `Selection × Text → Selection`. They modify the editor state (buffer contents) and return the affected Selection.
 
-TODO: unfortunately `.` and `d` ignore opposite arguments so we're stuck with not being able to give monadic text funcions?
-
-| Function | Semantics                                                              |
-|----------|------------------------------------------------------------------------|
-| `α . τ`  | Current selection in buffer(s) named by `τ` (`α` ignored)              |
-| `α c τ`  | Change (replace) `α` with text `τ`                                     |
-| `α i τ`  | Insert text `τ` before `α`                                             |
-| `α a τ`  | Append text `τ` after `α`                                              |
-| `α d τ`  | Delete `α` (`τ` ignored)                                               |
-| `α w τ`  | Write buffers associated with `α` (`τ` ignored)                        |
-| `α \| τ` | Pipe `α` through command `τ`, return rank 3 selection of output buffer |
+Text operations use [leading axis theory](https://aplwiki.com/wiki/Leading_axis_theory) where buffer names are the leading axis: TODO TODO TODO if `α F β` where `β` is rank 2 but `α` is rank 1, then operation applies once per range in `β`, using the contents of each range as the text argument.
+
+| Function | Effect                                                       | Return selection     |
+|----------|--------------------------------------------------------------|----------------------|
+| `.`      | No-op                                                        | Current selection    |
+| `c`      | No-op                                                        | Current selection    |
+| `i`      | No-op                                                        | Current selection    |
+| `a`      | No-op                                                        | Current selection    |
+| `d`      | Delete current selection in                                  | Empty selection      |
+| `w`      | Write the current buffer to its associated file.             | Current selection    |
+| `\|`     | Run current selection as shell commands, replace with output | Selection of outputs |
+
+**Note:** `\|` is undefined when the rank of the current selection is 0.
+
+| Function | Effect                                           | Return selection                            |
+|----------|--------------------------------------------------|---------------------------------------------|
+| `. τ`    | No-op                                            | Current selection in buffers named by `τ`   |
+| `c τ`    | No-op                                            | Replace the current selection by `τ`        |
+| `i τ`    | No-op                                            | Insert `τ` into the current selection       |
+| `a τ`    | No-op                                            | Append `τ` to the current selection         |
+| `d τ`    | Delete current selection in buffers named by `τ` | Empty selection in buffers named by `τ`     |
+| `w τ`    | Write the buffers named by `τ`.                  | Current selection in buffers named by `τ`   |
+| `\| τ`   | Run `τ`                                          | Return selection of ephemeral buffer output |
 
 **Note:** The text argument `τ` may be a string literal or a Selection (which coerces to Text).
+**Note:** `\|` and `d` are undefined when the rank of `τ` is 0.
+
+| Function | Effect                                               | Semantics                                                 |
+|----------|------------------------------------------------------|-----------------------------------------------------------|
+| `α . τ`  | No-op                                                | Current selection in buffer(s) named by `τ` (`α` ignored) |
+| `α c τ`  | No-op                                                | Change (replace) `α` with text `τ`                        |
+| `α i τ`  | No-op                                                | Insert text `τ` before `α`                                |
+| `α a τ`  | No-op                                                | Append text `τ` after `α`                                 |
+| `α d τ`  | Delete `α` in buffers named by `τ`                   | Empty selection in buffers nameb by `τ`                   |
+| `α w τ`  | Write (concatenation of) `α` in buffers named by `τ` | `α`                                                       |
+| `α \| τ` | Pipe `α` through command `τ`                         | Return selection of ephemeral output buffer               |
 
-**Note:** The `.` function unifies multiple use cases:
-- `.` (nullary) — current selection in current buffer
-- `e . "name"` — current selection in buffer "name"
-- `e . β` where β is rank 2 or 3 — current selections in buffers named by β's contents (returns rank 3)
-
-## 3.4 Evaluation Contexts
-
-**Top-level Selection:** Sets the editor's current selection.
-```
-α           # Finds pattern AND sets editor selection to it
-```
+**Examples:**
 
-**All text operations:** Modify editor content. Note that `F` returns a selection, so at the top level this also changes the current selection.
-```
-α F τ       # F modifies contents, sets selection to changed region.
-α F (β G τ) # Inner G modifies contents but doesn't set selection. F modifies contents and sets the new selection.
-```
+TODO: throw some combinators in to make this example nicer.
 
-**Buffer switching statement:** The `b` statement changes the current buffer in the EditorState.
 ```
-b "name"    # Switch current buffer to "name"
-/pattern/   # Searches in "name"
+| "date"                         # Run date with no input, returns selection to output
+/pattern/ c (| "date")           # Replace pattern with date command output
+selection c (selection | "sort") # Pipe selection through sort, replace with result
 ```
 
-The `b` statement is not a function and cannot be composed. It only appears as a top-level statement.
-
-## 3.5 The Grouping Operator `{}`
-
-The grouping operator `{}` provides transactional semantics: all operations within see the same input editor state, and their modifications are merged with position tracking where possible. Any error aborts the entire evaluation.
-
-**Syntax:** `{ op₁ , op₂ , ... , opₙ }`
-
-**Semantics:**
-- Captures editor state on entry
-- All operations execute with the original positions
-- Returns the union of all resulting Selections
-
-**Example:**
-
-Where `α` and `β` are selections
+An idiom
 ```
 α {swap i , d} β
 ```
@@ -226,24 +277,3 @@ Evaluates in parallel
 * `α d β` which means "delete α"
 
 The net result of this is to _move_ the content of α to (the start of) the selection given by β.
-
-## 3.6 Shell Integration
-
-The `|` text function pipes selections through shell commands, returning rank 3 selections for ephemeral buffers containing command output. Use the empty selection `e` to run commands with no stdin.
-
-**Examples:**
-
-TODO: throw some combinators in to make this example nicer.
-
-```
-e | "date"                 # Run date with no input, returns selection to output
-/pattern/ c (e | "date")   # Replace pattern with date command output
-selection c (selection | "sort")  # Pipe selection through sort, replace with result
-```
-
-# 4 Composition and Parsing
-
-**Precedence:** Following BQN rules:
-- Operators bind tighter than functions
-- Functions and operators apply left-to-right
-- Dyadic functions are infix