taro

README

Much of this code was forked from charmbracelet/bubbletea. I needed to be able to expand on its key/mouse event parsing and build a new Program-esque abstraction.

Documentation

Index

• Variables
• func GetSize(text string) geom.Vec2
• func KeysToBytes(keys ...KeyMsg) (data []byte, err error)
• func Sequence(cmds ...tea.Cmd) tea.Cmd
• func TranslateMouseEvents(data []byte, dx, dy int)
• type Cmd
  • func WaitScreens(ctx context.Context, screens ...mux.Screen) Cmd
• type Key
  • func (k Key) Bytes() (data []byte)
  • func (k Key) String() (str string)
• type KeyMsg
  • func KeysToMsg(keys ...string) (msgs []KeyMsg)
  • func (k KeyMsg) String() (str string)
  • func (k KeyMsg) ToTea() tea.KeyMsg
• type KeyType
  • func (k KeyType) String() (str string)
• type Model
• type MouseButton
• type MouseEvent
  • func (m MouseEvent) Bytes() []byte
  • func (m MouseEvent) String() (s string)
  • func (m MouseEvent) X10Bytes() []byte
• type MouseEventType
• type MouseMsg
  • func (m MouseMsg) Bytes() []byte
  • func (m MouseMsg) String() string
• type Msg
  • func DetectOneMsg(b []byte) (w int, msg Msg)
  • func TranslateMouseMessage(msg Msg, dx, dy int) Msg
• type Program
  • func New(ctx context.Context, model Model) *Program
  • func NewProgram(model Model) *Program
  • func (p *Program) Kill()
  • func (p *Program) Quit()
  • func (p *Program) Resize(size geom.Size) error
  • func (p *Program) Run() (Model, error)
  • func (p *Program) Send(msg events.Msg)
  • func (r *Program) State() *tty.State
  • func (p *Program) Wait()
  • func (p *Program) Write(data []byte) (n int, err error)
• type PublishMsg
• type Renderer
  • func NewRenderer() *Renderer
  • func (r *Renderer) ConvertLipgloss(color lipgloss.Color) emu.Color
  • func (r *Renderer) RenderAt(state image.Image, row, col int, value string)
  • func (r *Renderer) RenderImage(value string) image.Image
• type ScreenUpdate
• type ScreenWatcher
  • func NewWatcher(ctx context.Context, screen mux.Screen) *ScreenWatcher
  • func (s *ScreenWatcher) Wait() Cmd

Variables

var ErrProgramKilled = errors.New("program was killed")

ErrProgramKilled is returned by Program.Run when the program got killed.

Functions

func GetSize

func GetSize(text string) geom.Vec2

GetSize gets the size of `text` as it would appear on the screen.

func KeysToBytes

func KeysToBytes(keys ...KeyMsg) (data []byte, err error)

func Sequence

func Sequence(cmds ...tea.Cmd) tea.Cmd

Sequence runs the given commands one at a time, in order. Contrast this with Batch, which runs commands concurrently.

func TranslateMouseEvents

func TranslateMouseEvents(data []byte, dx, dy int)

TranslateMouseEvents translates all mouse events in-place by [dx, dy].

Types

type Cmd

type Cmd = tea.Cmd

func WaitScreens

func WaitScreens(ctx context.Context, screens ...mux.Screen) Cmd

type Key

type Key struct {
	Type  KeyType
	Runes []rune
	Alt   bool
}

Key contains information about a keypress.

func (Key) Bytes

func (k Key) Bytes() (data []byte)

func (Key) String

func (k Key) String() (str string)

String returns a friendly string representation for a key. It's safe (and encouraged) for use in key comparison.

k := Key{Type: KeyEnter}
fmt.Println(k)
// Output: enter

type KeyMsg

type KeyMsg Key

KeyMsg contains information about a keypress. KeyMsgs are always sent to the program's update function. There are a couple general patterns you could use to check for keypresses:

// Switch on the string representation of the key (shorter)
switch msg := msg.(type) {
case KeyMsg:
    switch msg.String() {
    case "enter":
        fmt.Println("you pressed enter!")
    case "a":
        fmt.Println("you pressed a!")
    }
}

// Switch on the key type (more foolproof)
switch msg := msg.(type) {
case KeyMsg:
    switch msg.Type {
    case KeyEnter:
        fmt.Println("you pressed enter!")
    case KeyRunes:
        switch string(msg.Runes) {
        case "a":
            fmt.Println("you pressed a!")
        }
    }
}

Note that Key.Runes will always contain at least one character, so you can always safely call Key.Runes[0]. In most cases Key.Runes will only contain one character, though certain input method editors (most notably Chinese IMEs) can input multiple runes at once.

func KeysToMsg

func KeysToMsg(keys ...string) (msgs []KeyMsg)

KeysToMsg translates human-readable key specifiers (such as "ctrl+a", "up", etc) into KeyMsg events. Unrecognized strings are represented as KeyRunes.

func (KeyMsg) String

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

String returns a string representation for a key message. It's safe (and encouraged) for use in key comparison.

func (KeyMsg) ToTea

func (k KeyMsg) ToTea() tea.KeyMsg

type KeyType

type KeyType int

KeyType indicates the key pressed, such as KeyEnter or KeyBreak or KeyCtrlC. All other keys will be type KeyRunes. To get the rune value, check the Rune method on a Key struct, or use the Key.String() method:

k := Key{Type: KeyRunes, Runes: []rune{'a'}, Alt: true}
if k.Type == KeyRunes {

    fmt.Println(k.Runes)
    // Output: a

    fmt.Println(k.String())
    // Output: alt+a

}

