ncurses

ncurses terminal UI library bindings for Kit

Files

Dependencies

No Kit package dependencies.

Installation

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

System Requirements

Usage

import Kit.NCurses as Nc

main = fn =>
  # Initialize ncurses
  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.print-at 5 0 "Press 'q' to quit."
  Nc.refresh()

  # Wait for keypress
  ch = Nc.get-char()
  Nc.print-at 7 0 ("You pressed key code: " ++ (show ch))
  Nc.print-at 9 0 "Press any key to exit..."
  Nc.refresh()
  Nc.get-char()

  # Clean up
  Nc.end()

main

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

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 (format, check, test):

kit dev

This will:

1. Format and check source files in src/
2. Run tests in tests/ with coverage

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, 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.

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