termview

README

Termview - TUI terminal component for Go

Termview is a terminal component which is designed to work with Bubble Tea v2. It embeds a real shell session in your app using the same model/update/view pattern as other Charm Bracelet components.

1. Functional demo

This demo represents routing PTY I/O into x/vt emulators, rendering with bubbletea library.

2. Installation and usage

go get github.com/grafviktor/termview@v0.1.0

import "github.com/grafviktor/termview"

...
term, err := termview.New(
    termview.WithCommand("/bin/bash"),
    termview.WithInitialWidth(80),
    termview.WithInitialHeight(24),
)

Also see terminal-simple and terminal-multiplexer for the examples.

3. License

MIT - see LICENSE.

Documentation

Overview

It provides a terminal model backed by a PTY and x/vt emulator.

KeyPressMsg flow

This describes what happens when a user types a key and how it reaches the real terminal process.

1. Write to the shell

• User types a character and Bubble Tea generates a tea.KeyPressMsg.
• Model.Update forwards the message to x/vt key handling: tw.emu.SendKey(vt.KeyPressEvent(msg)).
• x/vt converts the key event into bytes and writes them into the emulator's internal output buffer (via io.WriteString(e.pw, seq)).
• This unblocks the writeShell goroutine, which is waiting on tw.emu.Read.
• writeShell writes those bytes to the PTY with tw.pty.Write(buf[:n]).
• The shell running on the other end of the PTY receives those bytes as stdin.

2. Read from the shell

This is the continuation of step 1.

• The shell processes the input and produces output (echo, command result, prompts, etc.).
• The shell writes that output back to the PTY.
• readShell reads from the PTY and receives the shell output bytes.
• A OutputMsg is created and sent back into Update.
• The output is written to the emulator and rendered in Bubble Tea.

Index

• type ClosedMsg
• type Model
  • func New(opts ...Option) (Model, error)
  • func (m Model) Args() []string
  • func (m Model) Blur() Model
  • func (m *Model) Close()
  • func (m Model) Closed() bool
  • func (m Model) Command() string
  • func (m Model) Cursor() *tea.Cursor
  • func (m Model) Focus() Model
  • func (m Model) Focused() bool
  • func (m Model) Height() int
  • func (m Model) ID() int
  • func (m Model) Init() tea.Cmd
  • func (m Model) PID() int
  • func (m *Model) SetHeight(height int)
  • func (m *Model) SetWidth(width int)
  • func (m Model) Update(msg tea.Msg) (Model, tea.Cmd)
  • func (m Model) View() string
  • func (m Model) Width() int
• type Option
  • func WithCommand(cmd string, args ...string) Option
  • func WithInitialHeight(height int) Option
  • func WithInitialWidth(width int) Option
  • func WithStdErr(stdErr io.Writer) Option
• type OutputMsg

Types

type ClosedMsg

type ClosedMsg struct {
	ID              int
	ProcessExitCode int
	ProcessError    error
}

type Model

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

Model embeds a shell in Bubble Tea using x/vt for emulation and xpty for the pseudo-terminal.

func New

func New(opts ...Option) (Model, error)

func (Model) Args

func (m Model) Args() []string

func (Model) Blur

func (m Model) Blur() Model

func (*Model) Close

func (m *Model) Close()

func (Model) Closed

func (m Model) Closed() bool

func (Model) Command

func (m Model) Command() string

func (Model) Cursor

func (m Model) Cursor() *tea.Cursor

func (Model) Focus

func (m Model) Focus() Model

func (Model) Focused

func (m Model) Focused() bool

func (Model) Height

func (m Model) Height() int

func (Model) ID

func (m Model) ID() int

func (Model) Init

func (m Model) Init() tea.Cmd

func (Model) PID

func (m Model) PID() int

func (*Model) SetHeight

func (m *Model) SetHeight(height int)

func (*Model) SetWidth

func (m *Model) SetWidth(width int)

func (Model) Update

func (m Model) Update(msg tea.Msg) (Model, tea.Cmd)

func (Model) View

func (m Model) View() string

func (Model) Width

func (m Model) Width() int

type Option

type Option func(*Model)

func WithCommand

func WithCommand(cmd string, args ...string) Option

func WithInitialHeight

func WithInitialHeight(height int) Option

func WithInitialWidth

func WithInitialWidth(width int) Option

func WithStdErr

func WithStdErr(stdErr io.Writer) Option

type OutputMsg

type OutputMsg struct{ ID int }