celina

Celina CLI Library

A powerful Terminal User Interface library for Nim, inspired by Ratatui. Provides high-performance, type-safe components for building interactive terminal applications with both synchronous and asynchronous support.

Basic Usage:

import pkg/celina

proc main() =
  var app = newApp()
  app.run()

when isMainModule:
  main()

Async Usage:

Celina supports asyncdispatch and Chronos. Requires -d:asyncBackend flag.

# async_app.nim
import pkg/celina

proc main() {.async.} =
  var app = newAsyncApp()
  await app.runAsync()

when isMainModule:
  waitFor main()

Use asyncdispatch

$ nim c -d:asyncBackend=asyncdispatch async_app.nim

Use Chronos

$ nim c -d:asyncBackend=chronos async_app.nim

Consts

celinaVersion = "0.4.0"
Full version string
celinaVersionMajor = 0
Major version number
celinaVersionMinor = 4
Minor version number
celinaVersionPatch = 0
Patch version number

Procs

proc quickRun(eventHandler: proc (event: Event): bool;
              renderHandler: proc (buffer: var Buffer); config: AppConfig = AppConfig(
    title: "Celina App", alternateScreen: true, mouseCapture: false,
    rawMode: true, windowMode: false, targetFps: 60)) {.
    ...raises: [ValueError, Exception, TerminalError, CatchableError],
    tags: [TimeEffect, WriteIOEffect, RootEffect], forbids: [].}

Quick way to run a simple CLI application

Example:

quickRun(
  eventHandler = proc(event: Event): bool =
    case event.kind
    of EventKind.Key:
      if event.key.code == KeyCode.Char and event.key.char == "q":
        return false
    else: discard
    return true,
  
  renderHandler = proc(buffer: var Buffer) =
    buffer.clear()
    let area = buffer.area
    buffer.setString(10, area.height div 2, "Press 'q' to quit", defaultStyle())
)

Exports

