TTY

TTY

Módulo de UI de terminal para eventos de entrada raw, saída estilizada e utilitários de layout.

Este módulo só funciona dentro de um contexto de terminal. Você não pode usá-lo a partir de funções regulares — apenas a partir de processos executando em um Terminal Host.

Carregamento

local tty = require("tty")

Loop de Entrada

Inicia o leitor de entrada raw, inscreve-se nos eventos e os processa em loop:

local tty = require("tty")
local io = require("io")

local function handler()
    tty.start()
    local events = tty.events()

    while true do
        local ev = events:receive()
        if not ev then break end

        if ev.type == "key" then
            if ev.key == "q" or (ev.ctrl and ev.key == "c") then
                break
            end
            io.print("Key: " .. ev.key)

        elseif ev.type == "resize" then
            io.print("Size: " .. ev.width .. "x" .. ev.height)
        end
    end

    tty.stop()
end

Controle de Entrada

tty.start()

Habilita o modo de entrada raw do terminal. O terminal alterna para o modo raw e começa a emitir eventos.

local ok, err = tty.start()

Retorna: boolean, error

tty.stop()

Desabilita a entrada raw e restaura o terminal ao modo normal.

local ok, err = tty.stop()

Retorna: boolean, error

tty.events()

Inscreve-se nos eventos do terminal e retorna um channel. Eventos são entregues como tabelas com um campo type.

local events = tty.events()

Retorna: EventChannel, error

tty.screen_size()

Consulta as dimensões atuais do terminal.

local width, height, err = tty.screen_size()

Retorna: number, number, error

tty.mouse(enable)

Habilita ou desabilita o rastreamento de eventos de mouse.

local ok, err = tty.mouse(true)

Parâmetro	Tipo	Descrição
enable	boolean	true para habilitar, false para desabilitar

Retorna: boolean, error

Tipos de Evento

Eventos são tabelas com um campo type que determina quais outros campos estão presentes.

Evento de Tecla

{
    type = "key",
    key = "a",           -- caractere imprimível ou nome da tecla
    key_type = "runes",  -- "runes" para imprimível, ou nome de tecla especial
    action = "press",    -- "press" ou "release"
    alt = false,
    ctrl = false,
    shift = false
}

Evento de Mouse

Requer tty.mouse(true).

{
    type = "mouse",
    action = "press",    -- "press", "release", "motion", "wheel"
    button = "left",     -- nome do botão
    x = 10,
    y = 5,
    alt = false,
    ctrl = false,
    shift = false
}

Evento de Redimensionamento

{type = "resize", width = 120, height = 40}

Evento de Início

Emitido uma vez após tty.start() com as dimensões iniciais.

{type = "start", width = 120, height = 40}

Evento de Foco

{type = "focus", focused = true}

Evento de Colar

{type = "paste", text = "pasted content"}

Vinculações de Teclas

Crie vinculações de teclas reutilizáveis que correspondem a eventos de tecla:

local quit = tty.bind({
    keys = {"q", "ctrl+c"},
    help = {key = "q/ctrl+c", desc = "quit"}
})

-- No loop de eventos
if quit:matches(ev) then
    break
end

tty.bind(config)

Campo	Tipo	Descrição
keys	string[]	Padrões de tecla a corresponder (ex: "a", "ctrl+c", "enter")
help	table	Opcional. {key = "...", desc = "..."} para texto de ajuda

Retorna: KeyBinding

Métodos de KeyBinding

Método	Retorna	Descrição
matches(event)	boolean	Testa se um evento de tecla corresponde a esta vinculação
set_enabled(bool)	self	Habilita ou desabilita a vinculação
is_enabled()	boolean	Verifica se a vinculação está habilitada
help()	table	Retorna informações de ajuda {key, desc}

Estilos

Crie saída de texto estilizada usando estilização baseada em lipgloss. Todos os métodos de estilo retornam um novo estilo (imutável).

