kero

package module
v0.0.0-...-7d3ed90 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: BSD-3-Clause Imports: 12 Imported by: 0

Documentation

Index

Constants

View Source
const Continuation rune = -1

Continuation is a sentinel rune used in wide-character continuation cells. Screen.Flush skips emitting output for cells containing Continuation.

Variables

View Source
var (
	ColorDefault = Color{Type: ColorTypeDefault}
	ColorBlack   = Color{Type: ColorTypeANSI, Idx: 0}
	ColorRed     = Color{Type: ColorTypeANSI, Idx: 1}
	ColorGreen   = Color{Type: ColorTypeANSI, Idx: 2}
	ColorYellow  = Color{Type: ColorTypeANSI, Idx: 3}
	ColorBlue    = Color{Type: ColorTypeANSI, Idx: 4}
	ColorMagenta = Color{Type: ColorTypeANSI, Idx: 5}
	ColorCyan    = Color{Type: ColorTypeANSI, Idx: 6}
	ColorWhite   = Color{Type: ColorTypeANSI, Idx: 7}
)

Basic ANSI Color Constants (0-7 offset logic for standard 30-37 / 40-47)

Functions

func SplitHorizontal

func SplitHorizontal(r Rect, topHeight int) (top Rect, bottom Rect)

SplitHorizontal splits r into top and bottom rectangles.

func SplitVertical

func SplitVertical(r Rect, leftWidth int) (left Rect, right Rect)

SplitVertical splits r into left and right rectangles.

Types

type App

type App interface {
	// Init runs once after the terminal is ready.
	Init(ctx *Context) error
	// Update receives input, resize events, ticks, and internal messages.
	Update(ctx *Context, ev Event) error
	// Draw renders the current application state onto the provided Frame.
	// It should avoid mutating application state.
	Draw(ctx *Context, f *Frame)
}

App is the user-provided terminal program.

type Attr

type Attr uint16

Attr stores terminal text attributes.

const (
	AttrNone Attr = 0
	AttrBold Attr = 1 << iota
	AttrUnderline
	AttrReverse
	AttrDim
	AttrItalic
)

type Cell

type Cell struct {
	Ch    rune
	Style Style
}

Cell is one terminal cell.

type Color

type Color struct {
	Type ColorType
	R    uint8 // Used for RGB (or ANSI index if preferred)
	G    uint8
	B    uint8
	Idx  uint8 // Used for 256-color index or basic ANSI index
}

func Color256

func Color256(idx uint8) Color

func ColorANSI

func ColorANSI(idx uint8) Color

func ColorHex

func ColorHex(hex string) Color

ColorHex parses a hex color string (e.g., "#3E4451", "3E4451", "#3E4", "3E4") and returns an RGB Color. Returns ColorDefault if parsing fails.

func ColorRGB

func ColorRGB(r, g, b uint8) Color

type ColorType

type ColorType uint8
const (
	ColorTypeDefault ColorType = iota
	ColorTypeANSI              // Standard 8/16 ANSI colors
	ColorType256               // 256-color palette (0-255)
	ColorTypeRGB               // 24-bit True Color
)

type Context

type Context struct {
	Width  int
	Height int
	// contains filtered or unexported fields
}

Context gives an app controlled access to runtime state.

func (*Context) CopyToClipboard

func (c *Context) CopyToClipboard(text string) error

CopyToClipboard copies text to the system clipboard via the terminal.

func (*Context) Post

func (c *Context) Post(fn func(*Context))

Post schedules fn to run on the program's event loop.

Post may be called safely from any goroutine. The function runs later in the same context as Update and Draw, so it may safely modify application state.

func (*Context) Quit

func (c *Context) Quit()

Quit asks the program loop to stop after the current event is handled.

func (*Context) RequestFrame

func (c *Context) RequestFrame(fps int)

RequestFrame schedules a FrameEvent for a future animation frame.

It must be called from the program's event loop, such as from Init, Update, or a callback passed to Post. To request a frame from another goroutine, call Post and request the frame from its callback.

The application should call RequestFrame again from the FrameEvent handler if more frames are needed.

For example, RequestFrame(30) means "send me one FrameEvent about 1/30 second from now".

func (*Context) Size

func (c *Context) Size() Size

Size returns the current terminal size.

type Event

type Event interface {
	// contains filtered or unexported methods
}

Event is a value emitted by the terminal or runtime.

type Frame

type Frame struct {
	// contains filtered or unexported fields
}

Frame is a drawable grid of terminal cells.

func NewFrame

func NewFrame(w, h int) Frame

func (*Frame) Box

func (f *Frame) Box(r Rect, s Style)

Box draws a single-line box around r. Drawing is clipped to the frame.

func (*Frame) Cell

func (f *Frame) Cell(x, y int) Cell

func (*Frame) Clear

func (f *Frame) Clear()

Clear fills the frame with spaces using the default style.

func (*Frame) Fill

func (f *Frame) Fill(r Rect, ch rune, s Style)

Fill fills r with ch and s. Drawing is clipped to the frame.

func (*Frame) Set

func (f *Frame) Set(x, y int, ch rune, s Style)

Set writes one cell. Writes outside the frame are ignored. If ch is wide (e.g. CJK, width 2), the following cell(s) on the same row are marked as Continuation cells with the same style.

func (*Frame) Size

func (f *Frame) Size() Size

Size returns the frame size.

func (*Frame) Write

func (f *Frame) Write(x, y int, text string, s Style)

Write writes text starting at x/y. Text is clipped to the frame. Wide characters advance the column position by their display width.

type FrameEvent

type FrameEvent struct {
	Time time.Time
}

FrameEvent represents a timed redraw event. It only presents on-demand

type Key

type Key int

