Line Editing
LineReader reads user input with line editing for REPLs and interactive command-line programs. The same code runs on the JVM, as a Scala Native binary, and on Node.js.
It provides:
- Emacs-style editing (Ctrl-A/E, Ctrl-K/U/W/Y, Alt-B/F, arrows, Home/End)
- History with Up/Down, Ctrl-P/N, and reverse search (Ctrl-R), saved to a file
- Tab completion
- Syntax highlighting with Tint
- Multi-line input, e.g., until a statement ends with
; - Custom key bindings, including chords such as Ctrl-J Ctrl-R
- Bracketed paste, so pasted multi-line text stays in one input
- Wide characters (CJK, emoji) and long lines that wrap
Basic Usage
import wvlet.uni.cli.*
val reader = LineReader(
LineReaderConfig()
.withHistoryFile(".my_history")
.withCompleter(Completer.words(Seq("select", "from", "where")))
.withHighlighter(_.replace("select", Tint.cyan("select")))
.withInputComplete(_.trim.endsWith(";"))
.withContinuationPrompt(" | ")
)
// The same loop on every platform
def loop(reader: LineReader): Rx[Unit] = reader
.readLine("> ")
.flatMap {
case LineResult.Line("exit") | LineResult.EndOfInput =>
Rx.single(())
case LineResult.Line(text) =>
println(s"input: ${text}")
loop(reader)
case LineResult.Interrupted(_) =>
loop(reader)
}
loop(reader).run()readLine returns an Rx[LineResult] that completes when the user presses Enter (Line), Ctrl-C (Interrupted), or Ctrl-D on an empty line (EndOfInput). Chaining reads with flatMap keeps one code path for the JVM, Scala Native, and Node.js, where nothing can block. Code that never runs on Scala.js can also block with reader.readLine("> ").await.
LineReader uses TerminalIO.default, the terminal of the platform it runs on, so the code above has no platform-specific parts.
Wiring with Design
Pass the terminal to LineReader through Design to swap it in tests. The application binds TerminalIO.default, and a test overrides it with TerminalIO.inMemory, which replays keystrokes and records the output:
import wvlet.uni.design.Design
class Repl(reader: LineReader):
def run(): Rx[Unit] = loop(reader)
val design = Design
.newDesign
.bindInstance[LineReaderConfig](LineReaderConfig().withHistoryFile(".my_history"))
.bindInstance[TerminalIO](TerminalIO.default)
.bindProvider { (config: LineReaderConfig, io: TerminalIO) =>
LineReader(config, io)
}
// Application
design.build[Repl](_.run().run())
// Test: type "hello", then "exit"
val io = TerminalIO.inMemory(Seq("hello\r".getBytes, "exit\r".getBytes))
(design + Design.newDesign.bindInstance[TerminalIO](io))
.run[Repl, Rx[Unit]](_.run())The test runs the same way on the JVM, Scala Native, and Scala.js.
Completion
A Completer returns the candidates that replace part of the input before the cursor. Completer.word completes the word before the cursor; a one-element result is inserted with a trailing space, and several are listed above the prompt after their common prefix is inserted.
val files = Completer.word(delimiters = "'\"") { prefix =>
listFiles(prefix).map { f =>
// Keep typing into directories: no trailing space
Candidate(f.path, complete = !f.isDirectory)
}
}Key Bindings
KeyMap.emacs is the default. Bind a key sequence, written in ^X notation, to a built-in LineAction or to custom code with LineAction.Custom. The custom code receives the LineEditor, which can read and change the input, print above it, or accept it.
val runStatement = LineAction.Custom(
"run-statement",
editor =>
editor.moveCursor(editor.buffer.length)
editor.insert(";")
editor.accept()
)
val config = LineReaderConfig()
.withKeyMap(KeyMap.emacs.unbind("^J")) // Ctrl-J accepts by default; free it for chords
.bind("^J^R", runStatement)While the keys typed so far start a longer binding, the editor waits for the next key.
Output While Reading
reader.printAbove(message) prints a message above the prompt and draws the input again below it, for example, from a background task. To stop a running task on Ctrl-C without exiting, register a handler on the terminal:
val cancel = reader.terminal.onInterrupt(() => task.cancel())
try task.await
finally cancel.cancelTerminal Access
TerminalIO is the layer LineReader is built on, and can be used directly for key-driven UIs: enterRawMode()/exitRawMode(), readInput, size, write, and onInterrupt. KeyDecoder turns input bytes into Key events.
| Platform | Raw mode and window size |
|---|---|
| JVM | libc termios through the Foreign Function & Memory API; needs Java 22 or later |
| Scala Native | libc termios through a small C shim bundled with Uni |
| Scala.js | Node.js process.stdin.setRawMode; not available in browsers |
When stdin or stdout is not a terminal (a pipe, a file, CI), on Windows, or on a JVM older than 22, input is read line by line without editing, and nothing is drawn.
On Java 24 and later, run the JVM with --enable-native-access=ALL-UNNAMED to turn off the warning the JVM prints on the first native call.
TerminalIO.inMemory(...) replays input and records output, for testing code built on LineReader without a terminal. See Wiring with Design.
Example
examples/repl is a small SQL-like REPL with completion, highlighting, multi-line statements, and chord bindings.