From 29864ea0a6d6bc3c4d28765a200337256a5d3241 Mon Sep 17 00:00:00 2001
From: kitty <nepeta@canaglie.net>
Date: Tue, 31 Mar 2026 19:24:49 +1100
Subject: some input internals

maybe this stuff should be hidden. not sure yet
---
 readme.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

(limited to 'readme.md')

diff --git a/readme.md b/readme.md
index b41ba3a..d7b5341 100644
--- a/readme.md
+++ b/readme.md
@@ -118,6 +118,12 @@ of a `value`. (in compile mode u is whatever was on the stack already.)
 rotate the three topmost values on the stack so that the topmost value
 is moved to the third highest.
 
+### `/buffer   ( -- u )`
+the size of an input buffer.
+
+### `/linebuf   ( -- u )`
+the size of a line buffer.
+
 ### `/mod   ( u1 u2 -- u3 u4 )`
 divide u1 by u2. result is in u4, remainder is in u3.
 
@@ -260,6 +266,12 @@ perform bitwise AND on u1 and u2.
 a variable containing the current numeric input/output base.
 by default this is 10.
 
+### `base-buffer   ( -- a )`
+the address of the base input buffer which reads from the terminal.
+
+### `base-linebuffer   ( -- a )`
+the address of the base line input buffer.
+
 ### `begin   ( -- ) IMMEDIATE COMPILE-ONLY`
 mark the beginning of a begin-again, begin-until,
 or begin-while-repeat loop.
@@ -274,6 +286,22 @@ a 32 bit branch offset must be written immediately after.
 ### `brk@   ( -- a )`
 yields current program break.
 
+### `buf>buf   ( a -- a' )`
+transform an input buffer pointer into the *true buffer pointer*,
+skipping past the header.
+
+### `buf>fd   ( a -- a' )`
+transform an input buffer pointer into the file descriptor that the buffer is read from.
+
+### `buf>in   ( a -- a' )`
+transform an input buffer pointer into the number of read characters from that input buffer.
+
+### `buf>line   ( a -- a' )`
+transform an input buffer pointer into the corresponding line buffer variable pointer.
+
+### `buf>used   ( a -- a' )`
+transform an input buffer pointer into the number of characters contained in the input buffer.
+
 ### `bye   ( -- )`
 exits the forth system.
 
@@ -426,6 +454,9 @@ add the given charater into the numeric output buffer.
 if the flag is true, execute the following if statement,
 terminated by `else` or `then`.
 
+### `init-source   ( -- n )`
+yield the value of source-id when processing the initialisation script.
+
 ### `immediate   ( -- )`
 mark the most recently defined word as immediate.
 
@@ -446,6 +477,18 @@ set the deferred word name to execute xt.
 a variable containing the execution token of
 the most recently created word.
 
+### `latest-input-buffer   ( -- a )`
+a variable: the address of the highest recursed (current) input buffer.
+
+### `linebuf>used   ( a -- a' )`
+transform a line buffer pointer into the number of used characters of the buffer.
+
+### `linebuf>buf   ( a -- a' )`
+transform a line buffer pointer into the real line buffer pointer, skipping the header cells.
+
+### `buf>used   ( a -- a' )`
+transform an input buffer pointer into the number of characters contained in the input buffer.
+
 ### `literal   ( n -- ) IMMEDIATE COMPILE-ONLY`
 compile a push of the literal value n into the currently compiling word.
 
@@ -554,6 +597,12 @@ add a minus sign to the numeric output buffer if n is less than zero.
 ### `smudge   ( -- )`
 toggles the smudge bit on the xt in latest.
 
+### `source-id   ( -- n )`
+yield either the file descriptor of the current input file,
+-1 if the current input is from a string,
+or -2 if the current input is the initialisation script
+built into the binary.
+
 ### `sp   ( -- a )`
 yield the address of the stack pointer.
 note that the address points to the stack *before*
@@ -573,6 +622,9 @@ push the file descriptor of stdin to the stack.
 ### `stdout   ( -- 1 )`
 push the file descriptor of stdout to the stack.
 
+### `string-source   ( -- n )`
+yield the value of source-id when processing a string.
+
 ### `swap   ( u1 u2 -- u2 u1 )`
 swap the two topmost values on the stack.
 
-- 
cgit v1.2.3