const (
	KeyNull      KeyType = keyNUL
	KeyBreak     KeyType = keyETX
	KeyEnter     KeyType = keyCR
	KeyBackspace KeyType = keyDEL
	KeyTab       KeyType = keyHT
	KeyEsc       KeyType = keyESC
	KeyEscape    KeyType = keyESC

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

Control key aliases.

const (
	KeyRunes KeyType = -(iota + 1)
	KeyUp
	KeyDown
	KeyRight
	KeyLeft
	KeyShiftTab
	KeyHome
	KeyEnd
	KeyPgUp
	KeyPgDown
	KeyCtrlPgUp
	KeyCtrlPgDown
	KeyDelete
	KeyInsert
	KeySpace
	KeyCtrlUp
	KeyCtrlDown
	KeyCtrlRight
	KeyCtrlLeft
	KeyCtrlHome
	KeyCtrlEnd
	KeyShiftUp
	KeyShiftDown
	KeyShiftRight
	KeyShiftLeft
	KeyShiftHome
	KeyShiftEnd
	KeyCtrlShiftUp
	KeyCtrlShiftDown
	KeyCtrlShiftLeft
	KeyCtrlShiftRight
	KeyCtrlShiftHome
	KeyCtrlShiftEnd
	KeyF1
	KeyF2
	KeyF3
	KeyF4
	KeyF5
	KeyF6
	KeyF7
	KeyF8
	KeyF9
	KeyF10
	KeyF11
	KeyF12
	KeyF13
	KeyF14
	KeyF15
	KeyF16
	KeyF17
	KeyF18
	KeyF19
	KeyF20
)

Other keys.

func (KeyType) String

func (k KeyType) String() (str string)

type Model

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 consists of a full *tty.State. The
	// view is rendered after every Update.
	View(*tty.State)
}

Model contains the program's state as well as its core functions.

type MouseButton

type MouseButton int

const (
	MouseLeft MouseButton = iota
	MouseRight
	MouseMiddle
	MouseWheelUp
	MouseWheelDown
	MouseWheelRight
	MouseWheelLeft
)

type MouseEvent

type MouseEvent struct {
	geom.Vec2
	Type   MouseEventType
	Button MouseButton
	Down   bool
	Alt    bool
	Ctrl   bool
}

MouseEvent represents a mouse event, which could be a click, a scroll wheel movement, a cursor movement, or a combination.

func (MouseEvent) Bytes

func (m MouseEvent) Bytes() []byte

func (MouseEvent) String

func (m MouseEvent) String() (s string)

String returns a string representation of a mouse event.

func (MouseEvent) X10Bytes

func (m MouseEvent) X10Bytes() []byte

type MouseEventType

type MouseEventType int

MouseEventType indicates the type of mouse event occurring.

const (
	MouseUnknown MouseEventType = iota
	MousePress
	MouseMotion
)

Mouse event types.

type MouseMsg

type MouseMsg MouseEvent

MouseMsg contains information about a mouse event and are sent to a programs update function when mouse activity occurs. Note that the mouse must first be enabled in order for the mouse events to be received.

func (MouseMsg) Bytes

func (m MouseMsg) Bytes() []byte

func (MouseMsg) String

func (m MouseMsg) String() string

String returns a string representation of a mouse event.

type Msg

type Msg = events.Msg

func DetectOneMsg

func DetectOneMsg(b []byte) (w int, msg Msg)

func TranslateMouseMessage

func TranslateMouseMessage(msg Msg, dx, dy int) Msg

type Program

type Program struct {
	util.Lifetime
	// contains filtered or unexported fields
}

Program is a terminal user interface.

func New

func New(ctx context.Context, model Model) *Program

func NewProgram

func NewProgram(model Model) *Program

NewProgram creates a new Program.

func (*Program) Kill

func (p *Program) Kill()

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 (*Program) Quit

func (p *Program) Quit()

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 (*Program) Resize

func (p *Program) Resize(size geom.Size) error

func (*Program) Run

func (p *Program) Run() (Model, error)

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 (*Program) Send

func (p *Program) Send(msg events.Msg)

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 (*Program) State

func (r *Program) State() *tty.State

func (*Program) Wait

func (p *Program) Wait()

Wait waits/blocks until the underlying Program finished shutting down.

func (*Program) Write

func (p *Program) Write(data []byte) (n int, err error)

type PublishMsg

type PublishMsg struct {
	Msg Msg
}

Indicates that this message should be emitted upwards.

type Renderer

type Renderer struct {
	*lipgloss.Renderer
	// contains filtered or unexported fields
}

Renderer makes it easy to render lipgloss strings.

func NewRenderer

func NewRenderer() *Renderer

func (*Renderer) ConvertLipgloss

func (r *Renderer) ConvertLipgloss(color lipgloss.Color) emu.Color

func (*Renderer) RenderAt

func (r *Renderer) RenderAt(state image.Image, row, col int, value string)

RenderAt renders the given string at (row, col) in `state`.

func (*Renderer) RenderImage

func (r *Renderer) RenderImage(value string) image.Image

type ScreenUpdate

type ScreenUpdate struct {
	Msg Msg
}

type ScreenWatcher

type ScreenWatcher struct {
	util.Lifetime
	// contains filtered or unexported fields
}

func NewWatcher

func NewWatcher(ctx context.Context, screen mux.Screen) *ScreenWatcher

func (*ScreenWatcher) Wait

func (s *ScreenWatcher) Wait() Cmd