linenoise.c 1.2025.9 → 2.2026.1

package/{README.markdown → README.md}

@@ -1,38 +1,17 @@
 # Linenoise
 
 A minimal, zero-config, BSD licensed, readline replacement used in Redis,
-MongoDB, Android and many other projects. By [Salvatore Sanfilippo](https://github.com/antirez).
+MongoDB, Android and many other projects.
 
 * Single and multi line editing mode with the usual key bindings implemented.
 * History handling.
 * Completion.
 * Hints (suggestions at the right of the prompt as you type).
 * Multiplexing mode, with prompt hiding/restoring for asynchronous output.
-* About ~850 lines (comments and spaces excluded) of BSD license source code.
+* UTF-8 support for multi-byte characters and emoji.
+* About ~1100 lines (comments and spaces excluded) of BSD license source code.
 * Only uses a subset of VT100 escapes (ANSI.SYS compatible).
 
-## Installation
-
-Run:
-```bash
-$ npm i linenoise.c
-```
-
-And then include `linenoise.h` as follows:
-```c
-#include "node_modules/linenoise.c/linenoise.h"
-```
-
-You may also want to include `linenoise.c` as follows:
-```c
-#ifndef __LINENOISE_C__
-#define __LINENOISE_C__
-#include "node_modules/linenoise.c/linenoise.c"
-#endif
-```
-
-This will include both the function declaration and their definitions into a single file.
-
 ## Can a line editing library be 20k lines of code?
 
 Line editing with some support for history is a really important feature for command line utilities. Instead of retyping almost the same stuff again and again it's just much better to hit the up arrow and edit on syntax errors, or in order to try a slightly different command. But apparently code dealing with terminals is some sort of Black Magic: readline is 30k lines of code, libedit 20k. Is it reasonable to link small utilities to huge libraries just to get a minimal support for line editing?
@@ -41,7 +20,7 @@ So what usually happens is either:
 
  * Large programs with configure scripts disabling line editing if readline is not present in the system, or not supporting it at all since readline is GPL licensed and libedit (the BSD clone) is not as known and available as readline is (real world example of this problem: Tclsh).
  * Smaller programs not using a configure script not supporting line editing at all (A problem we had with `redis-cli`, for instance).
- 
+
 The result is a pollution of binaries without line editing support.
 
 So I spent more or less two hours doing a reality check resulting in this little library: is it *really* needed for a line editing library to be 20k lines of code? Apparently not, it is possibe to get a very small, zero configuration, trivial to embed library, that solves the problem. Smaller programs will just include this, supporting line editing out of the box. Larger programs may use this little library or just checking with configure if readline/libedit is available and resorting to Linenoise if not.
@@ -78,6 +57,48 @@ easy to understand code.
 
 Send feedbacks to antirez at gmail
 
+
+# Installation
+
+Run:
+
+```sh
+$ npm i linenoise.c
+```
+
+And then include `linenoise.h` as follows:
+
+```c
+// main.c
+#include "node_modules/linenoise.c/linenoise.h"
+
+int main() { /* ... */ }
+```
+
+And then compile with `clang` or `gcc` as usual.
+
+```bash
+$ clang main.c  # or, use gcc
+$ gcc   main.c
+```
+
+You may also use a simpler approach:
+
+```c
+// main.c
+#include <linenoise.h>
+
+int main() { /* ... */ }
+```
+
+If you add the path `node_modules/linenoise.c` to your compiler's include paths.
+
+```bash
+$ clang -I./node_modules/linenoise.c main.c  # or, use gcc
+$ gcc   -I./node_modules/linenoise.c main.c
+```
+
+
 # The API
 
 Linenoise is very easy to use, and reading the example shipped with the
@@ -155,7 +176,7 @@ just that. Both functions return -1 on error and 0 on success.
 
 Sometimes it is useful to allow the user to type passwords or other
 secrets that should not be displayed. For such situations linenoise supports
-a "mask mode" that will just replace the characters the user is typing 
+a "mask mode" that will just replace the characters the user is typing
 with `*` characters, like in the following example:
 
     $ ./linenoise_example
@@ -363,14 +384,47 @@ example using select(2) and the asynchronous API:
 
 You can test the example by running the example program with the `--async` option.
 
+## Running the tests
+
+To run the test suite:
+
+    make test
+
+The tests will display a virtual terminal showing linenoise output in real-time, making it easy to see what's being tested and debug any failures.
+
+### What the tests cover
+
+The test suite verifies:
+
+* Basic typing and cursor movement (left, right, home, end)
+* Backspace and delete operations
+* UTF-8 multi-byte characters (accented letters, CJK)
+* Emoji and grapheme clusters (skin tones, ZWJ sequences like flags)
+* Horizontal scrolling for long lines
+* Multiline mode editing and navigation
+* History navigation in multiline mode
+* Word and line deletion (Ctrl-W, Ctrl-U)
+
+### How the test harness works
+
+The test program (`linenoise-test.c`) implements a VT100 terminal emulator that captures and verifies linenoise output:
+
+1. **Fork and pipes**: The test harness forks `linenoise-example`, connecting to it via pipes. The child process sees `LINENOISE_ASSUME_TTY=1` to enable terminal mode despite not having a real TTY.
+2. **VT100 emulator**: A minimal VT100 emulator parses escape sequences (cursor movement, screen clearing, etc.) and maintains a virtual screen buffer. Each cell stores a complete UTF-8 grapheme cluster and its display width.
+3. **Visual rendering**: After each operation, the virtual screen is rendered to your real terminal with a border, so you can watch the test execute and see exactly what linenoise is displaying.
+4. **Assertions**: Tests verify screen contents and cursor position against expected values.
+
+This approach tests linenoise as users actually experience it, catching rendering bugs that unit tests would miss.
+
 ## Related projects
 
-* [Linenoise NG](https://github.com/arangodb/linenoise-ng) is a fork of Linenoise that aims to add more advanced features like UTF-8 support, Windows support and other features. Uses C++ instead of C as development language.
+* [Linenoise NG](https://github.com/arangodb/linenoise-ng) is a fork of Linenoise that aims to add more advanced features like Windows support and other features. Uses C++ instead of C as development language.
 * [Linenoise-swift](https://github.com/andybest/linenoise-swift) is a reimplementation of Linenoise written in Swift.
 
 <br>
 <br>
 
 
+[![SRC](https://img.shields.io/badge/src-repo-green?logo=Org)](https://github.com/antirez/linenoise)
 [![ORG](https://img.shields.io/badge/org-nodef-green?logo=Org)](https://nodef.github.io)
 ![](https://ga-beacon.deno.dev/G-RC63DPBH3P:SH3Eq-NoQ9mwgYeHWxu7cw/github.com/nodef/linenoise.c)