Let a program ask how big the text grid is

`RGR(1)` and `RGR(2)` gave the window in pixels and nothing gave columns, rows
or the cell size -- so anything placing a character *and* a sprite at the same
spot had to hardcode a number measured by hand against whatever font the host
loaded. The Breakout in examples/ does exactly that, `CW# = 16`, and it is the
one thing in that listing that breaks on a different font or window.

**`RWINDOW` is BASIC 7.0's own answer and had never been implemented here.**
`RWINDOW(0)` is the current text window's rows and `RWINDOW(1)` its columns.
`RWINDOW(2)` reports a C128's 40 or 80 column screen mode, and this interpreter
has neither -- refused by name, because answering 0 would be a plausible lie,
which is worse than a refusal that says why.

The cell size in pixels is `RGR(3)` and `RGR(4)`, beside the surface's own
dimensions rather than on `RWINDOW`. Two reasons: a cell size is a fact about
the surface, and `RWINDOW` reports the *window*, so dividing `RGR(1)` by a
column count stops being right the moment a program calls `WINDOW`.

Both read a new optional `grid` entry point on `akbasic_TextSink` -- columns,
rows, cell width, cell height -- implemented by the akgl sink and forwarded by
the tee, in the shape `moveto` and `window` already had. NULL everywhere else,
so both verbs refuse by name against a sink with no grid. `akbasic_sink_init_
stdio()` clears it for the same reason it now clears the other two.

Measured on the standalone build: `RGR(3)` answers 16 and `RWINDOW` answers 50
columns by 37 rows -- the three numbers the Breakout listing had written out as
constants -- and `RWINDOW` follows a `WINDOW` call while `RGR(3)` does not.

tests/console_verbs.c drives the answers through a stand-in sink with a grid,
since the harness sink is stdio and has none; tests/graphics_verbs.c covers the
new `RGR` fields, their refusal, and the moved range bound. The `c excerpt=`
block in docs/10-embedding.md moves with the header, which is `docs_examples`
doing its job.

TODO.md section 6 item 31's second half, struck.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

TODO.md

@@ -1960,8 +1960,23 @@ in either corpus runs for minutes, which is why the first of these had never bee
     calling `WINDOW` "ordinary work here rather than anything blocked", which is now half true:
     the work was done and then not plumbed.
 
-    Worth deciding at the same time: **a program still has no way to ask how big the text grid
+    ~~Worth deciding at the same time: **a program still has no way to ask how big the text
-    is.** `RGR(1)` and `RGR(2)` give the window in pixels, and nothing gives columns, rows or
+    grid is.**~~ **Done, and with BASIC 7.0's own function rather than more `RGR` fields.**
+    `RWINDOW(0)` is the current text window's rows and `RWINDOW(1)` its columns -- the C128
+    has exactly this function and this interpreter had never implemented it. `RWINDOW(2)` is
+    refused by name: it reports a 40 or 80 column screen mode and there is no such mode here,
+    so answering 0 would be a plausible lie.
+
+    The cell size in pixels is `RGR(3)` and `RGR(4)`, beside the surface's own dimensions,
+    because that is a fact about the surface -- and because `RWINDOW` reports the *window*,
+    which makes dividing `RGR(1)` by a column count wrong the moment a program calls
+    `WINDOW`. Both read a new optional `grid` entry point on `akbasic_TextSink`, implemented
+    by the akgl sink and forwarded by the tee, NULL everywhere else so both refuse by name.
+
+    `RGR(3)` on the standalone build now answers 16 -- the number the Breakout listing had
+    measured by hand and written out as a constant.
+
+    The original note: `RGR(1)` and `RGR(2)` give the window in pixels, and nothing gives columns, rows or
     the cell size, so anything that wants to place a character *and* a sprite at the same spot
     has to hardcode a cell size measured against the bundled font -- which is what the Breakout
     in `examples/breakout/characters` does, and it is the one thing in that listing that will break

docs/06-graphics.md

@@ -180,10 +180,29 @@ it off and coordinates go back to being window pixels.
 
 `RGR(0)` is the current `GRAPHIC` mode. `RGR(1)` and `RGR(2)` are the drawing
 surface's width and height in pixels — those two are ours rather than 7.0's, and they
-are what a program needs to use a window whose size it did not choose. All three
+are what a program needs to use a window whose size it did not choose. They
-refuse when there is no graphics device, except `RGR(0)`, which is a mode this
+refuse when there is no graphics device, unlike `RGR(0)`, which is a mode this
 interpreter recorded rather than a screen it has to go and measure.
 
