frog

README

Frog

Frog is the core TUI framework of the Pondworks ecosystem. It provides the runtime loop, renderer, input decoding, validation, and layout/style primitives for terminal apps in Go.

Installation

go get github.com/pondworks-lib/frog@latest

Quick Start

package main

import (
	"fmt"

	"github.com/pondworks-lib/frog"
)

type helloModel struct {
	count int
}

func (m helloModel) Init() frog.Cmd { return nil }

func (m helloModel) Update(msg frog.Msg) (frog.Model, frog.Cmd) {
	switch msg := msg.(type) {
	case frog.KeyMsg:
		if msg.String == "q" {
			return m, frog.Quit()
		}
		m.count++
	}
	return m, nil
}

func (m helloModel) View() string {
	return fmt.Sprintf("Hello Frog!\n\nKeys pressed: %d\n\nPress 'q' to quit.", m.count)
}

func main() {
	if err := frog.Run(helloModel{}); err != nil {
		panic(err)
	}
}

Features

• MUV architecture: Model, Update, View.
• Standard messages: KeyMsg, TickMsg, QuitMsg, ResizeMsg, MouseMsg, PasteMsg.
• Commands: Cmd, Tick, Quit, Nil.
• Renderer: ANSI renderer with diff mode and safe full repaint fallback on wrapped frames.
• Input: raw mode, UTF-8 decoding, escape sequences, mouse, bracketed paste.
• Styling: ANSI16, ANSI256, TrueColor, chained Style.
• Layout: Center, PlaceBlock, Align*.
• Sessions: Run, RunContext, NewApp, NewAppWithContext.
• Runtime options: alt screen, mouse, bracketed paste, custom renderer, logger, non-interactive mode.
• Validation: InspectModel, ValidateModel, structured FROG... issue codes.
• Runtime errors: structured FROG2.. errors from the session loop.

Examples

Examples live in example/0.0.9. The set includes basics, input demos, rendering demos, app-style demos, and errors/ for validator testing.

Status

• Frog is in pre-release stage (v0.0.9).
• The goal of v0.0.9 is to make the current surface smaller, clearer, and much closer to the v0.1.0 freeze.

Toward v0.1.0

• Stabilize the core runtime, renderer, input, validation and layout/style helpers.
• Freeze the public API for frog at v0.1.0.
• Build higher-level packages on top of the frozen core:
  • lily: widgets such as list, table, text input, form, progress.
  • ripple: event bus / reactive orchestration on top of Frog.
  • future packages only after the base API has stopped moving.

Notes

pad and splash were merged into Frog starting in v0.0.3. For now, layout and styling remain in this repository until the base API is frozen.

Documentation

Index

• Constants
• Variables
• func NewRenderer(out io.Writer, opts ...RendererOption) core.Renderer
• func NewThrottledRenderer(out io.Writer, fps int, opts ...core.RendererOption) core.Renderer
• func RenderKeyHelp(km *core.KeyMap, width, height int) string
• func Run(m Model, opts ...Option) error
• func RunContext(ctx context.Context, m Model, opts ...Option) error
• type AlignH
• type AlignV
• type App
  • func NewApp(m Model, opts ...Option) *App
  • func NewAppWithContext(ctx context.Context, m Model, opts ...Option) *App
• type Cmd
• type Color
• type ColorProfile
• type Error
• type ErrorCode
• type KeyMsg
• type KeyType
• type Logger
• type Model
• type MouseAction
• type MouseButton
• type MouseMsg
• type Msg
• type Option
• type PasteMsg
• type QuitMsg
• type RendererOption
• type ResizeMsg
• type Style
• type TickMsg
• type ValidationCode
• type ValidationIssue
• type ValidationReport
• type ValidationSeverity

Constants

