io Input and Output

io is Alia's standard library input and output module, providing standard input/output operations, terminal control, and core TUI capabilities.

Importing the Module

import 'io' as io ~ import as a variable
import 'io' ~ import into scope

Basic I/O

Output Functions

print

io.print writes to standard output without a newline.

io.print 'Hello, '
io.println 'World!'

println

io.println writes to standard output with a newline.

io.println 'This is a line'

eprint

io.eprint writes to standard error without a newline.

io.eprint 'Error: '
io.eprintln 'Something went wrong'

eprintln

io.eprintln writes to standard error with a newline.

io.eprintln 'Error occurred'

format

io.format formats output using {} as placeholders.

const result = io.format 'Name: {}, Age: {}' with ['Alice', 30]
io.println result  ~ output: Name: Alice, Age: 30

Terminal Information

terminalWidth

terminalWidth is the terminal width (number of columns), of type Number.

const width = io.terminalWidth
print 'Terminal width: ' .. width

terminalHeight

terminalHeight is the terminal height (number of rows), of type Number.

const height = io.terminalHeight
print 'Terminal height: ' .. height

terminalSize

terminalSize returns the terminal dimensions as an Object, containing the width and height properties.

const size = io.terminalSize
print 'Size: ' .. size.width .. 'x' .. size.height

Terminal Control

Cursor Control

moveCursor

moveCursor moves the cursor to the specified position (0-based).

io.moveCursor at row 0 column 0  ~ move to the top-left corner
io.moveCursor at row 5 column 10  ~ move to row 5, column 10

moveCursorUp / moveCursorDown / moveCursorForward / moveCursorBack

These four methods move the cursor relatively.

io.moveCursorUp 1
io.moveCursorDown 1
io.moveCursorForward 1
io.moveCursorBack 1

saveCursor / restoreCursor

saveCursor and restoreCursor save and restore the cursor position.

io.saveCursor
io.moveCursor at row 0 column 0
io.restoreCursor

hideCursor / showCursor

hideCursor and showCursor hide and show the cursor.

io.hideCursor
io.showCursor

Screen Control

clearScreen

clearScreen clears the entire screen.

io.clearScreen

clearLine

clearLine clears the current line.

io.clearLine

clearToEndOfLine

clearToEndOfLine clears to the end of the line.

io.clearToEndOfLine

clearToEndOfScreen

clearToEndOfScreen clears to the end of the screen.

io.clearToEndOfScreen

Full-Screen Mode

enterAlternateScreen / exitAlternateScreen

enterAlternateScreen and exitAlternateScreen enter and exit the alternate screen buffer.

io.enterAlternateScreen
io.clearScreen
io.println 'This is in alternate screen'
io.exitAlternateScreen

Enhanced Input

Input Functions

io.read, io.readChar, and io.readKey are property-style reads, while io.readLine and io.readPassword accept a single prompt string. All of the above reads return a Stack conforming to Alia's asynchronous model, which must be consumed with await; the result is Null on EOF.

read

read reads one line (up to a newline or EOF); the result excludes the trailing newline.

const task = io.read
const line = await task

readLine

readLine reads one line, printing a prompt before reading.

const task = io.readLine 'Name> '
const name = await task

readChar

readChar reads a single character (decoding 1-4 bytes based on the UTF-8 leading byte).

const task = io.readChar
const ch = await task

readPassword

readPassword reads a password: on a TTY it uses raw mode to suppress echo and supports backspace and Ctrl+C; on a non-TTY it falls back to whole-line reading.

const task = io.readPassword 'Password> '
const pw = await task

Raw Mode

setRawMode

setRawMode sets raw mode, enabling character-by-character reading.

io.setRawMode true
~ readKey can now read special keys
io.setRawMode false

Key Reading

readKey

readKey reads a key press and returns a Stack; after await, it yields a key information object.

const task = io.readKey
const key = await task
if (typeOf key) == 'Object' {
  print 'Key: ' .. key['key']
  print 'Ctrl: ' .. key['ctrl']
  print 'Alt: ' .. key['alt']
}

The returned object has the following structure:

• key: key name (e.g. 'a', 'enter', 'up', 'f1', etc.)
• ctrl: whether the Ctrl key is pressed
• alt: whether the Alt key is pressed
• shift: whether the Shift key is pressed
• raw: raw byte code

hasKey

hasKey non-blockingly checks whether a key press is available.

const has = io.hasKey
~ readKey can be called when has is true

Mouse Support

enableMouse / disableMouse

enableMouse and disableMouse enable and disable mouse events.

io.enableMouse
~ mouse events can now be received
io.disableMouse

Text Styles

Color Settings

Color constants are passed as positional arguments to io.setColor and io.setBackgroundColor.

const red = io.Colors.Red
io.setColor red  ~ set the foreground color

const blue = io.BgColors.Blue
io.setBackgroundColor blue  ~ set the background color