+**`RGR(3)` and `RGR(4)` are a character cell's width and height**, also ours. They come
+from the *text* device rather than the graphics one — a character grid belongs to the
+sink — so they refuse by naming that instead. Between them and
+[`RWINDOW`](12-function-reference.md), which gives the current text window in columns
+and rows, a program can place a character and a sprite at the same spot without
+hardcoding a number measured against whatever font the host loaded:
+
+```basic requires=akgl
+10 CW# = RGR(3)
+20 CH# = RGR(4)
+30 COL# = 12
+40 ROW# = 3
+50 CHAR 1, COL#, ROW#, "X"
+60 MOVSPR 1, COL# * CW#, ROW# * CH#
+```
+
+`RWINDOW` follows a `WINDOW` call, because it reports the window. `RGR(3)` and `RGR(4)`
+do not, because windowing does not change how big a character is.
+
 ### WIDTH
 
 `WIDTH 1` or `WIDTH 2` sets how thick a drawn line is. A thick line is drawn as

docs/10-embedding.md

@@ -115,6 +115,7 @@ typedef struct akbasic_TextSink
     akerr_ErrorContext AKERR_NOIGNORE *(*clear)(struct akbasic_TextSink *self);
     akerr_ErrorContext AKERR_NOIGNORE *(*moveto)(struct akbasic_TextSink *self, int col, int row);
     akerr_ErrorContext AKERR_NOIGNORE *(*window)(struct akbasic_TextSink *self, int left, int top, int right, int bottom);
+    akerr_ErrorContext AKERR_NOIGNORE *(*grid)(struct akbasic_TextSink *self, int *columns, int *rows, int *cellw, int *cellh);
 } akbasic_TextSink;
 ```
 
@@ -122,6 +123,12 @@ typedef struct akbasic_TextSink
 supplies its own and draws into a text layer. `readline` is expected to set `*eof` rather
 than block — that is how `INPUT` behaves sanely inside a frame.
 
+**The last three are optional and may be NULL**, which is how `CHAR`, `WINDOW` and
+`RWINDOW` know to refuse by name rather than pretending. Supply `grid` if your text layer
+has a character cell: it is the only way a script can find out how big one is, and
+without it anything placing a character and a sprite at the same spot has to hardcode a
+number measured against your font.
+
 `akbasic_sink_init_tee()` also ships, and composes two sinks into one: writes go to both,
 and `readline` comes from whichever of the two you name as the reader. That is how the SDL
 build puts `PRINT` in a window *and* on stdout. It needs no SDL, so you can use it to log a

docs/12-function-reference.md

@@ -25,8 +25,9 @@ so a call with the wrong number is a syntax error rather than a surprise.
 | `POINTER` | 1 | `POINTER(V)` | The address of a variable's value. |
 | `POINTERVAR` | 1 | `POINTERVAR(V)` | The address of the variable structure itself, metadata included. |
 | `RAD` | 1 | `RAD(n)` | Degrees converted to radians. |
-| `RGR` | 1 | `RGR(f)` | The `GRAPHIC` mode (0), or the drawing surface's width (1) or height (2) in pixels. |
+| `RGR` | 1 | `RGR(f)` | The `GRAPHIC` mode (0), the drawing surface's width (1) or height (2) in pixels, or a character cell's width (3) or height (4). |
 | `RIGHT` | 2 | `RIGHT(A$, n)` | The rightmost `n` characters. Clamped. |
+| `RWINDOW` | 1 | `RWINDOW(f)` | The current text window's rows (0) or columns (1). Field 2 is a C128 screen mode and is refused. |
 | `RSPCOLOR` | 1 | `RSPCOLOR(n)` | One of `SPRCOLOR`'s two shared registers, 1 or 2. |
 | `RSPPOS` | 2 | `RSPPOS(n, f)` | A sprite's x (0), y (1) or speed (2). |
 | `RSPRITE` | 2 | `RSPRITE(n, f)` | One of a sprite's `SPRITE` settings, in `SPRITE`'s argument order. |

docs/17-tutorial-breakout.md

@@ -53,24 +53,24 @@ with it. That is Chapter 18.
 ## Step 2: Measure the screen once, at the top
 
 ```basic norun
