taro

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Oct 3, 2024 License: MIT Imports: 26 Imported by: 0

README

taro

Package taro is a high level framework for defining terminal interfaces that obey cy's Screen interface. It is a fork of charmbracelet/bubbletea and borrows that library's state machine paradigm, originally inspired by the Elm framework.

I wanted bubbletea Programs to be able to write to arbitrary parts of the screen without futzing with strings. I also needed to improve on bubbletea's key/mouse event parsing (which, at any rate, has since been patched).

Documentation

Index

Constants

This section is empty.

Variables

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

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

Functions

func GetSize added in v0.1.6 

func GetSize(text string) geom.Vec2

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

func KeysToBytes added in v0.1.5 

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 Test added in v0.1.13 

func Test(m Model) func(msgs ...interface{})

Test returns a function that passes the given messages to the taro Model `m` one at a time. All `Cmd`s that would normally be executed in separate goroutines are instead executed in the calling goroutine. This is useful exclusively in testing.

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 added in v0.1.5 

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 added in v0.1.5 

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 added in v0.1.5 

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 added in v0.1.5 

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 added in v0.1.6 

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 added in v0.1.6 

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 added in v0.1.6 

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(ctx context.Context, model Model) *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 added in v0.1.6 

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 added in v0.1.5 

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 added in v0.1.6 

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

type ScreenUpdate added in v0.1.5 

type ScreenUpdate struct {
	Screen mux.Screen
	Msg    Msg
	// contains filtered or unexported fields
}

func (ScreenUpdate) Wait added in v0.1.16 

func (s ScreenUpdate) Wait() Cmd

type ScreenWatcher added in v0.1.6 

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

func NewWatcher added in v0.1.6 

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

func (*ScreenWatcher) Wait added in v0.1.6 

func (s *ScreenWatcher) Wait() Cmd

Source Files

View all Source files

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.