seedfile

A reckoner seed: text files over the guarded builtins (machines/seeds/seedfile.shoddy)

Summary

seedfile is a reckoner seed: a small file that bridges one machine's words into the reckoner calculator. It bridges text files: READLINES WRITELINES APPENDLINE FILEEXISTS. A bridged word must not be able to abort the session, that is, kill it. But file.shoddy's own ReadLines, WriteLines and AppendLine all abort on a path they cannot use. So this seed does not call them. READLINES goes straight to the TryReadLines builtin, which answers the lines or the reason. WRITELINES and APPENDLINE reimplement the line-joining over TryWriteFile. The runtime added those guarded words for this purpose.

Why It's Useful

APPENDLINE has no guarded builtin twin. A builtin is a word wired into the language itself; a guarded one refuses instead of aborting. There is a TryWriteFile but no TryAppendFile. So APPENDLINE reads what is there and writes it back with the new line on the end. (It reads nothing if the path does not yet exist or cannot be read.) This is an emulation, not the real append. It is the one place this seed's behaviour is not simply the builtin's.

Every word here touches the world, so all four are flagged effectful: their answers can change from one run to the next. Reading a path answers something different each run exactly as writing one does. The flag covers FILEEXISTS too, which is informational, not a guard. It is bridged for convenience. It is never the pre-flight check that keeps a word from aborting the session, because a directory reports False and an unwritable existing file reports True. Every other word here answers on its own rather than leaning on it.

User's Guide

Let st0 = RckSeedFile(RckNew())
RckEval(st0, Chr(34) & "dat/sales.csv" & Chr(34) & " READLINES")
RckEval(st0, Chr(34) & "no/such/path.txt" & Chr(34) & " READLINES")
' x: a refusal naming why — the state, and the session, survive

Word Reference

Word	Description
READLINES ( path -- list )	The file's lines, or a refusal naming why it could not be read.
WRITELINES ( path list -- ok )	Write the list's strings to path, one per line; True on success.
APPENDLINE ( path s -- ok )	Add s as a new last line of path (created if it does not exist); True on success.
FILEEXISTS ( path -- flag )	Whether path names an existing file. Informational only, not a guard: a directory answers False and an unwritable file answers True.

Who Uses It

	User	How
	halifax	The calculator's line-oriented file words: `READLINES`, `WRITELINES`, `APPENDLINE` and `FILEEXISTS`.
	sparky	Sparky folds it too, so a model calling `eval` reaches the same words halifax puts at a prompt.

A mill claims this seed by folding RckSeedFile over its reckoner state. That is all halifax does.

The Machines It Uses

	Machine	Why
	cuttle	The `Cell` type every word here reads and answers.
	reckoner	`RckReg`, `RckSeeding` and the argument readers every registered word is built from.
	seq	List plumbing under the LIST-of-STRING reader `WRITELINES` shares.
	str	`Join` and `EndsWith` do the line-joining file.shoddy's aborting words would otherwise have done; the splitting is the runtime's.