-CW# = 16
+CW# = RGR(3)
-CH# = 16
+CH# = RGR(4)
 SCW# = RGR(1)
 SCH# = RGR(2)
-COLS# = SCW# / CW#
+COLS# = RWINDOW(1)
-ROWS# = SCH# / CH#
+ROWS# = RWINDOW(0)
 ```
 
-`RGR(1)` and `RGR(2)` are the window in pixels — see
+Six numbers, none of them assumed. `RGR(1)` and `RGR(2)` are the window in pixels,
-[Chapter 6](06-graphics.md#rgr) — and the game asks for them rather than assuming 800 by
+`RGR(3)` and `RGR(4)` are one character cell, and `RWINDOW` gives the text grid in
-600, so it survives a host that opens a different window.
+columns and rows — see [Chapter 6](06-graphics.md#rgr). Everything below is derived from
+these, including the ball's speed relative to the wall, so the game fits whatever window
+the host opened and whatever font it loaded.
 
-**The cell size is a constant and has to be**, which is the one thing here you cannot
+**The listing in `examples/` still has `CW# = 16` written out**, measured by hand against
-derive. `WINDOW` knows the grid, but the standalone frontend's tee sink never offers it
+the bundled C64_Pro_Mono at 16 points, because when it was written a program had no way
-(`TODO.md` §9 item 3 again), so a program has no way to ask. 16 by 16 is the bundled
+to ask — and it was the one thing in it that would break on a different font. That is
-C64_Pro_Mono at 16 points. Change the font or the point size and change these two with
+what `RGR(3)` and `RWINDOW` are for; `TODO.md` §6 item 31 is the history.
-it; everything below is derived from them, including the ball's speed relative to the
-wall.
 
 Lay the rest of the geometry out in the same block — the wall in cells, the play area in
 pixels:

include/akbasic/sink.h

@@ -61,6 +61,27 @@ typedef struct akbasic_TextSink
      * @return `NULL` on success, otherwise an error context owned by the caller.
      */
     akerr_ErrorContext AKERR_NOIGNORE *(*window)(struct akbasic_TextSink *self, int left, int top, int right, int bottom);
+    /**
+     * Report the character grid, or NULL when the sink has none.
+     *
+     * `RWINDOW` and `RGR(3)`/`RGR(4)` are the callers. Without this a program
+     * had no way to ask how big a character is, so anything placing a character
+     * and a sprite at the same spot had to hardcode a cell size measured against
+     * whatever font the host happened to load -- which the Breakout in
+     * `examples/` did, and it was the one thing in that listing that broke on a
+     * different window.
+     *
+     * Columns and rows are the *current* window, so they follow `window()`;
+     * the cell size does not, because windowing does not change it.
+     *
+     * @param self The sink.
+     * @param columns Output: columns in the current text window.
+     * @param rows Output: rows in it.
+     * @param cellw Output: a character cell's width in pixels.
+     * @param cellh Output: its height in pixels.
+     * @return `NULL` on success, otherwise an error context owned by the caller.
+     */
+    akerr_ErrorContext AKERR_NOIGNORE *(*grid)(struct akbasic_TextSink *self, int *columns, int *rows, int *cellw, int *cellh);
 } akbasic_TextSink;
 
 /** @brief State for the stdio-backed sink. */

src/runtime_console.c

@@ -187,6 +187,65 @@ akerr_ErrorContext *akbasic_cmd_window(akbasic_Runtime *obj, akbasic_ASTLeaf *ex
     SUCCEED_RETURN(errctx);
 }
 