Position, size, position, isValid, contains, rect, size, shrink, isValid, contains, union, $, right, center, Area, $, Size, -, isEmpty, Rect, pos, area, area, expand, shrink, intersects, bottom, +, intersection, $, rect, indigo, color256, grayscale, toAnsiCode, ==, withModifiers, ColorKind, $, Style, $, deepSkyBlue, hotPink, toAnsiCode, bold, color256, reversed, hsv, Color, rgb, hsvToRgb, ColorValue, withBg, style, ==, withFg, brightColors, color, default, rgb, salmon, teal, addModifier, italic, violet, cubeColor, toAnsiSequence, RgbColor, crimson, limeGreen, withBg, $, style, ==, defaultColor, orange, lerp, underline, toAnsiCode, defaultStyle, withFg, darkColors, resetSequence, gold, toBgAnsiCode, lerp, StyleModifier, rgb, toAnsiCode, removeModifier, pastels, diff, getDirtyRegionSize, Cell, merge, []=, isEmpty, isValidPos, fill, DirtyRegion, Buffer, ==, clear, cell, clearDirty, setString, merge, setRunes, isValidPos, setString, []=, $, $, newBuffer, runeWidth, runesWidth, width, cell, [], newBuffer, cell, ==, toStrings, markDirty, setString, resize, setRunes, setString, markDirtyRect, [], readKeyInput, readKey, truncateUtf8, Utf8ValidationResult, MouseEventKind, KeyCode, buildUtf8String, validateUtf8Sequence, KeyModifier, incrementResizeCounter, pollKey, waitForKey, initSignalHandling, waitForAnyKey, pollEvents, Event, MouseButton, KeyEvent, utf8CharLength, MouseEvent, getResizeCounter, hasInput, utf8ByteLength, isUtf8ContinuationByte, EventKind, min, twoColumnPercent, withMargins, fill, percentage, Constraint, evenSplit, LayoutSolver, withMargin, Layout, length, layout, vertical, max, threeRow, twoColumn, ConstraintKind, $, split, Direction, ratio, horizontal, $, render, getTerminalSize, Terminal, suspend, setCursorStyle, drawWithCursor, withTerminal, moveCursorRight, withTerminal, moveCursorUp, moveCursorLeft, cleanup, enableRawMode, isSuspended, disableRawMode, disableMouse, setup, saveCursor, enableAlternateScreen, setupWithMouse, moveCursorDown, showCursor, disableAlternateScreen, setCursorPos, clearLine, draw, renderFull, clearScreen, TerminalError, updateSize, setCursorPos, clearToEndOfLine, hideCursor, getTerminalSizeOrDefault, renderCell, enableMouse, restoreCursor, setupWithHiddenCursor, resume, clearToStartOfLine, newTerminal, moveCursor, EventError, tryRecover, ensureNotNil, newTerminalError, newLayoutError, checkSystemCall, checkSystemCallVoid, newRenderError, TerminalError, ensure, newEventError, tryIO, RenderError, LayoutError, newBufferError, withResource, withErrorContext, withContext, BufferError, debugLog, checkForLeaks, getStats, ResourceId, ==, getGlobalResourceManager, acquire, newResourceGuard, initGlobalResourceManager, isValid, withManagedResource, newResourceManager, $, ResourceType, release, withResourceGuard, touchResource, globalResourceManager, release, ResourceState, getResourceInfo, getResourceStats, clear, ResourceGuard, cleanupAllResources, hash, ResourceManager, ResourceInfo, unregisterResource, get, newResourcePool, registerResource, cleanupLeakedResources, getAllResources, ResourcePool, CursorUpSeq, applyTerminalConfig, HideCursorSeq, generateRenderBatch, getTerminalCapabilities, disableMouseMode, CursorRightSeq, makeCursorPositionSeq, getSize, ShowCursorSeq, supportsAnsi, getTerminalSizeFromSystem, AlternateScreenExit, clearLastBufferForResume, MouseMode, calculateRenderMetrics, isSuspended, CursorLeftSeq, isTerminalInteractive, CursorState, RenderCommandKind, buildOutputWithCursor, optimizeRenderBatch, enableAlternateScreenImpl, buildOutputString, SaveCursorSeq, disableMouseImpl, calculateSimpleDiff, buildDifferentialOutput, getArea, RenderBatch, ClearScreenSeq, buildFullRenderOutput, AlternateScreenEnter, enableMouseMode, CursorStyle, CursorStyleBlinkingUnderline, getRawModeConfig, ClearToEndOfLineSeq, isRawMode, CursorStyleBlinkingBlock, makeCursorPositionSeq, ClearToStartOfLineSeq, MouseSequences, isAlternateScreen, AnsiSequence, TerminalConfig, CursorStyleSteadyUnderline, enableMouseImpl, writeAndFlush, SuspendState, CursorStyleSteadyBlock, saveSuspendState, parseMouseEvent, disableAlternateScreenImpl, RenderMetrics, CursorStyleDefault, CursorStyleSteadyBar, RestoreCursorSeq, CursorStyleBlinkingBar, CursorDownSeq, makeCursorMoveSeq, isMouseEnabled, addCommand, restoreSuspendedFeatures, RenderCommand, getTerminalSizeWithFallback, getCursorStyleSeq, ClearLineSeq, setCursorPosition, setCursorStyle, setTargetFps, getCursorStyle, App, suspend, getWindowInfo, showCursor, removeWindow, getTargetFps, enableWindowMode, getFocusedWindowId, withAlternateScreen, focusWindow, resetCursor, getCurrentFps, getWindow, withMouseCapture, moveCursorBy, withRawMode, withWindowMode, getWindows, isSuspended, showCursorAt, isCursorVisible, newApp, DefaultAppConfig, getWindowCount, onEvent, setCursorPosition, showCursorAt, defaultAppConfig, onEvent, run, handleWindowEvent, resume, withTitle, getFocusedWindow, quit, hideCursor, onRender, addWindow, getCursorPosition, AppConfig, withTargetFps, withSuspend, Renderer, render, showCursorAt, clear, setCursorPosition, renderDiff, getCursorManager, isCursorVisible, forceRender, showCursorAt, getBuffer, hideCursor, resize, newRenderer, setString, resize, getCursorPosition, setCursorPosition, showCursor, setCursorStyle, newCursorManager, isVisible, setPosition, styleChanged, hide, setStyle, updateLastStyle, CursorState, CursorManager, reset, showAt, setPosition, show, getStyle, getState, hasPosition, getPosition, getRemainingFrameTime, getTargetFps, getFrameTimeout, endFrame, setTargetFps, getStats, newFpsMonitor, shouldRender, getCurrentFps, FpsMonitor, startFrame, PerfStats, WindowState, render, WindowEvent, render, setBorder, defaultBorder, move, WindowKeyHandler, ==, getVisibleWindows, Window, defaultBorderChars, dispatchEvent, setKeyHandler, stopPropagation, WindowBorder, hide, $, removeWindow, getContentBuffer, WindowManager, bringToFront, handleEvent, focusWindow, findWindowAt, addWindow, newWindow, getWindow, setResizeHandler, resize, restore, WindowInfo, sendToBack, setArea, setEventHandler, setTitle, EventHandler, WindowMouseHandler, maximize, show, dispatchResize, WindowId, preventDefault, clearEventHandlers, minimize, toWindowInfo, WindowEventHandler, handleWindowEvent, newWindowManager, BorderChars, setMouseHandler, getContentSize, getFocusedWindow, WindowResizeHandler, EventPhase, registerFD, asyncBackend, sleepMs, hasChronos, unregisterFD, hasAsyncDispatch, hasAsyncSupport, hasAsyncSupport, hasChronos, hasAsyncDispatch