linenoise

Kind	ffi-c
Capabilities	ffi
Categories	terminal ffi
Keywords	linenoise readline line-editing repl terminal

linenoise line editing library bindings for Kit

Files

File	Description
`.editorconfig`	Editor formatting configuration
`.gitignore`	Git ignore rules for build artifacts and dependencies
`.tool-versions`	asdf tool versions (Zig, Kit)
`LICENSE`	MIT license file
`README.md`	This file
`c/kit_linenoise.c`	C FFI wrapper exposing a Kit-friendly API
`c/kit_linenoise.h`	C header for the FFI wrapper
`c/linenoise.c`	Bundled linenoise implementation
`c/linenoise.h`	Bundled linenoise public header
`examples/basic.kit`	Interactive REPL example
`kit.toml`	Package manifest with metadata, native build settings, and tasks
`src/linenoise.kit`	Kit bindings and high-level API
`tests/linenoise.test.kit`	API existence tests

Dependencies

No Kit package dependencies. No external system libraries are required.

The linenoise C source is bundled in this package and is compiled into libkit_linenoise.dylib during kit install and kit dev.

Installation

kit add gitlab.com/kit-lang/packages/kit-linenoise.git

This package requires the ffi capability because it calls the bundled native library.

Usage

import Kit.Linenoise as Linenoise

main = fn =>
  println "Type 'quit' to exit\n"

  # Configure history.
  Linenoise.history-set-max 100

  match Linenoise.history-load "/tmp/kit-linenoise-history.txt"
    | Ok _ -> println "(History loaded)"
    | Err _ -> println "(No previous history)"

  repl = fn(running) =>
    if running then
      line = Linenoise.readline "kit> "
      if String.length line == 0 then
        println "\nGoodbye!"
        match Linenoise.history-save "/tmp/kit-linenoise-history.txt"
          | Ok _ -> println "(History saved)"
          | Err e -> println "Failed to save history: ${e}"
        no-op
      else if line == "quit" then
        println "Goodbye!"
        match Linenoise.history-save "/tmp/kit-linenoise-history.txt"
          | Ok _ -> println "(History saved)"
          | Err e -> println "Failed to save history: ${e}"
        no-op
      else if line == "clear" then
        Linenoise.clear-screen
        repl true
      else
        Linenoise.history-add line
        println "You typed: ${line}"
        repl true
    else
      no-op

  repl true

main

Run examples with --allow=ffi:

kit run examples/basic.kit --allow=ffi

API

Function	Description
`readline prompt`	Read a line using linenoise editing with the given prompt
`readline-default`	Read a line with the default `>` prompt
`history-add line`	Add a line to in-memory history
`history-set-max len`	Set the maximum number of history entries
`history-save filename`	Save history to a file, returning `Result Unit String`
`history-load filename`	Load history from a file, returning `Result Unit String`
`set-multiline enabled`	Enable or disable multi-line editing
`set-mask-mode enabled`	Enable or disable password-style masking
`clear-screen`	Clear the terminal screen

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit --allow=ffi

Compile examples to a native binary:

kit build examples/basic.kit -o basic --allow=ffi && ./basic

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (native build, format, check, test):

kit dev

This will:

Build the bundled native library
Format and check source files in src/
Type check examples in examples/
Run tests in tests/ with coverage

Running Parity Checks

Run interpreter/compiler parity checks for examples:

kit parity --no-spinner --failures-only

The basic example is marked @check(interactive), so parity build-checks it without trying to drive the REPL interactively.

Generating Documentation

Generate API documentation from doc comments:

kit doc src/linenoise.kit

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html.

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Native Build Notes

The native library is configured in kit.toml:

csources = ["c/kit_linenoise.c", "c/linenoise.c"]
includes = ["c"]
libraries = ["kit_linenoise"]

Each extern-c binding in src/linenoise.kit links against kit_linenoise, which lets both kit run and compiled binaries resolve the wrapper symbols from the package library.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/linenoise/, making it available for import as Kit.Linenoise in other projects.

License

This package is released under the MIT License - see LICENSE for details.

linenoise is released under the BSD 2-Clause License.

Exported Functions & Types

`readline`

Read a line of input with the given prompt.

Supports line editing (arrow keys, backspace, etc.) and history navigation (up/down arrows). Returns empty string on EOF (Ctrl-D).

Parameters:

Returns:

String -> String

`readline-default`

Read a line with the default prompt ("> ").

String

`history-add`

Add a line to the history.

Parameters:

String -> Unit

`history-set-max`

Set the maximum number of history entries.

Parameters:

Int -> Unit

`history-save`

Save history to a file.

Parameters:

Returns:

NonEmptyString -> Result Unit String

`history-load`

Load history from a file.

Parameters:

Returns:

NonEmptyString -> Result Unit String

`set-multiline`

Enable or disable multi-line editing mode.

When enabled, long lines wrap to the next line instead of scrolling.

Parameters:

Bool -> Unit

`set-mask-mode`

Enable or disable password masking mode.

When enabled, typed characters are shown as asterisks.

Parameters:

Bool -> Unit

`clear-screen`

Clear the terminal screen.

Unit