+/* --------------------------------------------------------------- RWINDOW -- */
+
+/**
+ * @brief How big the current text window is, in characters.
+ *
+ * BASIC 7.0's own answer to the question, and it had never been implemented
+ * here: `RWINDOW(0)` is the number of lines and `RWINDOW(1)` the number of
+ * columns. Without it a program had no way to find out, so anything placing a
+ * character *and* a sprite at the same spot had to hardcode a cell size measured
+ * against whatever font the host loaded. The Breakout in `examples/` did exactly
+ * that, and it was the one thing in that listing that broke on a different
+ * window. TODO.md section 6 item 31.
+ *
+ * **`RWINDOW(2)` is refused by name.** On a C128 it answers 0 for 40-column mode
+ * and 1 for 80-column, and this interpreter has no such mode -- the grid is
+ * whatever the window divided by the font gives. Answering 0 would be a
+ * plausible lie, which is worse than a refusal that says why.
+ *
+ * The cell size in pixels is `RGR(3)` and `RGR(4)` rather than a field here: it
+ * is a question about the drawing surface, and it belongs beside the surface's
+ * own dimensions.
+ */
+akerr_ErrorContext *akbasic_fn_rwindow(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Value *out = NULL;
+    double args[1];
+    int count = 0;
+    int field = 0;
+    int columns = 0;
+    int rows = 0;
+    int cellw = 0;
+    int cellh = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in RWINDOW");
+    PASS(errctx, akbasic_args_numbers(obj, expr, "RWINDOW", args, 1, &count));
+    FAIL_ZERO_RETURN(errctx, (count >= 1), AKBASIC_ERR_SYNTAX, "RWINDOW expected a field number");
+    field = (int)args[0];
+
+    FAIL_NONZERO_RETURN(errctx, (field == 2), AKBASIC_ERR_DEVICE,
+			"RWINDOW(2) reports a C128's 40 or 80 column mode, and this interpreter has neither");
+    FAIL_ZERO_RETURN(errctx, (field == 0 || field == 1), AKBASIC_ERR_BOUNDS,
+		     "RWINDOW: field %d is outside 0..1", field);
+    FAIL_ZERO_RETURN(errctx, (obj->sink != NULL), AKBASIC_ERR_DEVICE,
+		     "RWINDOW needs a text device and this runtime has none");
+    FAIL_ZERO_RETURN(errctx, (obj->sink->grid != NULL), AKBASIC_ERR_DEVICE,
+		     "RWINDOW needs a text device with a character grid, and this one has none");
+    PASS(errctx, obj->sink->grid(obj->sink, &columns, &rows, &cellw, &cellh));
+
+    PASS(errctx, akbasic_environment_new_value(obj->environment, &out));
+    PASS(errctx, akbasic_value_zero(out));
+    out->valuetype = AKBASIC_TYPE_INTEGER;
+    out->intval = (field == 0 ? (int64_t)rows : (int64_t)columns);
+    *dest = out;
+    SUCCEED_RETURN(errctx);
+}
+
 /* ---------------------------------------------------------------- service -- */
 
 akerr_ErrorContext *akbasic_console_state_init(akbasic_ConsoleState *obj)

src/runtime_graphics.c