Key identifies non-text keyboard keys.

const (
	KeyUnknown Key = iota
	KeyRune
	KeyEsc
	KeyEnter
	KeyBackspace
	KeyTab
	KeyUp
	KeyDown
	KeyLeft
	KeyRight
	KeyHome
	KeyEnd
	KeyPgUp
	KeyPgDown
	KeyDelete
)

type KeyEvent

type KeyEvent struct {
	Key  Key
	Rune rune
	Mod  Mod
}

KeyEvent represents a keyboard input event.

func (KeyEvent) String

func (k KeyEvent) String() string

String returns a human-readable representation of the key event, including modifiers. Examples: "ctrl+a", "shift+enter", "esc".

type Mod

type Mod uint8

Mod stores keyboard or mouse modifiers.

const (
	ModNone Mod = 0
	ModCtrl Mod = 1 << iota
	ModAlt
	ModShift
	ModMeta // With Kitty keyboard protocol enabled, Kitty terminal reports Command key on macOS
)

type MouseAction

type MouseAction int

MouseAction identifies a mouse action.

const (
	MousePress MouseAction = iota
	MouseRelease
	MouseDrag
)

type MouseButton

type MouseButton int

MouseButton identifies a mouse button.

const (
	MouseNone MouseButton = iota
	MouseLeft
	MouseMiddle
	MouseRight
	MouseWheelUp
	MouseWheelDown
)

type MouseEvent

type MouseEvent struct {
	X      int // starts from 0
	Y      int // starts from 0
	Button MouseButton
	Action MouseAction
	Mod    Mod
}

MouseEvent represents a terminal mouse event.

func (MouseEvent) String

func (m MouseEvent) String() string

String returns a human-readable representation of the mouse event.

type Option

type Option func(*Options)

Option changes Program options.

func WithAltScreen

func WithAltScreen(v bool) Option

WithAltScreen enables or disables the alternate terminal screen.

func WithBracketedPaste

func WithBracketedPaste(v bool) Option

WithBracketedPaste enables or disables bracketed paste mode (\x1b[?2004h).

func WithKitty

func WithKitty(v bool) Option

WithKitty enables or disables kitty keyboard protocol.

func WithMouse

func WithMouse(v bool) Option

WithMouse enables or disables terminal mouse reporting.

type Options

type Options struct {
	AltScreen      bool
	Mouse          bool
	Kitty          bool // kitty keyboard protocol
	BracketedPaste bool
}

Options configures a Program.

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns the default Program options.

type PasteEndEvent

type PasteEndEvent struct{}

type PasteStartEvent

type PasteStartEvent struct{}

type Point

type Point struct {
	X int
	Y int
}

Point stores an x/y coordinate in terminal cells.

type Program

type Program struct {
	// contains filtered or unexported fields
}

Program owns the terminal lifecycle and event loop.

func New

func New(app App, opts ...Option) *Program

New creates a Program.

func (*Program) CopyToClipboard

func (p *Program) CopyToClipboard(text string) error

CopyToClipboard copies text to the system clipboard via the terminal.

func (*Program) Run

func (p *Program) Run() error

Run starts the terminal program and blocks until the app quits or an error occurs.

type Rect

type Rect struct {
	X int
	Y int
	W int
	H int
}

Rect stores a rectangle in terminal cells.

func Center

func Center(r Rect, w, h int) Rect

Center returns a w by h rectangle centered inside r.

func (Rect) Bottom

func (r Rect) Bottom() int

Bottom returns the first y coordinate after r.

func (Rect) Contains

func (r Rect) Contains(p Point) bool

Contains reports whether p is inside r.

func (Rect) Inset

func (r Rect) Inset(n int) Rect

Inset returns r with every edge moved inward by n cells.

func (Rect) Right

func (r Rect) Right() int

Right returns the first x coordinate after r.

type ResizeEvent

type ResizeEvent struct {
	Width  int
	Height int
}

ResizeEvent represents a terminal size change.

type Screen

type Screen struct {
	// contains filtered or unexported fields
}

Screen renders frames to a terminal output stream.

func NewScreen

func NewScreen(out io.Writer, w, h int) *Screen

NewScreen creates a screen with the given size.

func (*Screen) Flush

func (s *Screen) Flush() error

Flush writes the full frame to the output stream.

func (*Screen) Frame

func (s *Screen) Frame() *Frame

Frame returns the next drawable frame.

func (*Screen) Resize

func (s *Screen) Resize(w, h int)

Resize changes the screen size and clears stored frames.

type Size

type Size struct {
	Width  int
	Height int
}

Size stores a width and height in terminal cells.

type Style

type Style struct {
	Fg   Color
	Bg   Color
	Attr Attr
}

Style stores foreground, background, and text attributes.

func NewStyle

func NewStyle() Style

NewStyle returns the default terminal style.

func (Style) Background

func (s Style) Background(c Color) Style

Background returns s with a background color.

func (Style) Bold

func (s Style) Bold() Style

Bold returns s with bold text.

func (Style) Dim

func (s Style) Dim() Style

Dim returns s with dim text.

func (Style) Foreground

func (s Style) Foreground(c Color) Style

Foreground returns s with a foreground color.

func (Style) Italic

func (s Style) Italic() Style

Italic returns s with italic text

func (Style) Reverse

func (s Style) Reverse() Style

Reverse returns s with foreground and background reversed by the terminal.

func (Style) Underline

func (s Style) Underline() Style

Underline returns s with underlined text.

type Terminal

type Terminal interface {
	Enter() error
	Leave() error
	ReadEvent() (Event, error)
	Size() (Size, error)
	CopyToClipboard(text string) error
}

Terminal controls the user's terminal.

Directories

Path Synopsis
example
bouncer command
counter command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL