core

package
v0.0.9 Latest Latest
Warning

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

 Go to latest Published: Mar 26, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package core implements Frog's terminal runtime.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ColorBlack         = Ansi16(NamedBlack, false)
	ColorRed           = Ansi16(NamedRed, false)
	ColorGreen         = Ansi16(NamedGreen, false)
	ColorYellow        = Ansi16(NamedYellow, false)
	ColorBlue          = Ansi16(NamedBlue, false)
	ColorMagenta       = Ansi16(NamedMagenta, false)
	ColorCyan          = Ansi16(NamedCyan, false)
	ColorWhite         = Ansi16(NamedWhite, false)
	ColorBrightBlack   = Ansi16(NamedBlack, true)
	ColorBrightRed     = Ansi16(NamedRed, true)
	ColorBrightGreen   = Ansi16(NamedGreen, true)
	ColorBrightYellow  = Ansi16(NamedYellow, true)
	ColorBrightBlue    = Ansi16(NamedBlue, true)
	ColorBrightMagenta = Ansi16(NamedMagenta, true)
	ColorBrightCyan    = Ansi16(NamedCyan, true)
	ColorBrightWhite   = Ansi16(NamedWhite, true)
)

Functions

func Center added in v0.0.3 

func Center(block string, boxW, boxH int) string

Center places a block in the middle of a virtual box.

func Colorize added in v0.0.3 

func Colorize(text string, fg *Color, bg *Color, bold bool) string

func PlaceBlock added in v0.0.3 

func PlaceBlock(block string, boxW, boxH int, h AlignH, v AlignV) string

PlaceBlock aligns a multi-line block inside a virtual box.

func RenderHelpOverlay added in v0.0.9 

func RenderHelpOverlay(km *KeyMap, width, height int) string

RenderHelpOverlay renders a centered help legend.

func StripANSI added in v0.0.3 

func StripANSI(s string) string

StripANSI removes SGR sequences from a string.

Types

type AlignH added in v0.0.3 

type AlignH int

AlignH controls horizontal block alignment. 

const (
	AlignLeft AlignH = iota
	AlignCenter
	AlignRight
)

type AlignV added in v0.0.3 

type AlignV int

AlignV controls vertical block alignment. 

const (
	AlignTop AlignV = iota
	AlignMiddle
	AlignBottom
)

type Cmd added in v0.0.2 

type Cmd func() Msg

Cmd represents an async action that eventually returns a Msg.

func Batch added in v0.0.2 

func Batch(cmds ...Cmd) Cmd

Batch executes commands in order and returns the first produced message. (Subsequent scheduling is up to the Update loop.)

func Nil added in v0.0.2 

func Nil() Cmd

Nil returns no command.

func Quit added in v0.0.2 

func Quit() Cmd

Quit requests a graceful termination.

func Tick added in v0.0.2 

func Tick(d time.Duration) Cmd

Tick emits a TickMsg after d (min 1ms).

type Color added in v0.0.3 

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

func ANSI256 added in v0.0.3 

func ANSI256(n uint8) Color

func Ansi16 added in v0.0.3 

func Ansi16(name NamedColor, bright bool) Color

func RGB added in v0.0.3 

func RGB(r, g, b uint8) Color

type ColorProfile added in v0.0.3 

type ColorProfile int
const (
	ColorAuto ColorProfile = iota
	ColorNone
	ColorANSI16
	ColorANSI256
	ColorTrueColor
)

type Error added in v0.0.9 

type Error struct {
	Code   ErrorCode
	Op     string
	Detail string
	Err    error
}

Error is Frog's structured runtime error.

func (*Error) Error added in v0.0.9 

func (e *Error) Error() string

func (*Error) Unwrap added in v0.0.9 

func (e *Error) Unwrap() error

type ErrorCode added in v0.0.9 

type ErrorCode string

ErrorCode identifies a runtime failure in Frog's core loop. 

const (
	ErrNilModel       ErrorCode = "FROG201"
	ErrNilRenderer    ErrorCode = "FROG202"
	ErrRawMode        ErrorCode = "FROG203"
	ErrInitFailed     ErrorCode = "FROG204"
	ErrViewFailed     ErrorCode = "FROG205"
	ErrUpdateFailed   ErrorCode = "FROG206"
	ErrCommandFailed  ErrorCode = "FROG207"
	ErrNilUpdateModel ErrorCode = "FROG208"
)

type KeyBinding added in v0.0.9 

type KeyBinding struct {
	Keys []string // canonical key strings (case-insensitive)
	Help string   // short action label shown in help overlay
}

KeyBinding maps one or more keys to a help label.

type KeyMap added in v0.0.9 

type KeyMap struct {
	Bindings []KeyBinding
}

KeyMap is a flat list of key bindings.

func (KeyMap) Find added in v0.0.9 

func (km KeyMap) Find(k KeyMsg) (KeyBinding, bool)

Find returns the first binding that matches the given key.

type KeyMsg added in v0.0.2 

type KeyMsg struct {
	Type   KeyType
	Rune   rune   // valid when Type == KeyRune
	String string // best-effort textual/escape representation
	Alt    bool   // true if input decoder detected Alt/Meta
	Ctrl   bool   // true if control modifier was involved (e.g., Ctrl+C)
}

KeyMsg represents a keyboard event. For KeyRune, Rune and String are set. For non-printable keys, String holds the raw escape sequence (when available).

type KeyType added in v0.0.3 

type KeyType int

KeyType enumerates high-level keys recognized by the input decoder. For printable runes, Type is KeyRune and the Rune field is set. 

const (
	KeyUnknown KeyType = iota
	KeyRune
	KeyEnter
	KeyBackspace
	KeyEsc
	KeyCtrlC
	KeyUp
	KeyDown
	KeyLeft
	KeyRight
	KeyTab
	KeySpace
	KeyDelete
	KeyHome
	KeyEnd
	KeyPgUp
	KeyPgDn
	KeyQ // convenience (used in examples); treat like KeyRune('q') in user code if preferred
)

func (KeyType) String added in v0.0.9 

func (t KeyType) String() string

String returns a stable textual name for the key type (for logging/debug).

type Logger added in v0.0.3 

type Logger interface {
	Debugf(format string, args ...any)
	Infof(format string, args ...any)
	Warnf(format string, args ...any)
	Errorf(format string, args ...any)
}

Logger is the leveled logging interface used across the core runtime. It is intentionally minimal to keep call sites lightweight and mock-friendly.

type Model added in v0.0.2 

type Model interface {
	Init() Cmd
	Update(Msg) (Model, Cmd)
	View() string
}

Update processes a Msg and returns the next state plus an optional Cmd. View must be side-effect free and return the current UI as a string.

Tip: Use a consistent receiver style (pointer or value) across all methods to avoid FROG109 warnings from the validator.

type MouseAction added in v0.0.5 

type MouseAction int

MouseAction identifies the action associated with a mouse event. 

const (
	MousePress MouseAction = iota
	MouseRelease
	MouseDrag
	MouseWheel
)

func (MouseAction) String added in v0.0.9 

func (a MouseAction) String() string

String returns a stable textual name for the action.

type MouseButton added in v0.0.5 

type MouseButton int

MouseButton identifies the logical mouse button or wheel direction. 

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

func (MouseButton) String added in v0.0.9 

func (b MouseButton) String() string

String returns a stable textual name for the button.

type MouseMsg added in v0.0.5 

type MouseMsg struct {
	Button MouseButton
	Action MouseAction
	X, Y   int // 1-based terminal coords (col=X, row=Y)
	Alt    bool
	Ctrl   bool
	Shift  bool
}

MouseMsg represents a mouse event using SGR reporting (1006). X/Y are 1-based terminal coordinates (column/row).

type Msg added in v0.0.2 

type Msg interface{}

Msg is a marker interface for all messages delivered to a Model's Update. Any concrete type can be a message. The framework ships a standard set: - KeyMsg: keyboard input (including special keys) - MouseMsg: mouse input via SGR - PasteMsg: bracketed paste payload - TickMsg: time-based trigger - ResizeMsg: terminal size changes - QuitMsg: request to terminate the app

type NamedColor added in v0.0.3 

type NamedColor uint8
const (
	NamedBlack NamedColor = iota
	NamedRed
	NamedGreen
	NamedYellow
	NamedBlue
	NamedMagenta
	NamedCyan
	NamedWhite
)

type Option added in v0.0.2 

type Option func(*Session)

Option configures a Session at construction time.

func WithAltScreen added in v0.0.3 

func WithAltScreen() Option

WithAltScreen enables the alternate terminal screen.

func WithBracketedPaste added in v0.0.5 

func WithBracketedPaste() Option