@@ -291,6 +291,10 @@ akerr_ErrorContext *akbasic_fn_rgr(akbasic_Runtime *obj, akbasic_ASTLeaf *expr,
     double args[1];
     int count = 0;
     int field = 0;
+    int columns = 0;
+    int rows = 0;
+    int cellw = 0;
+    int cellh = 0;
     int64_t answer = 0;
 
     (void)lval; (void)rval;
@@ -312,6 +316,9 @@ akerr_ErrorContext *akbasic_fn_rgr(akbasic_Runtime *obj, akbasic_ASTLeaf *expr,
      * is no device -- asking how big the screen is when there is no screen is a
      * program bug worth reporting -- and the refresh that makes the answer
      * current rather than whatever it was at attach.
+     *
+     * Fields 3 and 4 are ours too, and come from the text sink rather than the
+     * graphics device; see the comment on them below.
      */
     switch ( field ) {
     case 0:
@@ -325,8 +332,31 @@ akerr_ErrorContext *akbasic_fn_rgr(akbasic_Runtime *obj, akbasic_ASTLeaf *expr,
 	PASS(errctx, require_graphics(obj, "RGR"));
 	answer = (int64_t)obj->gfx.devheight;
 	break;
+    /*
+     * Fields 3 and 4 are the character cell, in the same pixels fields 1 and 2
+     * are in -- so a program can place a character and a sprite at the same spot
+     * without hardcoding a size measured against the host's font. They come from
+     * the *sink*, which is where a grid lives, and the grid is a text device's
+     * property rather than a graphics one: hence a separate refusal, naming the
+     * text device rather than the graphics one.
+     *
+     * `RWINDOW` answers the other half -- how many columns and rows there are --
+     * and it is the C128's own function for that question. This is here rather
+     * than on RWINDOW because a cell size is a fact about the surface, and
+     * because RWINDOW reports the current *window*, which makes dividing the
+     * surface by the column count wrong the moment a program calls `WINDOW`.
+     */
+    case 3:
+    case 4:
+	FAIL_ZERO_RETURN(errctx, (obj->sink != NULL), AKBASIC_ERR_DEVICE,
+			 "RGR needs a text device and this runtime has none");
+	FAIL_ZERO_RETURN(errctx, (obj->sink->grid != NULL), AKBASIC_ERR_DEVICE,
+			 "RGR needs a text device with a character grid, and this one has none");
+	PASS(errctx, obj->sink->grid(obj->sink, &columns, &rows, &cellw, &cellh));
+	answer = (field == 3 ? (int64_t)cellw : (int64_t)cellh);
+	break;
     default:
-	FAIL_RETURN(errctx, AKBASIC_ERR_BOUNDS, "RGR: field %d is outside 0..2", field);
+	FAIL_RETURN(errctx, AKBASIC_ERR_BOUNDS, "RGR: field %d is outside 0..4", field);
     }
 
     PASS(errctx, akbasic_environment_new_value(obj->environment, &out));

src/sink_akgl.c

@@ -410,6 +410,35 @@ static akerr_ErrorContext *sink_moveto(akbasic_TextSink *self, int col, int row)
  * The full-screen geometry is remembered so a later WINDOW can grow back out;
  * without it each call could only ever shrink.
  */
+/**
+ * @brief Report the character grid, for RWINDOW and RGR.
+ *
+ * The four numbers a program cannot otherwise learn. Columns and rows are the
+ * *current* window rather than the whole screen, which is what RWINDOW means on
+ * a C128 and what a program placing text actually needs; the cell size is
+ * unaffected by windowing, which is what keeps a windowed program's text the
+ * same size as an unwindowed one's.
+ */
+static akerr_ErrorContext *sink_grid(akbasic_TextSink *self, int *columns, int *rows, int *cellw, int *cellh)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_AkglSink *state = NULL;
+
+    FAIL_ZERO_RETURN(errctx, (self != NULL), AKERR_NULLPOINTER, "NULL sink in grid");
+    FAIL_ZERO_RETURN(errctx, (columns != NULL && rows != NULL && cellw != NULL && cellh != NULL),
+		     AKERR_NULLPOINTER, "NULL destination in grid");
+    state = (akbasic_AkglSink *)self->self;
+    FAIL_ZERO_RETURN(errctx, (state != NULL), AKERR_NULLPOINTER, "akgl sink has no state");
+    FAIL_ZERO_RETURN(errctx, (state->cellw > 0 && state->cellh > 0), AKBASIC_ERR_STATE,
+		     "The sink has no character grid to measure");
+
+    *columns = state->columns;
+    *rows = state->rows;
+    *cellw = state->cellw;
+    *cellh = state->cellh;
+    SUCCEED_RETURN(errctx);
+}
+
 static akerr_ErrorContext *sink_window(akbasic_TextSink *self, int left, int top, int right, int bottom)
 {
     PREPARE_ERROR(errctx);
@@ -517,6 +546,7 @@ akerr_ErrorContext *akbasic_sink_init_akgl(akbasic_TextSink *obj, akbasic_AkglSi
     obj->clear = sink_clear;
     obj->moveto = sink_moveto;
     obj->window = sink_window;
+    obj->grid = sink_grid;
     SUCCEED_RETURN(errctx);
 }
 

src/sink_stdio.c

@@ -108,5 +108,6 @@ akerr_ErrorContext *akbasic_sink_init_stdio(akbasic_TextSink *obj, akbasic_Stdio
      */
     obj->moveto = NULL;
     obj->window = NULL;
+    obj->grid = NULL;
     SUCCEED_RETURN(errctx);
 }

src/sink_tee.c

@@ -143,6 +143,30 @@ static akerr_ErrorContext *tee_window(akbasic_TextSink *self, int left, int top,
     SUCCEED_RETURN(errctx);
 }
 
+/**
+ * @brief Report the grid of whichever half has one.
+ *
+ * The first half that answers wins rather than both being consulted, because
+ * there is one grid and only one half can have it -- the same reasoning
+ * tee_moveto() gives about there being one cursor.
+ */
+static akerr_ErrorContext *tee_grid(akbasic_TextSink *self, int *columns, int *rows, int *cellw, int *cellh)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_TeeSink *state = NULL;
+
+    PASS(errctx, tee_state(self, &state));
+    if ( state->primary != NULL && state->primary->grid != NULL ) {
+	PASS(errctx, state->primary->grid(state->primary, columns, rows, cellw, cellh));
+	SUCCEED_RETURN(errctx);
+    }
+    if ( state->mirror != NULL && state->mirror->grid != NULL ) {
+	PASS(errctx, state->mirror->grid(state->mirror, columns, rows, cellw, cellh));
+	SUCCEED_RETURN(errctx);
+    }
+    FAIL_RETURN(errctx, AKBASIC_ERR_STATE, "neither half of this tee has a character grid");
+}
+
 akerr_ErrorContext *akbasic_sink_init_tee(akbasic_TextSink *obj, akbasic_TeeSink *state, akbasic_TextSink *primary, akbasic_TextSink *mirror, akbasic_TextSink *reader)
 {
     PREPARE_ERROR(errctx);
@@ -177,6 +201,7 @@ akerr_ErrorContext *akbasic_sink_init_tee(akbasic_TextSink *obj, akbasic_TeeSink
      */
     obj->moveto = NULL;
     obj->window = NULL;
+    obj->grid = NULL;
     /*
      * Offered only when a half can actually do it, so CHAR's refusal against a
      * stdio-only driver still reads correctly through a tee.
@@ -191,5 +216,10 @@ akerr_ErrorContext *akbasic_sink_init_tee(akbasic_TextSink *obj, akbasic_TeeSink
 	 (mirror != NULL && mirror->window != NULL) ) {
 	obj->window = tee_window;
     }
+    /* And for the grid RWINDOW and RGR read. */
+    if ( (primary != NULL && primary->grid != NULL) ||
+	 (mirror != NULL && mirror->grid != NULL) ) {
+	obj->grid = tee_grid;
+    }
     SUCCEED_RETURN(errctx);
 }

src/verbs.c

@@ -143,6 +143,7 @@ static const akbasic_Verb VERBS[] = {
     { "RSPPOS",       AKBASIC_TOK_FUNCTION,              2, NULL,                  akbasic_fn_rsppos },
     { "RSPRITE",      AKBASIC_TOK_FUNCTION,              2, NULL,                  akbasic_fn_rsprite },
     { "RUN",          AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, NULL,                  akbasic_cmd_run },
+    { "RWINDOW",      AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_rwindow },
     { "SAVE",         AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, NULL,                  akbasic_cmd_dsave },
     { "SCALE",        AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_scale },
     { "SCNCLR",       AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_scnclr },

src/verbs.h

@@ -178,6 +178,7 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_type(struct akbasic_Parser *par
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_type(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_rgr(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_rwindow(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 
 /* Group I sound verbs -- src/runtime_audio.c */
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_envelope(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);

tests/console_verbs.c

@@ -150,6 +150,111 @@ static void test_window_needs_a_grid(void)
     harness_stop();
 }
 
+/*
+ * A grid a stdio sink does not have.
+ *
+ * `RWINDOW` and `RGR(3)`/`RGR(4)` read the sink's grid, and the harness sink is
+ * stdio, which has none -- so without a stand-in the only thing assertable here
+ * is the refusal. This is the akgl sink's shape without the SDL: the runtime
+ * asks through a function pointer and does not care who answers.
+ *
+ * Windowing changes the columns and rows and leaves the cell size alone, which
+ * is the distinction RWINDOW and RGR are split across, so the fake honours it.
+ */
+static int FAKE_COLUMNS = 50;
+static int FAKE_ROWS = 37;
+
+static akerr_ErrorContext AKERR_NOIGNORE *fake_grid(akbasic_TextSink *self, int *columns, int *rows, int *cellw, int *cellh)
+{
+    PREPARE_ERROR(errctx);
+
+    (void)self;
+    FAIL_ZERO_RETURN(errctx, (columns != NULL && rows != NULL && cellw != NULL && cellh != NULL),
+		     AKERR_NULLPOINTER, "NULL destination in fake grid");
+    *columns = FAKE_COLUMNS;
+    *rows = FAKE_ROWS;
+    *cellw = 16;
+    *cellh = 16;
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext AKERR_NOIGNORE *fake_window(akbasic_TextSink *self, int left, int top, int right, int bottom)
+{
+    PREPARE_ERROR(errctx);
+
+    (void)self;
+    FAKE_COLUMNS = (right - left) + 1;
+    FAKE_ROWS = (bottom - top) + 1;
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief `RWINDOW` and the cell-size `RGR` fields report the grid.
+ *
+ * A program had no way to ask how big a character is, so anything placing a
+ * character *and* a sprite at the same spot hardcoded a cell size measured
+ * against whatever font the host loaded. The Breakout in `examples/` did, and it
+ * was the one thing in that listing that broke on a different window. TODO.md
+ * section 6 item 31.
+ */
+static void test_rwindow(void)
+{
+    /* Without a grid, both refuse by name rather than answering something. */
+    TEST_REQUIRE_OK(run_program("10 PRINT RWINDOW(0)\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "character grid") != NULL,
+		 "RWINDOW against a stdio sink should refuse by name, got \"%s\"",
+		 HARNESS_OUTPUT);
+    harness_stop();
+
+    FAKE_COLUMNS = 50;
+    FAKE_ROWS = 37;
+    TEST_REQUIRE_OK(load_program("10 PRINT RWINDOW(0)\n"
+				 "20 PRINT RWINDOW(1)\n"
+				 "30 PRINT RGR(3)\n"
+				 "40 PRINT RGR(4)\n"));
+    HARNESS_SINK.grid = fake_grid;
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 0));
+    /* Rows first: that is RWINDOW's own order on a C128, and it is not obvious. */
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "37\n50\n16\n16\n");
+    harness_stop();
+
+    /* RWINDOW follows a WINDOW; the cell size does not, because windowing does
+       not change how big a character is. */
+    FAKE_COLUMNS = 50;
+    FAKE_ROWS = 37;
+    TEST_REQUIRE_OK(load_program("10 WINDOW 0, 0, 19, 4\n"
+				 "20 PRINT RWINDOW(1)\n"
+				 "30 PRINT RWINDOW(0)\n"
+				 "40 PRINT RGR(3)\n"));
+    HARNESS_SINK.grid = fake_grid;
+    HARNESS_SINK.window = fake_window;
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 0));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "20\n5\n16\n");
+    HARNESS_SINK.window = NULL;
+    harness_stop();
+
+    /*
+     * Field 2 is refused by name. A C128 answers 0 for 40-column mode and 1 for
+     * 80-column; this interpreter has neither, and answering 0 would be a
+     * plausible lie -- which is worse than a refusal that says why.
+     */
+    FAKE_COLUMNS = 50;
+    FAKE_ROWS = 37;
+    TEST_REQUIRE_OK(load_program("10 PRINT RWINDOW(2)\n"));
+    HARNESS_SINK.grid = fake_grid;
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 0));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "40 or 80 column mode") != NULL,
+		 "RWINDOW(2) should be refused by name, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+
+    TEST_REQUIRE_OK(load_program("10 PRINT RWINDOW(7)\n"));
+    HARNESS_SINK.grid = fake_grid;
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 0));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "outside 0..1") != NULL,
+		 "RWINDOW(7) should be out of range, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
 /** @brief TI# counts jiffies and TI$ formats them, both from the host's clock. */
 static void test_ti(void)
 {
@@ -174,6 +279,7 @@ int main(void)
     test_wait();
     test_key();
     test_window_needs_a_grid();
+    test_rwindow();
     test_ti();
     return akbasic_test_failures;
 }

