Addresses search a line at a time as sam does, say why they fail, and a failed addr leaves no address

addr's regexps ran mvzr over text[from..hi]: ^ and $ anchored only at the
slice's ends, . matched newlines, the search never wrapped, and every
failure read as bad address syntax. The regexps stay mvzr's, called the
way sam searches (editors/acme/regx.c): one line per haystack, so ^ and $
fall at line boundaries and . never crosses a newline; a pattern naming
\\n runs over the whole text with its . made [^\\n]; /re/ wraps unless
limit is set, and ?re? takes the last match before the range. The ceiling
(mvzr's first alternative, not sam's longest) is documented. A failed
address says why (no match for regexp, address out of range, bad regular
expression), and a failed write to addr leaves no address, so data and
xdata refuse until the next good one instead of writing at the old range.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

1 files changed, 23 insertions, 0 deletions

diff --git a/docs/fs.md b/docs/fs.md
index 6060949b..42e4d9b8 100644
--- a/docs/fs.md
+++ b/docs/fs.md
@@ -243,6 +243,29 @@ whole buffer.
 until someone writes or truncates it, so writing an address and reading it
 back evaluates it, which is what acme(4) promises of its own `addr`.
 
+The regular expressions are mvzr's (sets, `\d`/`\w`/`\s`, `{m,n}` and
+lazy `*?` included), searched the way sam searches (editors/acme/regx.c): as
+lines, so `^` and `$` match at the start and end of any line, `.` and a
+negated class never match a newline, and `$` also matches at the end of a
+text with no final newline. A pattern that names a newline (`\n`) runs over
+the whole text instead, its `.` kept to one line. `/re/` searches forward
+from the end of the current range to `limit` if one is set, and otherwise
+wraps to the start of the text; `?re?` finds the last match ending before
+the range, wrapping to the text's last. The match is the leftmost, but of
+the alternatives at that place mvzr takes the first that matches where sam
+takes the longest (`/gam|gamma/` finds `gam`); in a search begun in the
+middle of a line, `^` inside an alternation can match there; and in a
+pattern that spans lines, `^`, `$` and `[^...]` keep mvzr's own meaning.
+pardes has no regex engine of its own on purpose; these are its limits.
+
+An address that does not evaluate fails the write with why: `bad address
+syntax`, `no match for regexp`, `address out of range` or `bad regular
+expression`. A failed write to `addr` leaves no address at all, where acme
+keeps the old one: until an address is written or `addr` is truncated,
+reading `addr`, and reading, writing or truncating `data` and `xdata`, fail
+with `no address: the last one written to addr failed`, so a script that
+missed its target cannot then write at the last one.
+
 The three flag files `dirty`, `mark` and `scroll` read `0` or `1` and take
 `0` or `1`: whether the buffer differs from its file, whether a write pushes
 an undo point (writing `1` pushes one now), and whether a write scrolls the