tea

README

Tea

The fun, functional way to build terminal apps. A Go framework based on The Elm Architecture. 茶!

⚠️ This project is a pre-release! The API is subject to change a little.

Simple example

package main

// A simple program that counts down from 5 and then exits.

import (
	"fmt"
	"log"
	"time"
	"github.com/charmbracelet/tea"
)

type model int

type tickMsg time.Time

func main() {
	p := tea.NewProgram(init, update, view, subscriptions)
	if err := p.Start(); err != nil {
		log.Fatal(err)
	}
}

// Listen for messages and update the model accordingly
func update(msg tea.Msg, mdl tea.Model) (tea.Model, tea.Cmd) {
	m, _ := mdl.(model)

	switch msg.(type) {
	case tickMsg:
        m--
		if m == 0 {
			return m, tea.Quit
		}
	}
	return m, nil
}

// Render to the terminal
func view(mdl tea.Model) string {
	m, _ := mdl.(model)
	return fmt.Sprintf("Hi. This program will exit in %d seconds...\n", m)
}

// Subscribe to events
func subscriptions(_ tea.Model) tea.Subs {
    return tea.Subs{
        "tick": time.Every(time.Second, func(t time.Time) tea.Msg {
            return tickMsg(t)
        },
    }
}

Hungry for more? See the other examples.

Other Resources

• Tea Party: a collection of Tea components.
• Termenv: advanced ANSI style and color support for your terminal applications. Very useful when rendering your views.
• Reflow: a collection of ANSI-aware text formatting tools. Also useful for view rendering.

Acknowledgments

Heavily inspired by both The Elm Architecture by Evan Czaplicki et al. and go-tea by TJ Holowaychuk.

License

MIT

---

Part of Charm.

Charm热爱开源!

Documentation

Index

• Constants
• func AltScreen()
• func ExitAltScreen()
• func UseSysLog(programName string) error
• type Cmd
  • func Batch(cmds ...Cmd) Cmd
• type Init
• type Key
  • func ReadKey(r io.Reader) (Key, error)
• type KeyMsg
  • func (k *KeyMsg) IsRune() bool
  • func (k *KeyMsg) String() (str string)
• type KeyType
• type Model
• type Msg
  • func Quit() Msg
• type NewEveryMsg
• type Program
  • func NewProgram(init Init, update Update, view View, subs Subscriptions) *Program
  • func (p *Program) Start() error
• type Sub
  • func Every(duration time.Duration, newMsg NewEveryMsg) Sub
  • func Tick(d time.Duration, newMsg NewEveryMsg) Sub
• type Subs
• type Subscriptions
• type Update
• type View

Constants

const (
	KeyNull      = keyNUL
	KeyBreak     = keyETX
	KeyEnter     = keyCR
	KeyBackspace = keyBS
	KeyTab       = keyHT
	KeySpace     = keySP
	KeyEsc       = keyESC
	KeyEscape    = keyESC
	KeyDelete    = keyDEL

	KeyCtrlAt           = keyNUL // ctrl+@
	KeyCtrlA            = keySOH
	KeyCtrlB            = keySTX
	KeyCtrlC            = keyETX
	KeyCtrlD            = keyEOT
	KeyCtrlE            = keyENQ
	KeyCtrlF            = keyACK
	KeyCtrlG            = keyBEL
	KeyCtrlH            = keyBS
	KeyCtrlI            = keyHT
	KeyCtrlJ            = keyLF
	KeyCtrlK            = keyVT
	KeyCtrlL            = keyFF
	KeyCtrlM            = keyCR
	KeyCtrlN            = keySO
	KeyCtrlO            = keySI
	KeyCtrlP            = keyDLE
	KeyCtrlQ            = keyDC1
	KeyCtrlR            = keyDC2
	KeyCtrlS            = keyDC3
	KeyCtrlT            = keyDC4
	KeyCtrlU            = keyNAK
	KeyCtrlV            = keyETB
	KeyCtrlW            = keyETB
	KeyCtrlX            = keyCAN
	KeyCtrlY            = keyEM
	KeyCtrlZ            = keySUB
	KeyCtrlOpenBracket  = keyESC // ctrl+[
	KeyCtrlBackslash    = keyFS  // ctrl+\
	KeyCtrlCloseBracket = keyGS  // ctrl+]
	KeyCtrlCaret        = keyRS  // ctrl+^
	KeyCtrlUnderscore   = keyUS  // ctrl+_
	KeyCtrlQuestionMark = keyDEL // ctrl+?
)

Aliases

const (
	KeyRune = -(iota + 1)
	KeyUp
	KeyDown
	KeyRight
	KeyLeft
	KeyShiftTab
	KeyHome
	KeyEnd
	KeyPgUp
	KeyPgDown
)

Other keys we track

Functions

func AltScreen

func AltScreen()

AltScreen exits the altscreen. This is just a wrapper around the termenv function

func ExitAltScreen

func ExitAltScreen()

ExitAltScreen exits the altscreen. This is just a wrapper around the termenv function

func UseSysLog

func UseSysLog(programName string) error

UseSysLog sets up logging to log the system log. This becomes helpful when debugging since we can't easily print to the terminal since our TUI is occupying it!

On macOS this is a just a matter of: tail -f /var/log/system.log

Types

type Cmd

type Cmd func() Msg

Cmd is an IO operation that runs once. If it's nil it's considered a no-op.

func Batch

func Batch(cmds ...Cmd) Cmd

Batch peforms a bunch of commands concurrently with no ordering guarantees about the results.

type Init

type Init func() (Model, Cmd)

Init is the first function that will be called. It returns your initial model and runs an optional command

type Key

type Key struct {
	Type KeyType
	Rune rune
	Alt  bool
}

Key contains information about a keypress

func ReadKey

func ReadKey(r io.Reader) (Key, error)

ReadKey reads keypress input from a TTY and returns a string representation of a key

type KeyMsg

type KeyMsg Key

KeyPressMsg contains information about a keypress

func (*KeyMsg) IsRune

func (k *KeyMsg) IsRune() bool

IsRune returns weather or not the key is a rune

func (*KeyMsg) String

func (k *KeyMsg) String() (str string)

String returns a friendly name for a key

type KeyType

type KeyType int

KeyType indicates the key pressed

type Model

type Model interface{}

Model contains the program's state.

type Msg

type Msg interface{}

Msg represents an action and is usually the result of an IO operation. It's triggers the Update function, and henceforth, the UI.

func Quit

func Quit() Msg

Quit is a command that tells the program to exit

type NewEveryMsg

type NewEveryMsg func(time.Time) Msg

NewEveryMsg is used by Every to create a new message. It contains the time at which the timer finished.

type Program

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

Program is a terminal user interface

func NewProgram

func NewProgram(init Init, update Update, view View, subs Subscriptions) *Program

NewProgram creates a new Program

func (*Program) Start

func (p *Program) Start() error

Start initializes the program

type Sub

type Sub func() Msg

Sub is an event subscription; generally a recurring IO operation. If it returns nil it's considered a no-op, but there's really no reason to have a nil subscription.

func Every

func Every(duration time.Duration, newMsg NewEveryMsg) Sub

Every is a subscription that ticks with the system clock at the given duration, similar to cron. It's particularly useful if you have several subscriptions that need to run in sync.

TODO: make it cancelable.

func Tick

func Tick(d time.Duration, newMsg NewEveryMsg) Sub

Tick is a subscription that at an interval independent of the system clock at the given duration. That is, it begins precisely when invoked.

TODO: make it cancelable.

type Subs

type Subs map[string]Sub

Subs is a keyed set of subscriptions. The key should be a unique identifier: two different subscriptions should not have the same key or weird behavior will occur.

type Subscriptions

type Subscriptions func(Model) Subs

Subscriptions returns a map of subscriptions (Subs) our application will subscribe to. If Subscriptions is nil it's considered a no-op.

type Update

type Update func(Msg, Model) (Model, Cmd)

Update is called when a message is received. It may update the model and/or send a command.

type View

type View func(Model) string

View produces a string which will be rendered to the terminal