tests/graphics_verbs.c

@@ -266,9 +266,28 @@ static void test_rgr(void)
     TEST_REQUIRE_STR(MOCK.log, "point 639.0,399.0 " WHITE "\n");
     harness_stop();
 
+    TEST_REQUIRE_OK(run_program("10 PRINT RGR(5)\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "outside 0..4") != NULL,
+		 "RGR(5) should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+
+    /*
+     * 3 and 4 are the character cell, and they come from the *sink* rather than
+     * the graphics device -- a grid belongs to a text device. The harness sink
+     * is stdio and has none, so what a device-less build can assert is the
+     * refusal; tests/console_verbs.c drives the answers through a stand-in sink
+     * that does have a grid.
+     */
     TEST_REQUIRE_OK(run_program("10 PRINT RGR(3)\n"));
-    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "outside 0..2") != NULL,
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "text device with a character grid") != NULL,
-		 "RGR(3) should be refused, got \"%s\"", HARNESS_OUTPUT);
+		 "RGR(3) against a grid-less sink should refuse by name, got \"%s\"",
+		 HARNESS_OUTPUT);
+    harness_stop();
+
+    TEST_REQUIRE_OK(run_program("10 PRINT RGR(4)\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "text device with a character grid") != NULL,
+		 "RGR(4) against a grid-less sink should refuse by name, got \"%s\"",
+		 HARNESS_OUTPUT);
     harness_stop();
 
     /*