WithBracketedPaste enables bracketed paste (ESC[200~ .. ESC[201~]).

func WithIn added in v0.0.4 

func WithIn(r io.Reader) Option

WithIn overrides the input reader (default: os.Stdin).

func WithLogger added in v0.0.4 

func WithLogger(l Logger) Option

WithLogger sets a custom logger.

func WithMouse added in v0.0.5 

func WithMouse() Option

WithMouse enables SGR mouse reporting (1000/1002/1006 modes).

func WithMsgBuffer added in v0.0.3 

func WithMsgBuffer(n int) Option

WithMsgBuffer sets the size of the internal message channel buffer (default 64).

func WithNonInteractive added in v0.0.4 

func WithNonInteractive() Option

WithNonInteractive disables raw mode and the input loop.

func WithOut added in v0.0.4 

func WithOut(w io.Writer) Option

WithOut overrides the output writer (default: os.Stdout).

func WithRenderer added in v0.0.2 

func WithRenderer(r Renderer) Option

WithRenderer sets a custom renderer.

func WithResizeInterval added in v0.0.4 

func WithResizeInterval(d time.Duration) Option

WithResizeInterval sets the polling interval for terminal size changes (default 150ms).

type PasteMsg added in v0.0.5 

type PasteMsg struct {
	Text string
}

PasteMsg is emitted when bracketed paste is enabled and a paste operation completes. Text contains the full pasted payload (up to an internal cap).

type QuitMsg added in v0.0.2 

type QuitMsg struct{}

QuitMsg requests the app to terminate. Models can emit this to exit cleanly.

type Renderer added in v0.0.2 

type Renderer interface {
	// Clear clears the target before rendering.
	Clear()
	// Render writes a frame to the target.
	Render(s string)
	// Close restores terminal state and releases resources.
	Close()
}

Renderer renders frames to an output target.

func NewRenderer added in v0.0.3 

func NewRenderer(out io.Writer, opts ...RendererOption) Renderer

NewRenderer returns an ANSI renderer bound to out.

func NewThrottledRenderer added in v0.0.9 

func NewThrottledRenderer(out io.Writer, fps int, opts ...RendererOption) Renderer

NewThrottledRenderer returns a Renderer with FPS cap. If fps <= 0 the base renderer is returned as-is.

type RendererOption added in v0.0.3 

type RendererOption func(*ansiRenderer)

RendererOption configures an ANSI renderer.

func WithColorProfile added in v0.0.3 

func WithColorProfile(p ColorProfile) RendererOption

WithColorProfile forces a color profile.

func WithDiff added in v0.0.3 

func WithDiff(enabled bool) RendererOption

WithDiff enables or disables line diffing.

type ResizeMsg added in v0.0.2 

type ResizeMsg struct {
	Width, Height int
}

ResizeMsg is emitted when the terminal size changes. Coordinates are in cells.

type Session added in v0.0.2 

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

Session runs a Model, coordinating input, rendering and lifecycle.

func NewSession added in v0.0.2 

func NewSession(m Model, opts ...Option) *Session

NewSession creates a session with a background context.

func NewSessionWithContext added in v0.0.4 

func NewSessionWithContext(ctx context.Context, m Model, opts ...Option) *Session

NewSessionWithContext creates a session bound to ctx.

func (*Session) Quit added in v0.0.3 

func (p *Session) Quit()

Quit requests a graceful shutdown by sending a QuitMsg into the event loop.

func (*Session) Run added in v0.0.2 

func (p *Session) Run() (runErr error)

Run starts the session and blocks until completion or error.

func (*Session) Send added in v0.0.2 

func (p *Session) Send(msg Msg)

Send injects a message into the session.

type Style added in v0.0.3 

type Style struct {
	Bold      bool
	Faint     bool
	Italic    bool
	Underline bool
	Blink     bool
	Reverse   bool
	Strike    bool
	// contains filtered or unexported fields
}

func NewStyle added in v0.0.3 

func NewStyle() Style

func (Style) Bg added in v0.0.3 

func (s Style) Bg(c Color) Style

func (Style) Blinking added in v0.0.3 

func (s Style) Blinking() Style

func (Style) Bolded added in v0.0.3 

func (s Style) Bolded() Style

func (Style) Fainted added in v0.0.3 

func (s Style) Fainted() Style

func (Style) Fg added in v0.0.3 

func (s Style) Fg(c Color) Style

func (Style) Italicized added in v0.0.3 

func (s Style) Italicized() Style

func (Style) Render added in v0.0.3 

func (s Style) Render(text string) string

Render wraps text in ANSI SGR codes.

func (Style) Reversed added in v0.0.3 

func (s Style) Reversed() Style

func (Style) Struck added in v0.0.3 

func (s Style) Struck() Style

func (Style) Underlined added in v0.0.3 

func (s Style) Underlined() Style

type TickMsg added in v0.0.2 

type TickMsg struct{ At time.Time }

TickMsg is emitted by a Cmd created with Tick/After-like helpers. At contains the emission time. Models can schedule further Ticks in Update.

Source Files

View all Source files

Directories

Path Synopsis
Package validate inspects Frog models before runtime.
 Package validate inspects Frog models before runtime.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.