/* Ebitor.h Copyright (C) 2021-2025 Pierre Sarrazin This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . */ #ifndef _H_Ebitor #define _H_Ebitor #ifdef _CMOC_VERSION_ /* If compiling with CMOC. */ #include #else /* To compile with GCC (useful to get more warnings). */ #include #include #include typedef uint8_t byte; typedef uint16_t word; typedef uint8_t BOOL; enum { FALSE, TRUE }; void *memichr(const void *s, int c, size_t n); int memicmp(const void *s1, const void *s2, size_t n); #endif // Control codes, >= 256. // Characters in 32..126 and 128..255 are assumed to be printable. // enum { ebitor_KEY_ARROW_LEFT = 256, ebitor_KEY_ARROW_RIGHT, ebitor_KEY_ARROW_UP, ebitor_KEY_ARROW_DOWN, ebitor_KEY_ESCAPE, }; struct Ebitor; // Clear the entire terminal. // Does not move the cursor. // typedef void (*ebitor_clear)(void); // Position the terminal's cursor. // column, row: Start at 0. // typedef void (*ebitor_locateFunc)(byte column, byte row); // Obtains the current position of the terminal's cursor. // *column, *row: Will start at 0. // typedef void (*ebitor_getCursorPosFunc)(byte *column, byte *row); // Prints an ASCIIZ to the terminal. // Character '\r' does a carriage return and line feed AND clears // the rest of the row it is applied to (with spaces). // Returns FALSE if the printing reached the end of the terminal. // In this case, the cursor can be assumed to be at the first // position of the last row of the window. // typedef BOOL (*ebitor_printFunc)(const char *str); // Prints a given number of characters to the terminal. // Character '\r' does a carriage return and line feed AND clears // the rest of the row it is applied to (with spaces). // No other control code is supported. // Returns FALSE if the printing reached the end of the terminal. // typedef BOOL (*ebitor_printPrefixFunc)(const char *str, size_t prefixLength); // Clears the current terminal line from the cursor position to the end of the terminal line. // Does not move the terminal's cursor. // typedef void (*ebitor_clrtoeolFunc)(void); // Moves the contents of the terminal up by the given number of rows. // Fills the bottom row(s) of the terminal with spaces. // Does not move the terminal's cursor. // typedef void (*ebitor_scrollTerminalUpFunc)(byte numRows); // Moves the contents of the terminal down by the given number of rows. // Fills the top row(s) of the terminal with spaces. // Does not move the terminal's cursor. // typedef void (*ebitor_scrollTerminalDownFunc)(byte numRows); // Blocks while waiting for a key press on the terminal. // Returns a printable character, or a control character (e.g., '\b', '\r') or // a control code (see the ebitor_KEY_* enum). // typedef word (*ebitor_waitKeyFunc)(void); enum { INSERT_BUFFER_SIZE = 64, // Must be >= 2. }; typedef struct InsertBuffer { char buffer[INSERT_BUFFER_SIZE]; size_t size; // prefix of buffer[] that is filled } InsertBuffer; typedef struct Ebitor { byte termWidth; // number of columns of the terminal (all the columns used) byte termHeight; // number of rows of the terminal (all the rows are used) char *bufferBegin; char *bufferEnd; size_t bufferFilledSize; // prefix of [bufferBegin, bufferEnd) that is filled size_t cursorOffset; // in [bufferBegin, bufferEnd); does not count the chars in insertBuffer byte savedCursorCol; // cursor column when editing stopped byte savedCursorRow; // cursor row when editing stopped byte mode; // MODE_* enum value InsertBuffer insertBuffer; // Terminal-specific functions. ebitor_clear clear; ebitor_locateFunc locate; ebitor_printFunc print; ebitor_printPrefixFunc printPrefix; ebitor_clrtoeolFunc clrtoeol; ebitor_scrollTerminalUpFunc scrollTerminalUp; ebitor_scrollTerminalDownFunc scrollTerminalDown; ebitor_waitKeyFunc waitKey; ebitor_getCursorPosFunc getCursorPos; } Ebitor; // termWidth: Number of columns of the terminal (all the columns are used). // termHeight: Number of rows of the terminal (all the rows are used). // See the comments above concerning the behavior expected of the callbacks. // void Ebitor_init(char *bufferBegin, size_t bufferSize, byte termWidth, byte termHeight, ebitor_clear clear, ebitor_locateFunc locate, ebitor_getCursorPosFunc getCursorPos, ebitor_printFunc print, ebitor_printPrefixFunc printPrefix, ebitor_clrtoeolFunc clrtoeol, ebitor_scrollTerminalUpFunc scrollTerminalUp, ebitor_scrollTerminalDownFunc scrollTerminalDown, ebitor_waitKeyFunc waitKey); // Return the address of the lone instance of struct Ebitor. // Should be used only for self-testing code and/or debugging. // Ebitor *Ebitor_getInstance(void); // Tells the editor how much text is currently in its buffer. // Typically called after filling the buffer passed to Ebitor_init() // from a file. // Also puts the cursor at the beginning. // newLength: Must not exceed the bufferSize parameter passed // to Ebitor_init(). // void Ebitor_setContentLength(size_t newLength); size_t Ebitor_getContentLength(void); // Processes the user's keyboard commands to edit the text. // Invokes the callbacks given to Ebitor_init(). // Saves the terminal cursor position upon exiting. // The next call will start by restoring the terminal cursor to the saved position. // Other functions can affect the saved position, e.g., Ebitor_findStringAndScrollToShow(). // startWithRefresh: Start by filling the terminal with what is currently supposed to appear, // depending on the position of the logical cursor and of the terminal cursor. // void Ebitor_processEditing(BOOL startWithRefresh); // Processes the given key as if it had been typed by the user. // // key: Must be a printable character or an ebitor_KEY_* value, but NOT ebitor_KEY_ESCAPE. // // Ebitor_locateCursorAtSavedPosition() must be called before calling this function; // then, this function can be called one or more times; when this sequence of calls // is done, Ebitor_saveCursorPosition() must be called. // void Ebitor_processKey(word key); // Simulate a user pressing the up or down arrow multiple times, then refreshes the terminal. // When the number of repetitions is large, this function is more efficient than calling // Ebitor_processKey() multiple times, because the terminal would get updated with each call // to Ebitor_processKey(). // isUpArrow: TRUE to simulate an up arrow key, FALSE for a down arrow. // numRepetitions: The number of times to repeat the specified arrow key. // Allowed to be zero. // void Ebitor_processUpOrDownArrowsAndRefresh(BOOL isUpArrow, size_t numRepetitions); // Remembers the current position of the cursor. // The cursor can later be restored to that position by a call to Ebitor_locateCursorAtSavedPosition(). // void Ebitor_saveCursorPosition(void); // Puts the cursor at the position saved by the most recent call to Ebitor_saveCursorPosition(). // The latter must have been called at least once. // void Ebitor_locateCursorAtSavedPosition(void); size_t Ebitor_getLogicalCursorOffset(void); // Determines which logical offset is currently at position (0, 0) on the terminal. // size_t Ebitor_getLogicalOffsetAtHome(byte cursorCol, byte cursorRow); // Also puts the terminal cursor at the home position. // void Ebitor_setLogicalCursorAtBeginning(void); // Searches for the string in strSearchedFor and if found, scrolls the terminal and // positions the cursor so that the the found string is visible. // If the string is not found, the terminal is not scrolled and the cursor is not moved. // startLogicalOffset: Position in the text where to start the search. // strSearchedFor: Non empty, NUL-terminated. // foundLogicalOffset: (Must not be null.) Receives the logical position where the string // was found, if TRUE is returned. Not filled if FALSE is returned. // Returns TRUE if found, FALSE if not. // BOOL Ebitor_findStringAndScrollToShow(size_t startLogicalOffset, const char *strSearchedFor, size_t *foundLogicalOffset); // Locates the terminal cursor at the terminal location equivalent to logicalOffsetToShow. // Makes this terminal cursor the currently saved one. // Scrolls enough to make sure that 'lengthToShow' characters from logicalOffsetToShow // are visible in the terminal. // lengthToShow is allowed to be zero. // This saved position will be used by the next call to Ebitor_processEditing(). // Puts the logical cursor at logicalOffsetToShow. // Scrolls and/or redraws lines as necessary. // void Ebitor_scrollToShowLogicalOffset(size_t logicalOffsetToShow, size_t lengthToShow); // Returns the offset of the start of the line that contains the given offset. // size_t Ebitor_findSOL(size_t startOffset); // Returns the offset of the end-of-line delimiter of the line that contains the given offset. // If the current line is the last one and has no such delimiter, then the length of the // filled buffer is returned. // size_t Ebitor_findEOL(size_t startOffset); void Ebitor_shutdown(void); #endif /* _H_Ebitor */