11/**
22 * @file input.h
33 * @author Craig Edwards (craigedwards@brainbox.cc)
4- * @brief Console line input API for Retro Rocket.
5- * @copyright Copyright (c) 2012-2026
4+ * @brief Simple line input API backed by a per-context buffer.
65 *
7- * This interface provides buffered, line-based input for consoles. It handles
8- * character input, backspace editing, line completion detection, and safe
9- * buffer allocation. The functions in this header are backed by the
10- * implementation in @ref input.c.
6+ * Provides minimal, line-based input suitable for BASIC `INPUT` and
7+ * similar use cases. Input is accumulated into a caller-owned context
8+ * and completed when a carriage return is received.
119 *
12- * ## Usage Lifecycle
13- * 1. Call `kinput(maxlen, cons)` repeatedly until it returns `1` (line complete).
14- * 2. Retrieve the full line with `kgetinput(cons)`.
15- * 3. Process the string as needed.
16- * 4. Call `kfreeinput(cons)` when finished to release the internal buffer.
17- *
18- * The buffer is lazily allocated by `kinput()` when the first character arrives,
19- * so you must not call `kgetinput()` until after at least one successful call to
20- * `kinput()`.
10+ * ## Usage
11+ * 1. Initialise with `kinitinput(ctx)`.
12+ * 2. Call `kinput(ctx)` until it returns true (line complete).
13+ * 3. Read the line with `kgetinput(ctx)`.
14+ * 4. Call `kfreeinput(ctx)` when finished.
2115 *
2216 * ## Behaviour
23- * - Input is null-terminated automatically.
24- * - Carriage return (`'\r'`) signals end-of-line and is echoed as newline (`'\n'`).
25- * - Backspace (`8`) removes the previous character (with console cursor handling).
26- * - Arrow keys (↑ ↓ ← →) are recognised but ignored.
27- * - If the buffer limit is reached, no more characters are added and a beep is
28- * emitted as feedback.
29- *
30- * @note This input API is retained primarily to support the BASIC INPUT
31- * statement and similar minimal line-reading requirements. Modern
32- * interactive shells and tools use the ANSI console library, which
33- * provides line editing, history, and richer input handling.
17+ * - Input is null-terminated.
18+ * - `'\r'` completes the line and is echoed as `'\n'`.
19+ * - Backspace (`8`) deletes the previous character with cursor update.
20+ * - Arrow keys are ignored.
21+ * - Buffer grows dynamically as needed.
3422 *
35- * `kinput()` is intentionally simple and blocking; it does not support
36- * advanced editing or multiple input sources .
23+ * @note This API is polled and intended for cooperative scheduling.
24+ * It performs no advanced line editing .
3725 */
3826
3927#pragma once
4028
29+ struct basic_ctx ;
30+
4131/**
42- * @brief Poll for a single character of input from the console .
32+ * @brief Per- input context state .
4333 *
44- * This function reads a single character from the console associated
45- * with the specified process, storing it in the input buffer.
46- *
47- * When the user completes a line (e.g. by pressing Enter), the function
48- * returns 1 to indicate the input line is ready for retrieval.
49- * Until then, it returns 0, allowing the caller to yield or retry later.
34+ * Stores the buffer and cursor state for a single line input operation.
35+ */
36+ typedef struct buffered_input_context_t {
37+ bool stopped ; /**< Line completion flag */
38+ uint8_t last ; /**< Last character read */
39+ char * internalbuffer ; /**< Base pointer to allocated buffer */
40+ char * buffer ; /**< Current write pointer */
41+ size_t bufcnt ; /**< Number of characters in buffer */
42+ size_t buflen ; /**< Allocated buffer size */
43+ } buffered_input_context_t ;
44+
45+ /**
46+ * @brief Initialise an input context.
5047 *
51- * @note This function is typically called repeatedly inside a loop or
52- * idle callback, until a full line of input is received.
48+ * Clears all state. Must be called before first use.
5349 *
54- * @param maxlen Maximum length of the input line.
55- * @param cons Console to read input from.
56- * @return 1 if a full line is available, 0 otherwise.
50+ * @param ctx Input context
5751 */
58- size_t kinput ( size_t maxlen );
52+ void kinitinput ( struct buffered_input_context_t * ctx );
5953
6054/**
61- * @brief Free the internal input buffer associated with a console.
55+ * @brief Poll for input and update the buffer.
56+ *
57+ * Reads a single character and updates the context buffer.
6258 *
63- * This function releases the memory used to store a pending line of
64- * input for the specified console. It should be called after input
65- * has been processed, to prevent memory leaks and prepare the console
66- * for the next `kinput()` cycle.
59+ * @param basic BASIC context
60+ * @param ctx Input context
61+ * @return true if a full line has been entered, false otherwise
62+ */
63+ bool kinput (struct basic_ctx * basic , struct buffered_input_context_t * ctx );
64+
65+ /**
66+ * @brief Free any allocated input buffer and reset the context.
6767 *
68- * @param cons Console whose input buffer should be freed.
68+ * @param basic BASIC context
69+ * @param ctx Input context
6970 */
70- void kfreeinput ();
71+ void kfreeinput (struct basic_ctx * basic , struct buffered_input_context_t * ctx );
7172
7273/**
73- * @brief Retrieve the accumulated input string for a console .
74+ * @brief Get the current input buffer .
7475 *
75- * @param cons Pointer to the console.
76- * @return Pointer to the null-terminated input string, or NULL if no buffer exists.
76+ * @param ctx Input context
77+ * @return Pointer to null-terminated string, or NULL if not initialised
7778 *
78- * @warning Do not free the returned pointer directly; use @ref kfreeinput().
79+ * @warning Do not free the returned pointer directly
7980 */
80- char * kgetinput ();
81+ const char * kgetinput (struct buffered_input_context_t * ctx );
0 commit comments