io.resetColor  ~ reset the color

Text Styles

io.bold, io.italic, io.underline, io.strikethrough, and io.inverse set the corresponding text styles, and io.resetStyle resets all styles.

io.bold
io.italic
io.underline
io.strikethrough
io.inverse
io.resetStyle  ~ reset all styles

Color Constants

Foreground Colors

io.Colors.Black
io.Colors.Red
io.Colors.Green
io.Colors.Yellow
io.Colors.Blue
io.Colors.Magenta
io.Colors.Cyan
io.Colors.White
io.Colors.Gray
io.Colors.BrightRed
io.Colors.BrightGreen
io.Colors.BrightYellow
io.Colors.BrightBlue
io.Colors.BrightMagenta
io.Colors.BrightCyan
io.Colors.BrightWhite

Background Colors

io.BgColors.Black
io.BgColors.Red
io.BgColors.Green
io.BgColors.Yellow
io.BgColors.Blue
io.BgColors.Magenta
io.BgColors.Cyan
io.BgColors.White

Drawing Primitives

drawBox

drawBox draws a border.

io.drawBox at 0 and 0 sized 20 and 10  ~ draw a single-line border

fillRect

fillRect fills a rectangle.

io.fillRect at 0 and 0 sized 10 and 3 with '#'

drawText

drawText draws text at the specified position.

io.drawText at 0 and 0 with 'Hello at origin'
io.drawText at 5 and 10 with 'Text at (5, 10)'

Event Loop

Creating an Event Loop

const loop = io.eventLoop

EventLoop Methods

on

on registers an event callback.

const onKey = alias <Object keyInfo> -> {
  print 'Key pressed: ' .. keyInfo.key
}
loop.on 'key' with onKey

off

off removes an event callback.

loop.off 'key' onKey

start / stop

start and stop start and stop the event loop.

loop.start
~ ...
loop.stop

setTimeout

setTimeout registers a one-shot timer.

const fire = alias -> {
  print 'Timer fired!'
}
const timerId = loop.setTimeout 1000 with fire
loop.clearTimer timerId  ~ cancel the timer

setInterval

setInterval registers an interval timer.

const tick = alias -> {
  print 'Tick!'
}
const timerId = loop.setInterval 500 with tick
loop.clearTimer timerId  ~ cancel the timer

Event Types

Event	Parameters	Description
'key'	<Object keyInfo>	Key press event
'mouse'	<Object mouseInfo>	Mouse event
'resize'	-	Terminal size changed
'tick'	-	Timer fired

Example Code

Simple Menu

import 'io' as io

io.enterAlternateScreen
io.clearScreen
io.hideCursor

const items = ['Start', 'Settings', 'Exit']
let selected = 0

const drawMenu = alias -> {
  io.moveCursor at row 0 column 0
  io.println 'Main Menu'
  io.println '========='
  let i = 0
  while i < items.length {
    if i == selected {
      const cyan = io.Colors.Cyan
      io.setColor cyan
      const line = '> ' .. items[i]
      io.println line
      io.resetColor
    } else {
      const line = '  ' .. items[i]
      io.println line
    }
    i++
  }
}

call drawMenu

io.setRawMode true
let running = true
while running {
  const keyInfo = await io.readKey
  if (typeOf keyInfo) == 'Object' {
    if keyInfo['key'] == 'up' {
      if selected > 0 { selected = selected - 1 }
    } else {
      if keyInfo['key'] == 'down' {
        if selected < items.length - 1 { selected = selected + 1 }
      } else {
        if keyInfo['key'] == 'enter' { running = false }
      }
    }
  }
  if running {
    io.clearScreen
    call drawMenu
  }
}

io.setRawMode false
io.showCursor
io.exitAlternateScreen
const selectedText = 'Selected: ' .. items[selected]
io.println selectedText

Colored Output

import 'io' as io

io.println 'Colorful output:'

const red = io.Colors.Red
io.setColor red
io.print 'Red '
const green = io.Colors.Green
io.setColor green
io.print 'Green '
const blue = io.Colors.Blue
io.setColor blue
io.print 'Blue '
io.resetColor
io.println ''

io.bold
const yellow = io.Colors.Yellow
io.setColor yellow
io.println 'Bold Yellow Text'
io.resetStyle

Progress Bar

import 'io' as io

const total = 50
let current = 0

while current <= total {
  const progress = current * 100 / total
  const filledCount = current * 20 / total

  let bar = ''
  let i = 0
  while i < 20 {
    if i < filledCount {
      bar = bar .. '#'
    } else {
      bar = bar .. '-'
    }
    i++
  }

  io.moveCursor at row 0 column 0
  const green = io.Colors.Green
  io.setColor green
  print 'Progress: [' .. bar .. '] ' .. progress .. '%'
  io.resetColor

  current++
}

io.println ''
io.println 'Complete!'

Next Steps

• web Network Access