summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorBerke Güzel <wenekar1@gmail.com>2026-10-15 13:04:01 +0300
committerBerke Güzel <wenekar1@gmail.com>2026-10-15 13:04:01 +0300
commitdcebf9c7f954a55350b68d0ead1935612c4e2e05 (patch)
tree3eb3e9f6154c6760bcb89a565f8ddc8f8b66cb90 /README.md
parentbd8222e615134c3ec5e7a07b6b1fa97c9bd4a471 (diff)
Rename the library to wsap_vtcore
ncurses installs <term.h> and defines struct term. In a file that includes both headers, an ncurses TERMINAL * and this library's terminal are silently the same type. The name wsap_vtcore avoids the clash. The public header is now <wsap_vtcore/wsap_vtcore.h>. Every global symbol uses the wsap_vtcore_ prefix, every macro uses WSAP_VTCORE_, and the shared library is libwsap_vtcore.so.0. The default terminal name is now "wsap_vtcore". The ISA override variable is WSAP_VTCORE_ISA. No other behavior changes. The amalgamation writes wsap_vtcore.c and wsap_vtcore.h. Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Diffstat (limited to 'README.md')
-rw-r--r--README.md77
1 files changed, 39 insertions, 38 deletions
diff --git a/README.md b/README.md
index c77883a..01db1a3 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,13 @@
-# term
+# wsap_vtcore
-term is a headless terminal core: the parser, screen ring, logical-line
-history store, write core, and viewport snapshots. It is a C11 library
-with no dependency but libm and, on POSIX, the thread library (`-pthread`).
+wsap_vtcore is a headless terminal core: the parser, screen ring,
+logical-line history store, write core, and viewport snapshots. It is a C11
+library with no dependency but libm and, on POSIX, the thread library
+(`-pthread`).
| Path | Contents |
| --- | --- |
-| `include/term/` | The public headers: `term.h`, and the header-only `unicode/` |
+| `include/wsap_vtcore/` | The public headers: `wsap_vtcore.h`, and the header-only `unicode/` |
| `src/` | The core. Its headers are private. |
| `tests/` | Unit, model, fuzz, and portability tests, and the Kitty parser suite |
| `benchmarks/` | `term-write-bench`, `term-resize-bench`, and `hist-bench` |
@@ -18,20 +19,20 @@ with no dependency but libm and, on POSIX, the thread library (`-pthread`).
Pick one of these:
-- **Meson subproject**: `dependency('term')`, or
- `subproject('term').get_variable('term_dep')`. The `arch_flag` option
- sets the lowest instruction set, such as `-march=x86-64-v3`.
+- **Meson subproject**: `dependency('wsap_vtcore')`, or
+ `subproject('wsap_vtcore').get_variable('wsap_vtcore_dep')`. The `arch_flag`
+ option sets the lowest instruction set, such as `-march=x86-64-v3`.
- **Amalgamation**: run `tools/amalgamate.py . OUT`. It writes
- `OUT/term.c` and `OUT/term.h`. Compile `term.c` with any C11 compiler
- and link libm and the thread library: `cc -std=c11 -pthread -c term.c`
- on POSIX. A Rust `build.rs` needs one
- `cc::Build::new().file("term.c").compile("term")`.
+ `OUT/wsap_vtcore.c` and `OUT/wsap_vtcore.h`. Compile `wsap_vtcore.c` with any
+ C11 compiler and link libm and the thread library:
+ `cc -std=c11 -pthread -c wsap_vtcore.c` on POSIX. A Rust `build.rs` needs one
+ `cc::Build::new().file("wsap_vtcore.c").compile("wsap_vtcore")`.
- **Sources**: compile `src/*.c` and `src/osc/*.c` once, with `src` and
- `include/term` on the include path. Link the thread library too.
+ `include/wsap_vtcore` on the include path. Link the thread library too.
The library needs nothing else. On Windows the writer lock is an SRWLOCK
from the system library, so it needs no extra link. The `*-amalgamation`
-tests run the term tests against the generated `term.c`, and
+tests run the wsap_vtcore tests against the generated `wsap_vtcore.c`, and
`term-cross-test` compiles it for aarch64, macOS, and Windows.
### SIMD level
@@ -41,10 +42,10 @@ scroll and line-feed output runs 8 to 30 times slower. The build needs
no flags to get them:
- On x86-64 with GCC or Clang, each kernel compiles at every level with
- a target attribute. The first `term_new()` picks the highest level the
+ a target attribute. The first `wsap_vtcore_new()` picks the highest level the
CPU supports. The levels are `base` (x86-64), `avx2` (x86-64-v3), and
- `avx512` (x86-64-v4 with VBMI and VBMI2). `term_isa()` names the level
- in use. Set `TERM_HEADLESS_ISA` to a lower level to force it.
+ `avx512` (x86-64-v4 with VBMI and VBMI2). `wsap_vtcore_isa()` names the level
+ in use. Set `WSAP_VTCORE_ISA` to a lower level to force it.
- `-march` sets the lowest level. The checks for that level and below
become constants, and their kernels inline into their callers.
- aarch64 always has NEON, so it needs no choice at run time.
@@ -52,31 +53,31 @@ no flags to get them:
`simd.h` states the rules for a new kernel.
-- `term.h` is the only header a host includes. A host writes
- `#include <term/term.h>`. The package adds only the include directory,
- so `term.h` from another library, such as ncurses, is not shadowed. The
- header includes `term_input.h` and `term_types.h`. It compiles as C11
- and as C++.
-- Every global symbol starts with `term_`. The library builds with hidden
- symbols, so a shared build exports only the `TERM_API` functions of
- `term.h`. `term-symbols-test` checks both.
+- `wsap_vtcore.h` is the only header a host includes. A host writes
+ `#include <wsap_vtcore/wsap_vtcore.h>`. The package adds only the include
+ directory, so `wsap_vtcore.h` from another library, such as ncurses, is not
+ shadowed. The header includes `wsap_vtcore_input.h` and
+ `wsap_vtcore_types.h`. It compiles as C11 and as C++.
+- Every global symbol starts with `wsap_vtcore_`. The library builds with hidden
+ symbols, so a shared build exports only the `WSAP_VTCORE_API` functions of
+ `wsap_vtcore.h`. `term-symbols-test` checks both.
- Any thread can call any function. Calls on one terminal run one at a
- time. `term.h` states the rules.
-- The `static inline` helpers (`term_color_*`, `term_view_color`,
- `term_attr_underline`) only decode documented bit layouts. A binding
+ time. `wsap_vtcore.h` states the rules.
+- The `static inline` helpers (`wsap_vtcore_color_*`, `wsap_vtcore_view_color`,
+ `wsap_vtcore_attr_underline`) only decode documented bit layouts. A binding
generator such as bindgen skips them. Mirror them in the binding, or
use the generator's static-function wrappers.
A host wires the terminal in four places:
-1. Create it with `term_new()`. Set `term_options.callbacks.reply` to
- send replies to the program. Set `term_options.name` to the name
- programs read with XTVERSION and XTGETTCAP. It defaults to `term`.
-2. Feed program output with `term_feed()`.
-3. Translate key and mouse events into `struct term_key_event` and
- `struct term_mouse_event`. Encode them with `term_input_encode_key()`
- and `term_input_encode_mouse()`, and send the bytes to the program.
-4. Paint from a `struct term_snapshot`. The terminal gives code points,
+1. Create it with `wsap_vtcore_new()`. Set `wsap_vtcore_options.callbacks.reply` to
+ send replies to the program. Set `wsap_vtcore_options.name` to the name
+ programs read with XTVERSION and XTGETTCAP. It defaults to `wsap_vtcore`.
+2. Feed program output with `wsap_vtcore_feed()`.
+3. Translate key and mouse events into `struct wsap_vtcore_key_event` and
+ `struct wsap_vtcore_mouse_event`. Encode them with `wsap_vtcore_input_encode_key()`
+ and `wsap_vtcore_input_encode_mouse()`, and send the bytes to the program.
+4. Paint from a `struct wsap_vtcore_snapshot`. The terminal gives code points,
colors, and attributes. The host shapes and draws the glyphs.
## Files and responsibilities
@@ -138,11 +139,11 @@ Snapshot capture makes the counts exact for lines in the view.
Counts above 254 rows use a separate cache.
That cache grows only when a visited line needs it.
-`term_snapshot_update` takes a mutable terminal.
+`wsap_vtcore_snapshot_update` takes a mutable terminal.
It updates history query metadata before it copies the view.
Snapshot getters and history getters do not change terminal state.
Renderers do not read terminal memory directly. Renderers read an
-immutable snapshot (`struct term_snapshot`).
+immutable snapshot (`struct wsap_vtcore_snapshot`).
Snapshots track row keys based on row content identities.
When output scrolls, snapshots detect the scroll distance `k`.
Renderers shift existing pixels and draw records by `k` rows and paint