Files
Ebitor/docs/UPSTREAM_README.md
T

151 lines
5.4 KiB
Markdown

# Ebitor: A reusable text editor C library for 8-bit systems
Ebitor is a C library that implements a bare bones text editor
that can be adapted to work in any terminal. It features text
search and can be extended by the client program.
Copyright © 2021-2025 Pierre Sarrazin <http://sarrazip.com/>
This code comes with ABSOLUTELY NO WARRANTY.
It is recommended to make backups of any files whose contents
are subjected to this editor.
## License: GPLv3
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 <http://www.gnu.org/licenses/>.
See file COPYING.
## Introduction
This is NOT an editor application, it is only a **C library**.
It is intended for programmers who want to integrate a full-screen
editor into their own application.
This library implements a bare bones editor: It has very few features.
More features can be implemented by the client program. They would
typically be invoked by the user by typing the escape key followed by
another key. For example, the Break key followed by A could be used to
put the cursor at the start of the current line.
## Features
- Used as a library, not a program.
- Terminal functions are entirely provided by the client program.
This allows this editor to be used with any terminal type.
- CoCo 32x16, 40x25, 64x25, 80x25 terminal drivers provided.
- OS-9 40- and 80-column driver provided.
The 32-column terminal is not supported.
(The OS-9 version needs the BControl library, available from
the CMOC home page.)
- Does not require dynamic memory allocation.
- Folds lines that are longer than the terminal width.
Does not support non-folding with horizontal scrolling.
- Only one editor can be operated at a given time.
- Should be compiled with the CMOC compiler.
See <http://sarrazip.com/dev/cmoc.html>.
The code assumes a 64k addressable space.
- The only controls provided are moving the cursor with the arrow
keys, and a backspace key to erase the previous character.
Other controls like page-up, page-down and string search must be
implemented by the client program.
The library offers function Ebitor_findStringAndScrollToShow()
to facilitate the latter.
## Building Ebitor
In a Unix-like development environment, do `make` to compile
for the CoCo, or `make TARGET=os9` to compile for OS-9.
See `Makefile` for details.
## Programming for Ebitor
See `smoldemo.c` for a minimal example and `ebitdemo.c` for a
substantial one. To compile these demos, do `make`, then run
`smoldemo.bin` or `ebitdemo.bin` on a CoCo or an emulator.
Either of these demos first #includes header files for one or
more terminal structs, e.g., `sgterm.h` for SG-4 mode (32x16),
`gimeterm.h` for the CoCo 3 text modes, or `os9term.h` for an
OS-9 40- or 80-character terminal.
Then it #includes `Ebitor.h` to use the editor structs and functions.
The demo's first step is to fill an ebitor_Window object that defines
the text window that the editor will use. Then it calls Ebitor's
`sg4term_init()` function, in the case of ,`smoldemo.c` to initialize
the 32x16 screen terminal.
Then `Ebitor_init()` is called to initialize the editor. This call
receives several pointers to several functions that Ebitor will need,
e.g., clearing the terminal, locating the cursor, etc. In the case of
the 32x16 screen, `sg4term_clear` and `sg4term_locate` are passed.
Then the demo enters its main editing loop. This loop must call
`Ebitor_processEditing()`. This function will operate until the user
presses the escape key, typically Break on a CoCo.
Then the editing loop shows a prompt to ask the user what to do after
pressing the escape key. Both demos offer to quit the program or to
show a help page. `ebitdemo.c` also offers to find some text.
If the user presses the escape key again instead of choosing one
of those options, the editing loop just goes back to the call to
`Ebitor_processEditing()`.
When exiting the editor loop, `Ebitor_shutdown()` must be called.
## Porting to other environments
`Ebitor_init()` accepts pointers to functions that handle the
terminal operations needed by the editor. Porting to a different
type of terminal mainly involves writing functions that fill the
same roles, and passing the addresses of those functions to
`Ebitor_init()`.
A good starting point can be to make a copy of sg4term.h and
sg4term.c under new names, then reworking the code for the new
terminal type.
## Memory requirements
The Ebitor library code should take about 5100 bytes in memory under DECB,
but about 5400 under OS-9.
The SG4 (32x16) terminal code (sg4term.c) should take about 1300 bytes.
The GIME (CoCo 3) terminal code (gimeterm.c) should take about 1300 bytes.
The OS-9 terminal code should take about 1000 bytes.
These sizes do not count:
* the text buffer in which the edited text is stored;
* the stack space needed during operation;
* the space that would be used if the assert() statements were enabled
by compiling without NDEBUG.
## Version history
0.1.0 - 2027-07-27 - First public release.