Cross-platform Kotlin/Native readline library with history support for interactive console apps.

📖 Documentation

🏠 Homepage (under construction)

[!IMPORTANT]
The project is in a very early stage; thus, breaking changes should be expected.

• Unix (tested on FreeBSD, Linux, and macOS)
• Windows
  • cmd.exe
  • Powershell

• Powershell ISE is not supported
• Mintty (Cygwin/MinGW) is not supported
• Highlighting / Colors are not supported on Windows < Windows 10 except with ConEmu and ColorMode::Forced.

• Cross-platform line editing for Unix (Linux, macOS, FreeBSD) and Windows consoles.
• Simple, composable API:
  • Read one line with a prompt prefix and get Result back (non-throwing API).
  • Clear screen, manage history, and attach completion/highlighting strategies.
• History management:
  • In-memory history with max size and duplicate handling policy.
  • Load from/save to a file, clear history, and optional auto-add on successful read.
  • Optionally ignore lines starting with a space.
• Pluggable completion:
  • Interface-based Completer with cursor-aware token replacement.
  • Built-in SimpleFileCompleter for filesystem paths (tilde expansion, hidden files rules, dir trailing slash).
  • Multiple completion modes: Circular cycling or List with common-prefix and paging; show-all-if-ambiguous option.
• Configurable highlighting:
  • Highlighter interface to style prompt, inline hints, and candidates (e.g., via ANSI colors).
  • Color modes: Enabled, Forced, or Disabled to match terminal capabilities.
• Editing behavior and keymaps:
  • Emacs or Vi editing modes.
  • Bell styles: audible or none (with sensible Windows default).
• Terminal features (where supported):
  • Bracketed paste, synchronized output, and signal handling on Unix-like systems.
• I/O behavior:
  • STDIO by default or Prefer terminal behavior when available.

A minimal REPL-style loop with history persistence:

fun main() {
    val history = "history.txt" // Filesystem path to the history file.

    // Configure the LineEditor.
    val config = LineEditorConfig(
        maxHistorySize = 100,
        completionType = CompletionType.LIST,
        // See the documentation for more options.
    )

    // Create a new LineEditor instance.
    val editor = SimpleLineEditor(
        linePrefix = "> ",
        config = config,
    ).also { editor ->
        // Set up the completer and highlighter.
        editor
            .withCompleter(SimpleFileCompleter()) // Provides file completion (optional).
            .withHighlighter(SimpleHighlighter()) // Provides color highlighting (optional).

        // Load the history from the disk (throws LineEditorError if it fails).
        editor.loadHistory(history).getOrThrow()
    }

    println("Welcome to the LineEditor example!")
    println("Press Ctrl+C to exit")

    while (true) {
        // Read a line from the user.
        editor.readLine()
            .onFailure { err ->
                // err is a LineEditorError
                println(err.message)
                break

            }
            .onSuccess { line ->
                // We can also add the line to the history automatically by setting autoAddHistory = true in the config.
                editor.addHistoryEntry(line)
                println(line)
            }
    }

    // Save the history to disk.
    editor.saveHistory(history)
}

See more examples here

For all modes:

Readline Emacs Editing Mode Cheat Sheet

Readline vi Editing Mode Cheat Sheet

ANSI escape code

The library is published to Maven Central. Use the latest version shown by the badge above.

Kotlin DSL (example for a native target):

kotlin {
    // Choose your native targets, e.g.:
    macosX64()
    linuxX64()
    mingwX64()

    sourceSets {
        // With the default hierarchy, a shared nativeMain is available when you have multiple native targets
        val nativeMain by getting {
            dependencies {
                implementation("io.github.smyrgeorge:readline4k:<latest>")
            }
        }
    }
}

If you use only one native target, add the dependency to that target's Main source set (e.g., macosX64Main, linuxX64Main, or mingwX64Main).

Under the hood, readline4k leverages the rustyline project to provide comprehensive readline functionality, with communication between Kotlin and the Rust library handled through FFI (Foreign Function Interface).

MIT — see LICENSE.