const (
	KeyUnknown   = core.KeyUnknown
	KeyRune      = core.KeyRune
	KeyEnter     = core.KeyEnter
	KeyBackspace = core.KeyBackspace
	KeyEsc       = core.KeyEsc
	KeyCtrlC     = core.KeyCtrlC
	KeyUp        = core.KeyUp
	KeyDown      = core.KeyDown
	KeyLeft      = core.KeyLeft
	KeyRight     = core.KeyRight
	KeyTab       = core.KeyTab
	KeySpace     = core.KeySpace
	KeyDelete    = core.KeyDelete
	KeyHome      = core.KeyHome
	KeyEnd       = core.KeyEnd
	KeyPgUp      = core.KeyPgUp
	KeyPgDn      = core.KeyPgDn
	KeyQ         = core.KeyQ
)

Key constants

const (
	MouseUnknown   = core.MouseUnknown
	MouseLeft      = core.MouseLeft
	MouseMiddle    = core.MouseMiddle
	MouseRight     = core.MouseRight
	MouseWheelUp   = core.MouseWheelUp
	MouseWheelDown = core.MouseWheelDown
)

Mouse constants

const (
	ErrNilModel       = core.ErrNilModel
	ErrNilRenderer    = core.ErrNilRenderer
	ErrRawMode        = core.ErrRawMode
	ErrInitFailed     = core.ErrInitFailed
	ErrViewFailed     = core.ErrViewFailed
	ErrUpdateFailed   = core.ErrUpdateFailed
	ErrCommandFailed  = core.ErrCommandFailed
	ErrNilUpdateModel = core.ErrNilUpdateModel
)

Runtime error codes

const (
	ValidationNilModel           = validate.CodeNilModel
	ValidationMissingView        = validate.CodeMissingView
	ValidationEmptyView          = validate.CodeEmptyView
	ValidationViewNotString      = validate.CodeViewNotString
	ValidationViewHasBadRunes    = validate.CodeViewHasBadRunes
	ValidationViewPanic          = validate.CodeViewPanic
	ValidationMissingUpdate      = validate.CodeMissingUpdate
	ValidationBadUpdateSignature = validate.CodeBadUpdateSignature
	ValidationMissingInit        = validate.CodeMissingInit
	ValidationBadInitSignature   = validate.CodeBadInitSignature
	ValidationUpdateNilModel     = validate.CodeUpdateNilModel
	ValidationViewVeryLarge      = validate.CodeViewVeryLarge
	ValidationViewSuspicious     = validate.CodeViewSuspicious
	ValidationNonExportedType    = validate.CodeNonExportedType
	ValidationSlowView           = validate.CodeSlowView
	ValidationSlowInit           = validate.CodeSlowInit
	ValidationHasNoMethods       = validate.CodeHasNoMethods
	ValidationUpdateNotMethod    = validate.CodeUpdateNotMethod
	ValidationViewNotMethod      = validate.CodeViewNotMethod
	ValidationReceiverMismatch   = validate.CodeReceiverMismatch
	ValidationViewControlCodes   = validate.CodeViewControlCodes
)

Validation issue codes

const (
	MousePress   = core.MousePress
	MouseRelease = core.MouseRelease
	MouseDrag    = core.MouseDrag
	MouseWheel   = core.MouseWheel
)

const (
	ColorAuto      = core.ColorAuto
	ColorNone      = core.ColorNone
	ColorANSI16    = core.ColorANSI16
	ColorANSI256   = core.ColorANSI256
	ColorTrueColor = core.ColorTrueColor
)

Color profile constants

const (
	AlignLeft   = core.AlignLeft
	AlignCenter = core.AlignCenter
	AlignRight  = core.AlignRight
	AlignTop    = core.AlignTop
	AlignMiddle = core.AlignMiddle
	AlignBottom = core.AlignBottom
)

Layout helpers.

Variables

