ncurses

ncurses terminal UI library bindings for Kit

Files

Dependencies

No Kit package dependencies.

This package depends on the system ncurses library through C FFI.

Installation

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

Usage

import Kit.NCurses as Nc

# Initialize ncurses. Always call Nc.end before exiting.
win = Nc.init
Nc.echo-off
Nc.cbreak
Nc.keypad-on win

# Get terminal dimensions.
max-y = Nc.get-max-y win
max-x = Nc.get-max-x win

# Display text at specific positions.
Nc.print-at 0 0 "=== Kit NCurses Demo ==="
Nc.print-at 2 0 ("Terminal size: " ++ (show max-x) ++ "x" ++ (show max-y))
Nc.print-at 4 0 "Press any key to see its code."
Nc.refresh

# Wait for a keypress and display the key code.
ch = Nc.get-char
Nc.print-at 6 0 ("You pressed key code: " ++ (show ch))
Nc.print-at 8 0 "Press any key to exit..."
Nc.refresh
Nc.get-char

# Restore terminal state.
Nc.end

Common Operations

Zero-arity Kit functions auto-invoke when referenced, so call Nc.refresh, Nc.get-char, and constants like Nc.key-up without ().

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit

Compile examples to a native binary:

kit build examples/basic.kit && ./basic

The basic example opens a real terminal UI and waits for keyboard input. It is marked @check(interactive) so parity build-checks it without trying to drive the ncurses screen or compare terminal control output.

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

The tests avoid driving an interactive screen. They validate exported constants and API availability so the package can be checked in automated environments.

Running kit dev

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

kit dev

This will:

1. Format and check source files in src/
2. Check example files in examples/
3. Run tests in tests/ with coverage

Running Parity

Run interpreter/compiler parity checks for examples:

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

Interactive examples are build-checked but are not executed for output comparison.

Generating Documentation

Generate API documentation from doc comments:

kit doc

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

Cleaning Build Artifacts

Remove generated files, caches, parity results, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

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

Developer Notes

The C wrapper exists because ncurses exposes several macros and varargs-style APIs that are not convenient to call directly through Kit FFI. The wrapper keeps the Kit API simple and gives tests a stable surface for constants such as colors, arrow keys, function keys, and color pair attributes.

Always restore the terminal with Nc.end after calling Nc.init. During manual debugging, a process that exits before cleanup can leave the shell in an altered mode; running reset in the terminal usually restores normal behavior.

License

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

ncurses is released under the MIT License.

Exported Functions & Types

init

Initialize the ncurses terminal UI.

Returns a pointer to the standard screen window (stdscr), which is needed for functions like keypad-on, get-max-y, and get-max-x. Always call end when done to restore the terminal.

Returns:

Ptr

win = init()
# ... use ncurses ...
end()

end

Restore the terminal to its normal state.

Must be called before program exit to restore terminal settings. Failing to call this leaves the terminal in a broken state.

Unit

win = init()
# ... use ncurses ...
end()

print-str

Print a string at the current cursor position.

Parameters:

String -> Unit

print-str "Hello, World!"
refresh()

print-at

Print a string at a specific position (row, column).

Parameters:

Int -> Int -> String -> Unit

print-at 5 10 "Centered text"
refresh()

refresh

Refresh the screen to display pending changes.

Changes made with print-str and print-at are buffered. Call refresh to make them visible on screen.

Unit

print-at 0 0 "Updated!"
refresh()

clear

Clear the entire screen.

Unit

clear()
refresh()

move-cursor

Move the cursor to a specific position.

Parameters:

Int -> Int -> Unit

move-cursor 10 20

get-char

Read a single character or key from the keyboard.

Blocks until a key is pressed. Returns the character code or a special key constant (use key-up, key-down, etc. to compare).

Returns:

Int

ch = get-char()
if ch == key-up() then
  print-at 0 0 "Up arrow pressed!"

get-max-y

Get the maximum number of rows in a window.

Parameters:

Returns:

Ptr -> Int

win = init()
rows = get-max-y win
println ("Terminal has " ++ (show rows) ++ " rows")

get-max-x

Get the maximum number of columns in a window.

Parameters:

Returns:

Ptr -> Int

win = init()
cols = get-max-x win

echo-off

Disable echo of typed characters.

Unit

echo-off()

echo-on

Enable echo of typed characters.

Unit

echo-on()

cbreak

Enable cbreak mode (characters available immediately, no line buffering).

Unit

cbreak()

keypad-on

Enable keypad input for special keys (arrows, function keys, etc.).

Parameters:

Ptr -> Unit

win = init()
keypad-on win

set-timeout

Set input timeout in milliseconds.

A negative value blocks indefinitely (default). Zero enables non-blocking input. A positive value sets the timeout in milliseconds.

Parameters:

Int -> Unit

set-timeout 1000  # 1 second timeout

has-colors?

Check if the terminal supports colors.

Returns:

Bool

if has-colors?() then
  start-color()
  init-pair 1 color-red() color-black()

start-color

Initialize the color subsystem. Must be called before using colors.

Unit

start-color()

init-pair

Define a color pair with foreground and background colors.

Parameters:

Int -> Int -> Int -> Unit

init-pair 1 color-red() color-black()
init-pair 2 color-green() color-black()

attr-on

Enable a text attribute (e.g., color pair).

Parameters:

Int -> Unit

attr-on (color-pair 1)
print-str "Red text!"
attr-off (color-pair 1)

attr-off

Disable a text attribute.

Parameters:

Int -> Unit

attr-off (color-pair 1)

color-pair

Get the attribute value for a color pair number.

Parameters:

Returns:

Int -> Int

attr-on (color-pair 1)

color-black

Black color constant.

Int

color-red

Red color constant.

Int

color-green

Green color constant.

Int

color-yellow

Yellow color constant.

Int

color-blue

Blue color constant.

Int

color-magenta

Magenta color constant.

Int

color-cyan

Cyan color constant.

Int

color-white

White color constant.

Int

key-up

Up arrow key constant.

Int

key-down

Down arrow key constant.

Int

key-left

Left arrow key constant.

Int

key-right

Right arrow key constant.

Int

key-enter

Enter key constant.

Int

key-backspace

Backspace key constant.

Int

key-home

Home key constant.

Int

key-end

End key constant.

Int

key-delete

Delete key constant.

Int

key-insert

Insert key constant.

Int

key-page-down

Page Down key constant.

Int

key-page-up

Page Up key constant.

Int

key-f

Function key constant (F1-F12).

Parameters:

Returns:

Int -> Int

if ch == key-f 1 then println "F1 pressed"

key-resize

Terminal resize event key constant.

Int

cursor-set

Set cursor visibility.

Parameters:

Int -> Unit

cursor-set 0  # Hide cursor