bubbletea/tea.go

731 lines
18 KiB
Go
Raw Permalink Normal View History

2020-07-30 11:29:20 -04:00
// Package tea provides a framework for building rich terminal user interfaces
// based on the paradigms of The Elm Architecture. It's well-suited for simple
// and complex terminal applications, either inline, full-window, or a mix of
// both. It's been battle-tested in several large projects and is
// production-ready.
2020-07-29 20:49:20 -04:00
//
// A tutorial is available at https://github.com/charmbracelet/bubbletea/tree/master/tutorials
//
// Example programs can be found at https://github.com/charmbracelet/bubbletea/tree/master/examples
package tea
2020-01-10 16:02:04 -05:00
import (
2021-01-11 16:33:14 -05:00
"context"
"errors"
"fmt"
"io"
"os"
2021-01-11 16:33:14 -05:00
"os/signal"
"runtime/debug"
"sync"
"sync/atomic"
2021-01-11 16:33:14 -05:00
"syscall"
2020-01-31 07:47:36 -05:00
"github.com/containerd/console"
isatty "github.com/mattn/go-isatty"
"github.com/muesli/cancelreader"
"github.com/muesli/termenv"
2023-02-06 14:44:53 -05:00
"golang.org/x/sync/errgroup"
2020-01-10 16:02:04 -05:00
)
// ErrProgramKilled is returned by [Program.Run] when the program got killed.
var ErrProgramKilled = errors.New("program was killed")
2021-09-28 13:54:25 -04:00
// Msg contain data from the result of a IO operation. Msgs trigger the update
// function and, henceforth, the UI.
2020-01-10 16:02:04 -05:00
type Msg interface{}
2021-09-28 13:54:25 -04:00
// Model contains the program's state as well as its core functions.
type Model interface {
// Init is the first function that will be called. It returns an optional
// initial command. To not perform an initial command return nil.
Init() Cmd
// Update is called when a message is received. Use it to inspect messages
// and, in response, update the model and/or send a command.
Update(Msg) (Model, Cmd)
// View renders the program's UI, which is just a string. The view is
// rendered after every Update.
View() string
}
2020-01-10 16:02:04 -05:00
2021-09-28 13:54:25 -04:00
// Cmd is an IO operation that returns a message when it's complete. If it's
// nil it's considered a no-op. Use it for things like HTTP requests, timers,
// saving and loading from disk, and so on.
2020-06-24 12:14:35 -04:00
//
2021-09-28 13:54:25 -04:00
// Note that there's almost never a reason to use a command to send a message
// to another part of your program. That can almost always be done in the
// update function.
type Cmd func() Msg
type inputType int
const (
defaultInput inputType = iota
ttyInput
customInput
)
// String implements the stringer interface for [inputType]. It is inteded to
// be used in testing.
func (i inputType) String() string {
return [...]string{
"default input",
"tty input",
"custom input",
}[i]
}
// Options to customize the program during its initialization. These are
// generally set with ProgramOptions.
//
// The options here are treated as bits.
type startupOptions int16
2021-07-29 15:43:03 -04:00
func (s startupOptions) has(option startupOptions) bool {
return s&option != 0
}
const (
withAltScreen startupOptions = 1 << iota
withMouseCellMotion
withMouseAllMotion
withANSICompressor
withoutSignalHandler
2022-10-07 15:48:50 -04:00
// Catching panics is incredibly useful for restoring the terminal to a
// usable state after a panic occurs. When this is set, Bubble Tea will
// recover from panics, print the stack trace, and disable raw mode. This
// feature is on by default.
withoutCatchPanics
withoutBracketedPaste
)
// handlers manages series of channels returned by various processes. It allows
// us to wait for those processes to terminate before exiting the program.
type handlers []chan struct{}
// Adds a channel to the list of handlers. We wait for all handlers to terminate
// gracefully on shutdown.
func (h *handlers) add(ch chan struct{}) {
*h = append(*h, ch)
}
// shutdown waits for all handlers to terminate.
func (h handlers) shutdown() {
var wg sync.WaitGroup
for _, ch := range h {
wg.Add(1)
go func(ch chan struct{}) {
<-ch
wg.Done()
}(ch)
}
wg.Wait()
}
// Program is a terminal user interface.
2020-01-10 16:02:04 -05:00
type Program struct {
initialModel Model
// Configuration options that will set as the program is initializing,
// treated as bits. These options can be set via various ProgramOptions.
startupOptions startupOptions
inputType inputType
ctx context.Context
cancel context.CancelFunc
msgs chan Msg
errs chan error
finished chan struct{}
2022-10-07 15:48:50 -04:00
// where to send output, this will usually be os.Stdout.
output *termenv.Output
restoreOutput func() error
2022-10-07 15:48:50 -04:00
renderer renderer
2022-10-07 15:48:50 -04:00
// where to read inputs from, this will usually be os.Stdin.
input io.Reader
cancelReader cancelreader.CancelReader
2022-10-07 17:29:50 -04:00
readLoopDone chan struct{}
2022-10-07 15:48:50 -04:00
console console.Console
2021-01-11 16:33:14 -05:00
2022-10-07 17:29:50 -04:00
// was the altscreen active before releasing the terminal?
altScreenWasActive bool
ignoreSignals uint32
bpWasActive bool // was the bracketed paste mode active before releasing the terminal?
// Stores the original reference to stdin for cases where input is not a
// TTY on windows and we've automatically opened CONIN$ to receive input.
// When the program exits this will be restored.
//
// Lint ignore note: the linter will find false positive on unix systems
// as this value only comes into play on Windows, hence the ignore comment
// below.
windowsStdin *os.File //nolint:golint,structcheck,unused
filter func(Model, Msg) Msg
// fps is the frames per second we should set on the renderer, if
// applicable,
fps int
2020-01-10 16:02:04 -05:00
}
2020-07-29 20:49:20 -04:00
// Quit is a special command that tells the Bubble Tea program to exit.
func Quit() Msg {
return QuitMsg{}
2020-01-10 16:02:04 -05:00
}
// QuitMsg signals that the program should quit. You can send a QuitMsg with
// Quit.
type QuitMsg struct{}
2020-01-10 16:02:04 -05:00
// NewProgram creates a new Program.
func NewProgram(model Model, opts ...ProgramOption) *Program {
p := &Program{
initialModel: model,
msgs: make(chan Msg),
2020-01-10 16:02:04 -05:00
}
// Apply all options to the program.
for _, opt := range opts {
opt(p)
}
// A context can be provided with a ProgramOption, but if none was provided
// we'll use the default background context.
if p.ctx == nil {
p.ctx = context.Background()
}
// Initialize context and teardown channel.
p.ctx, p.cancel = context.WithCancel(p.ctx)
// if no output was set, set it to stdout
if p.output == nil {
p.output = termenv.DefaultOutput()
// cache detected color values
termenv.WithColorCache(true)(p.output)
}
p.restoreOutput, _ = termenv.EnableVirtualTerminalProcessing(p.output)
return p
2020-01-10 16:02:04 -05:00
}
func (p *Program) handleSignals() chan struct{} {
ch := make(chan struct{})
// Listen for SIGINT and SIGTERM.
//
// In most cases ^C will not send an interrupt because the terminal will be
// in raw mode and ^C will be captured as a keystroke and sent along to
// Program.Update as a KeyMsg. When input is not a TTY, however, ^C will be
// caught here.
//
// SIGTERM is sent by unix utilities (like kill) to terminate a process.
2021-01-11 16:33:14 -05:00
go func() {
sig := make(chan os.Signal, 1)
signal.Notify(sig, syscall.SIGINT, syscall.SIGTERM)
defer func() {
signal.Stop(sig)
close(ch)
}()
2021-01-11 16:33:14 -05:00
for {
select {
case <-p.ctx.Done():
return
case <-sig:
if atomic.LoadUint32(&p.ignoreSignals) == 0 {
p.msgs <- QuitMsg{}
return
}
}
2021-01-11 16:33:14 -05:00
}
}()
return ch
}
// handleResize handles terminal resize events.
func (p *Program) handleResize() chan struct{} {
ch := make(chan struct{})
2020-01-10 16:02:04 -05:00
if f, ok := p.output.TTY().(*os.File); ok && isatty.IsTerminal(f.Fd()) {
2021-09-28 13:54:25 -04:00
// Get the initial terminal size and send it to the program.
go p.checkResize()
2021-09-28 13:54:25 -04:00
// Listen for window resizes.
go p.listenForResize(ch)
} else {
close(ch)
}
return ch
}
// handleCommands runs commands in a goroutine and sends the result to the
// program's message channel.
func (p *Program) handleCommands(cmds chan Cmd) chan struct{} {
ch := make(chan struct{})
2020-01-10 16:02:04 -05:00
go func() {
defer close(ch)
2020-01-10 16:02:04 -05:00
for {
select {
case <-p.ctx.Done():
2020-01-10 16:02:04 -05:00
return
2020-01-10 16:02:04 -05:00
case cmd := <-cmds:
if cmd == nil {
continue
2020-01-10 16:02:04 -05:00
}
// Don't wait on these goroutines, otherwise the shutdown
// latency would get too large as a Cmd can run for some time
// (e.g. tick commands that sleep for half a second). It's not
// possible to cancel them so we'll have to leak the goroutine
// until Cmd returns.
go func() {
msg := cmd() // this can be long.
p.Send(msg)
}()
2020-01-10 16:02:04 -05:00
}
}
}()
return ch
}
func (p *Program) disableMouse() {
p.renderer.disableMouseCellMotion()
p.renderer.disableMouseAllMotion()
p.renderer.disableMouseSGRMode()
}
// eventLoop is the central message loop. It receives and handles the default
// Bubble Tea messages, update the model and triggers redraws.
func (p *Program) eventLoop(model Model, cmds chan Cmd) (Model, error) {
2020-01-10 16:02:04 -05:00
for {
select {
case <-p.ctx.Done():
return model, nil
case err := <-p.errs:
return model, err
case msg := <-p.msgs:
// Filter messages.
if p.filter != nil {
msg = p.filter(model, msg)
}
if msg == nil {
continue
}
2021-09-28 13:54:25 -04:00
// Handle special internal messages.
switch msg := msg.(type) {
case QuitMsg:
return model, nil
2022-08-25 13:13:30 -04:00
case clearScreenMsg:
p.renderer.clearScreen()
case enterAltScreenMsg:
2022-10-03 18:04:05 -04:00
p.renderer.enterAltScreen()
case exitAltScreenMsg:
2022-10-03 18:04:05 -04:00
p.renderer.exitAltScreen()
case enableMouseCellMotionMsg, enableMouseAllMotionMsg:
switch msg.(type) {
case enableMouseCellMotionMsg:
p.renderer.enableMouseCellMotion()
case enableMouseAllMotionMsg:
p.renderer.enableMouseAllMotion()
}
// mouse mode (1006) is a no-op if the terminal doesn't support it.
p.renderer.enableMouseSGRMode()
case disableMouseMsg:
p.disableMouse()
case showCursorMsg:
p.renderer.showCursor()
2020-12-03 10:44:10 -05:00
case hideCursorMsg:
2022-10-03 18:04:05 -04:00
p.renderer.hideCursor()
case enableBracketedPasteMsg:
p.renderer.enableBracketedPaste()
case disableBracketedPasteMsg:
p.renderer.disableBracketedPaste()
case execMsg:
// NB: this blocks.
p.exec(msg.cmd, msg.fn)
case BatchMsg:
2022-10-03 18:04:05 -04:00
for _, cmd := range msg {
cmds <- cmd
}
continue
case sequenceMsg:
go func() {
// Execute commands one at a time, in order.
for _, cmd := range msg {
if cmd == nil {
continue
}
2023-04-04 07:18:50 -04:00
2023-02-06 14:44:53 -05:00
msg := cmd()
if batchMsg, ok := msg.(BatchMsg); ok {
g, _ := errgroup.WithContext(p.ctx)
for _, cmd := range batchMsg {
cmd := cmd
g.Go(func() error {
p.Send(cmd())
return nil
})
}
2023-04-04 07:18:50 -04:00
2023-02-06 14:44:53 -05:00
//nolint:errcheck
g.Wait() // wait for all commands from batch msg to finish
continue
}
2023-04-04 07:18:50 -04:00
p.Send(msg)
}
}()
case setWindowTitleMsg:
p.SetWindowTitle(string(msg))
2020-01-10 16:02:04 -05:00
}
2021-09-28 13:54:25 -04:00
// Process internal messages for the renderer.
if r, ok := p.renderer.(*standardRenderer); ok {
r.handleMessages(msg)
}
2020-06-23 16:11:06 -04:00
var cmd Cmd
model, cmd = model.Update(msg) // run update
cmds <- cmd // process command (if any)
p.renderer.write(model.View()) // send view to renderer
2020-01-10 16:02:04 -05:00
}
}
}
// Run initializes the program and runs its event loops, blocking until it gets
// terminated by either [Program.Quit], [Program.Kill], or its signal handler.
// Returns the final model.
func (p *Program) Run() (Model, error) {
handlers := handlers{}
cmds := make(chan Cmd)
p.errs = make(chan error)
p.finished = make(chan struct{}, 1)
defer p.cancel()
switch p.inputType {
case defaultInput:
p.input = os.Stdin
// The user has not set a custom input, so we need to check whether or
// not standard input is a terminal. If it's not, we open a new TTY for
// input. This will allow things to "just work" in cases where data was
// piped in or redirected to the application.
//
// To disable input entirely pass nil to the [WithInput] program option.
f, isFile := p.input.(*os.File)
if !isFile {
break
}
if isatty.IsTerminal(f.Fd()) {
break
}
f, err := openInputTTY()
if err != nil {
return p.initialModel, err
}
defer f.Close() //nolint:errcheck
p.input = f
case ttyInput:
// Open a new TTY, by request
f, err := openInputTTY()
if err != nil {
return p.initialModel, err
}
defer f.Close() //nolint:errcheck
p.input = f
case customInput:
// (There is nothing extra to do.)
}
// Handle signals.
if !p.startupOptions.has(withoutSignalHandler) {
handlers.add(p.handleSignals())
}
2022-10-07 15:48:50 -04:00
// Recover from panics.
if !p.startupOptions.has(withoutCatchPanics) {
defer func() {
if r := recover(); r != nil {
p.shutdown(true)
fmt.Printf("Caught panic:\n\n%s\n\nRestoring terminal...\n\n", r)
debug.PrintStack()
return
}
}()
}
// If no renderer is set use the standard one.
if p.renderer == nil {
p.renderer = newRenderer(p.output, p.startupOptions.has(withANSICompressor), p.fps)
}
// Check if output is a TTY before entering raw mode, hiding the cursor and
// so on.
if err := p.initTerminal(); err != nil {
return p.initialModel, err
}
// Honor program startup options.
if p.startupOptions&withAltScreen != 0 {
p.renderer.enterAltScreen()
}
if p.startupOptions&withoutBracketedPaste == 0 {
p.renderer.enableBracketedPaste()
}
if p.startupOptions&withMouseCellMotion != 0 {
p.renderer.enableMouseCellMotion()
p.renderer.enableMouseSGRMode()
} else if p.startupOptions&withMouseAllMotion != 0 {
p.renderer.enableMouseAllMotion()
p.renderer.enableMouseSGRMode()
}
// Initialize the program.
model := p.initialModel
if initCmd := model.Init(); initCmd != nil {
ch := make(chan struct{})
handlers.add(ch)
go func() {
defer close(ch)
select {
case cmds <- initCmd:
case <-p.ctx.Done():
}
}()
}
// Start the renderer.
p.renderer.start()
// Render the initial view.
p.renderer.write(model.View())
// Subscribe to user input.
if p.input != nil {
if err := p.initCancelReader(); err != nil {
return model, err
}
}
// Handle resize events.
handlers.add(p.handleResize())
// Process commands.
handlers.add(p.handleCommands(cmds))
// Run event loop, handle updates and draw.
model, err := p.eventLoop(model, cmds)
killed := p.ctx.Err() != nil
if killed {
err = ErrProgramKilled
} else {
// Ensure we rendered the final state of the model.
p.renderer.write(model.View())
}
// Tear down.
p.cancel()
// Check if the cancel reader has been setup before waiting and closing.
if p.cancelReader != nil {
// Wait for input loop to finish.
if p.cancelReader.Cancel() {
p.waitForReadLoop()
}
_ = p.cancelReader.Close()
}
// Wait for all handlers to finish.
handlers.shutdown()
// Restore terminal state.
p.shutdown(killed)
return model, err
}
// StartReturningModel initializes the program and runs its event loops,
// blocking until it gets terminated by either [Program.Quit], [Program.Kill],
// or its signal handler. Returns the final model.
//
// Deprecated: please use [Program.Run] instead.
func (p *Program) StartReturningModel() (Model, error) {
return p.Run()
}
// Start initializes the program and runs its event loops, blocking until it
// gets terminated by either [Program.Quit], [Program.Kill], or its signal
// handler.
//
// Deprecated: please use [Program.Run] instead.
func (p *Program) Start() error {
_, err := p.Run()
return err
}
// Send sends a message to the main update function, effectively allowing
// messages to be injected from outside the program for interoperability
// purposes.
//
// If the program hasn't started yet this will be a blocking operation.
// If the program has already been terminated this will be a no-op, so it's safe
// to send messages after the program has exited.
func (p *Program) Send(msg Msg) {
select {
case <-p.ctx.Done():
case p.msgs <- msg:
}
}
// Quit is a convenience function for quitting Bubble Tea programs. Use it
// when you need to shut down a Bubble Tea program from the outside.
//
// If you wish to quit from within a Bubble Tea program use the Quit command.
//
// If the program is not running this will be a no-op, so it's safe to call
// if the program is unstarted or has already exited.
func (p *Program) Quit() {
p.Send(Quit())
}
// Kill stops the program immediately and restores the former terminal state.
// The final render that you would normally see when quitting will be skipped.
// [program.Run] returns a [ErrProgramKilled] error.
func (p *Program) Kill() {
p.cancel()
}
// Wait waits/blocks until the underlying Program finished shutting down.
func (p *Program) Wait() {
<-p.finished
}
// shutdown performs operations to free up resources and restore the terminal
// to its original state.
func (p *Program) shutdown(kill bool) {
if p.renderer != nil {
if kill {
p.renderer.kill()
} else {
p.renderer.stop()
}
}
_ = p.restoreTerminalState()
if p.restoreOutput != nil {
_ = p.restoreOutput()
}
p.finished <- struct{}{}
}
// ReleaseTerminal restores the original terminal state and cancels the input
// reader. You can return control to the Program with RestoreTerminal.
func (p *Program) ReleaseTerminal() error {
atomic.StoreUint32(&p.ignoreSignals, 1)
p.cancelReader.Cancel()
p.waitForReadLoop()
if p.renderer != nil {
p.renderer.stop()
}
2022-10-03 18:04:05 -04:00
p.altScreenWasActive = p.renderer.altScreen()
p.bpWasActive = p.renderer.bracketedPasteActive()
return p.restoreTerminalState()
}
// RestoreTerminal reinitializes the Program's input reader, restores the
// terminal to the former state when the program was running, and repaints.
// Use it to reinitialize a Program after running ReleaseTerminal.
func (p *Program) RestoreTerminal() error {
atomic.StoreUint32(&p.ignoreSignals, 0)
if err := p.initTerminal(); err != nil {
return err
}
if err := p.initCancelReader(); err != nil {
return err
}
if p.altScreenWasActive {
p.renderer.enterAltScreen()
} else {
// entering alt screen already causes a repaint.
go p.Send(repaintMsg{})
}
if p.renderer != nil {
p.renderer.start()
}
if p.bpWasActive {
p.renderer.enableBracketedPaste()
}
// If the output is a terminal, it may have been resized while another
// process was at the foreground, in which case we may not have received
// SIGWINCH. Detect any size change now and propagate the new size as
// needed.
go p.checkResize()
return nil
}
2022-06-28 15:34:22 -04:00
// Println prints above the Program. This output is unmanaged by the program
// and will persist across renders by the Program.
//
// If the altscreen is active no output will be printed.
func (p *Program) Println(args ...interface{}) {
p.msgs <- printLineMessage{
messageBody: fmt.Sprint(args...),
}
}
// Printf prints above the Program. It takes a format template followed by
// values similar to fmt.Printf. This output is unmanaged by the program and
// will persist across renders by the Program.
//
// Unlike fmt.Printf (but similar to log.Printf) the message will be print on
// its own line.
//
// If the altscreen is active no output will be printed.
func (p *Program) Printf(template string, args ...interface{}) {
p.msgs <- printLineMessage{
messageBody: fmt.Sprintf(template, args...),
}
}