var (
	ColorBlack         = core.ColorBlack
	ColorRed           = core.ColorRed
	ColorGreen         = core.ColorGreen
	ColorYellow        = core.ColorYellow
	ColorBlue          = core.ColorBlue
	ColorMagenta       = core.ColorMagenta
	ColorCyan          = core.ColorCyan
	ColorWhite         = core.ColorWhite
	ColorBrightBlack   = core.ColorBrightBlack
	ColorBrightRed     = core.ColorBrightRed
	ColorBrightGreen   = core.ColorBrightGreen
	ColorBrightYellow  = core.ColorBrightYellow
	ColorBrightBlue    = core.ColorBrightBlue
	ColorBrightMagenta = core.ColorBrightMagenta
	ColorBrightCyan    = core.ColorBrightCyan
	ColorBrightWhite   = core.ColorBrightWhite
)

Named colors (16-color)

var (
	NewStyle  = core.NewStyle
	ANSI256   = core.ANSI256
	RGB       = core.RGB
	Colorize  = core.Colorize
	StripANSI = core.StripANSI

	InspectModel  = validate.InspectModel
	ValidateModel = validate.ValidateModel
)

Style functions.

var (
	Tick               = core.Tick
	Quit               = core.Quit
	Nil                = core.Nil
	WithRenderer       = core.WithRenderer
	WithAltScreen      = core.WithAltScreen
	WithMsgBuffer      = core.WithMsgBuffer
	WithOut            = core.WithOut
	WithIn             = core.WithIn
	WithResizeInterval = core.WithResizeInterval
	WithNonInteractive = core.WithNonInteractive
	WithLogger         = core.WithLogger
	WithMouse          = core.WithMouse
	WithBracketedPaste = core.WithBracketedPaste
)

Session options

var (
	WithDiff         = core.WithDiff
	WithColorProfile = core.WithColorProfile
)

var (
	Center     = core.Center
	PlaceBlock = core.PlaceBlock
)

Functions

func NewRenderer

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

Renderer helpers.

func NewThrottledRenderer

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

FPS-throttled renderer.

func RenderKeyHelp

func RenderKeyHelp(km *core.KeyMap, width, height int) string

Help overlay.

func Run

func Run(m Model, opts ...Option) error

func RunContext

func RunContext(ctx context.Context, m Model, opts ...Option) error

Types

type AlignH

type AlignH = core.AlignH

Layout.

type AlignV

type AlignV = core.AlignV

type App

type App = core.Session

func NewApp

func NewApp(m Model, opts ...Option) *App

App functions.

func NewAppWithContext

func NewAppWithContext(ctx context.Context, m Model, opts ...Option) *App

Context-aware entrypoints.

type Cmd

type Cmd = core.Cmd

type Color

type Color = core.Color

type ColorProfile

type ColorProfile = core.ColorProfile

type Error

type Error = core.Error

Structured runtime and validation errors.

type ErrorCode

type ErrorCode = core.ErrorCode

type KeyMsg

type KeyMsg = core.KeyMsg

type KeyType

type KeyType = core.KeyType

type Logger

type Logger = core.Logger

Logger.

type Model

type Model = core.Model

Core types.

type MouseAction

type MouseAction = core.MouseAction

type MouseButton

type MouseButton = core.MouseButton

type MouseMsg

type MouseMsg = core.MouseMsg

Mouse and paste messages.

type Msg

type Msg = core.Msg

type Option

type Option = core.Option

type PasteMsg

type PasteMsg = core.PasteMsg

type QuitMsg

type QuitMsg = core.QuitMsg

type RendererOption

type RendererOption = core.RendererOption

Renderer options.

type ResizeMsg

type ResizeMsg = core.ResizeMsg

type Style

type Style = core.Style

Styling.

type TickMsg

type TickMsg = core.TickMsg

type ValidationCode

type ValidationCode = validate.Code

type ValidationIssue

type ValidationIssue = validate.Issue

type ValidationReport

type ValidationReport = validate.Report

type ValidationSeverity

type ValidationSeverity = validate.Severity