local tty = require("tty")
local io = require("io")

local title = tty.style()
    :bold()
    :foreground("#FF0000")
    :padding(0, 1)

local box = tty.style()
    :border(tty.borders.ROUNDED)
    :border_foreground("#00FF00")
    :width(40)
    :padding(1, 2)

io.print(box:render(title:render("Hello"), "World"))

tty.style()

Cria um novo estilo vazio.

Retorna: Style

Métodos de Estilo

Todos os métodos retornam um novo Style e podem ser encadeados.

Decoração de Texto

Método	Parâmetro	Descrição
foreground(color)	string	Cor do texto (hex "#FF0000", ANSI "9", ou nome)
background(color)	string	Cor de fundo
bold(enable?)	boolean	Texto em negrito (padrão: true)
italic(enable?)	boolean	Texto em itálico
underline(enable?)	boolean	Texto sublinhado
strikethrough(enable?)	boolean	Texto tachado
faint(enable?)	boolean	Texto esmaecido
blink(enable?)	boolean	Texto piscante
reverse(enable?)	boolean	Inverte primeiro plano/fundo

Layout

Método	Parâmetro	Descrição
width(n)	number	Largura fixa
height(n)	number	Altura fixa
max_width(n)	number	Largura máxima
max_height(n)	number	Altura máxima
padding(...)	numbers	Padding (estilo CSS: top, right, bottom, left)
margin(...)	numbers	Margin (estilo CSS)
align(pos)	number	Alinhamento horizontal
align_vertical(pos)	number	Alinhamento vertical
inline(enable?)	boolean	Modo de renderização inline

Bordas

Método	Parâmetro	Descrição
border(name, ...)	string, booleans	Estilo de borda, alternâncias opcionais por lado
border_foreground(...)	strings	Cor(es) de borda
border_background(...)	strings	Cor(es) de fundo da borda

Outros

Método	Descrição
render(...)	Renderiza strings com este estilo aplicado
copy()	Cria uma cópia deste estilo

Constantes de Borda

tty.borders.NORMAL
tty.borders.ROUNDED
tty.borders.THICK
tty.borders.DOUBLE
tty.borders.HIDDEN

Constantes de Alinhamento

tty.align.LEFT    -- 0
tty.align.CENTER  -- 0.5
tty.align.RIGHT   -- 1

Utilitários de Texto

Funções de layout e medição para texto estilizado. Disponíveis sob tty.text.

Medição

local w = tty.text.width("hello")         -- largura imprimível (ciente de ANSI)
local h = tty.text.height("a\nb\nc")      -- contagem de linhas
local w, h = tty.text.size("hello\nworld") -- ambos

Junção

-- Junta lado a lado, alinhado no topo
local row = tty.text.join_horizontal(tty.text.position.TOP, left, right)

-- Empilha verticalmente, centralizado
local col = tty.text.join_vertical(tty.text.position.CENTER, top, bottom)

Dimensões Máximas

local w = tty.text.max_width({"short", "a longer string"})   -- mais largo
local h = tty.text.max_height({"one\ntwo", "single"})         -- mais alto

Posicionamento

Posiciona uma string dentro de uma caixa de dimensões dadas:

-- Centraliza em uma caixa 80x24
local out = tty.text.place(80, 24, tty.text.position.CENTER, tty.text.position.CENTER, content)

-- Apenas horizontal
local out = tty.text.place_horizontal(80, tty.text.position.RIGHT, content)

-- Apenas vertical
local out = tty.text.place_vertical(24, tty.text.position.BOTTOM, content)

Constantes de Posição

tty.text.position.TOP      -- 0
tty.text.position.LEFT     -- 0
tty.text.position.CENTER   -- 0.5
tty.text.position.BOTTOM   -- 1
tty.text.position.RIGHT    -- 1

Veja Também

• I/O do Terminal — operações de stdin/stdout/stderr
• Terminal Host — Configuração do host de terminal