akbasic/include/akbasic/sink.h

/**
 * @file sink.h
 * @brief Declares the text sink: where PRINT goes and where INPUT comes from.
 *
 * The reference's Write() and Println() mirror every line to stdout *and* to an
 * SDL surface, and that mirror is the only reason its golden-file suite works.
 * Reproducing it as a hardcoded pair of calls would drag SDL into the core and
 * make the corpus unrunnable without a display, so it becomes a record of
 * function pointers instead -- the house pattern for anything that varies.
 *
 * akbasic_sink_init_stdio() is in the library. akbasic_sink_init_akgl() is in the
 * separate akbasic_akgl target and draws through whatever renderer the host game
 * already initialized; the interpreter never owns a window.
 */

#ifndef _AKBASIC_SINK_H_
#define _AKBASIC_SINK_H_

#include <stdio.h>

#include <akerror.h>

#include <akbasic/types.h>

typedef struct akbasic_TextSink
{
    void *self;
    akerr_ErrorContext AKERR_NOIGNORE *(*write)(struct akbasic_TextSink *self, const char *text);
    akerr_ErrorContext AKERR_NOIGNORE *(*writeln)(struct akbasic_TextSink *self, const char *text);
    /**
     * Read one line. Sets *eof true at end of input rather than raising, because
     * running off the end of a stream is how RUNSTREAM mode finishes normally.
     */
    akerr_ErrorContext AKERR_NOIGNORE *(*readline)(struct akbasic_TextSink *self, char *dest, size_t len, bool *eof);
    akerr_ErrorContext AKERR_NOIGNORE *(*clear)(struct akbasic_TextSink *self);
    /**
     * Put the cursor at a character cell, or NULL when the sink has no cursor.
     *
     * `CHAR` is the only verb that needs it, and a stdio sink genuinely cannot
     * do it -- a terminal's cursor is not this library's to move, and a pipe has
     * no cursor at all. So it is optional, like the audio backend's `sweep`, and
     * `CHAR` refuses by name against a sink that leaves it NULL rather than
     * printing in the wrong place.
     *
     * @param self The sink.
     * @param col Zero-based column.
     * @param row Zero-based row.
     * @return `NULL` on success, otherwise an error context owned by the caller.
     */
    akerr_ErrorContext AKERR_NOIGNORE *(*moveto)(struct akbasic_TextSink *self, int col, int row);
    /**
     * Constrain the sink to a rectangle of character cells, or NULL when it has
     * no grid to constrain. `WINDOW` is the only caller. Coordinates are
     * inclusive, as BASIC 7.0 writes them.
     *
     * @param self The sink.
     * @param left Leftmost column, zero-based.
     * @param top Topmost row, zero-based.
     * @param right Rightmost column, inclusive.
     * @param bottom Bottommost row, inclusive.
     * @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);
    /**
     * Select how this sink's text plane participates in a GRAPHIC display mode.
     *
     * This is optional: a stream has no display plane to hide or split, so the
     * stdio sink leaves it NULL. A graphical sink receives the mode after the
     * runtime has validated it. @p split is the first text row for a split mode,
     * or -1 when BASIC used the C128 default.
     *
     * @param self The sink.
     * @param mode BASIC 7.0 GRAPHIC mode.
     * @param split First text row for a split screen, or -1 for the default.
     * @return `NULL` on success, otherwise an error context owned by the caller.
     */
    akerr_ErrorContext AKERR_NOIGNORE *(*graphic)(struct akbasic_TextSink *self, int mode, int split);
} akbasic_TextSink;

/** @brief State for the stdio-backed sink. */
typedef struct
{
    FILE *out;
    FILE *in;
} akbasic_StdioSink;

/**
 * @brief Point a sink at a pair of stdio streams.
 * @param obj Object to initialize, inspect, or modify.
 * @param state Storage for the stream pair; must outlive the sink.
 * @param out Where write/writeln go; NULL selects stdout.
 * @param in Where readline reads; NULL selects stdin.
 */
akerr_ErrorContext AKERR_NOIGNORE *akbasic_sink_init_stdio(akbasic_TextSink *obj, akbasic_StdioSink *state, FILE *out, FILE *in);

/**
 * @brief State for a sink that writes to two others.
 *
 * The reference mirrors every line to stdout *and* to its SDL surface, and that
 * mirror is what makes the golden corpus runnable. Reproducing it as a second
 * hardcoded write inside the interpreter is exactly what the sink boundary
 * exists to prevent, so the composition lives out here instead: two sinks in,
 * one sink out, and the interpreter still only knows about one.
 */
typedef struct
{
    akbasic_TextSink *primary;
    akbasic_TextSink *mirror;
    akbasic_TextSink *reader;
} akbasic_TeeSink;

/**
 * @brief Compose two sinks into one that writes to both.
 *
 * Writes go to @p primary first and then to @p mirror; an error from either one
 * stops the pair, so a failed write is never half-reported.
 *
 * @p reader says which of the two answers readline, because only one of them can
 * and the answer is not derivable. A file-mode driver reads its program from the
 * stdio half while drawing through the akgl half; an interactive one reads from
 * the akgl line editor and mirrors to stdout. Passing NULL makes readline report
 * end of input, which is the honest answer for a pair that has no input.
 *
 * @param obj Object to initialize, inspect, or modify.
 * @param state Storage for the three pointers; must outlive the sink.
 * @param primary The sink written first; must not be NULL.
 * @param mirror The sink written second; must not be NULL.
 * @param reader Whichever of the two supplies readline, or NULL for none.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_NULLPOINTER When `obj`, `state`, `primary` or `mirror` is NULL.
 * @throws AKBASIC_ERR_VALUE When `reader` is neither `primary` nor `mirror`.
 */
akerr_ErrorContext AKERR_NOIGNORE *akbasic_sink_init_tee(akbasic_TextSink *obj, akbasic_TeeSink *state, akbasic_TextSink *primary, akbasic_TextSink *mirror, akbasic_TextSink *reader);

#endif // _AKBASIC_SINK_H_