tcellterm

README

tcell-term

A virtual terminal widget for tcell

tcell-term implements the native tcell Widget interface.

screen := tcell.NewScreen()
term := tcellterm.New()
// Create a view. A screen is also a valid view
view := views.NewViewport(screen, 0, 0, -1, -1)

// Set the view. This must be set before calling Draw in your event
// handler
term.SetView(view)

// Call watch with your model. It should HandleEvent(ev tcell.Event)
term.Watch(myWidgetEventWatcher)

cmd := exec.Command(os.Getenv("SHELL"))

go func() {
	term.Run(cmd)
}()

For general discussion or patches, use the mailing list: ~rockorager/tcell-term@lists.sr.ht.

Contributing

Anyone can contribute to tcell-term:

• Clone the repository.
• Patch the code.
• Make some tests.
• Ensure that your code is properly formatted with gofmt.
• Ensure that everything works as expected.
• Ensure that you did not break anything.
• Do not forget to update the docs.

Once you are happy with your work, you can create a commit (or several commits). Follow these general rules:

• Limit the first line (title) of the commit message to 60 characters.
• Use a short prefix for the commit title for readability with git log --oneline.
• Use the body of the commit message to actually explain what your patch does and why it is useful.
• Address only one issue/topic per commit.
• If you are fixing a ticket, use appropriate commit trailers.
• If you are fixing a regression introduced by another commit, add a Fixes: trailer with the commit id and its title.

There is a great reference for commit messages in the Linux kernel documentation.

Before sending the patch, you should configure your local clone with sane defaults:

git config format.subjectPrefix "PATCH tcell-term"
git config sendemail.to "~rockorager/tcell-term@lists.sr.ht"

And send the patch to the mailing list:

git sendemail --annotate -1

Wait for feedback. Address comments and amend changes to your original commit. Then you should send a v2:

git sendemail --in-reply-to=$first_message_id --annotate -v2 -1

Documentation

Index

• type C0
  • func (seq C0) String() string
• type CSI
  • func (seq CSI) String() string
• type DCS
• type DCSData
• type DCSEndOfData
• type EOF
  • func (seq EOF) String() string
• type ESC
  • func (seq ESC) String() string
• type EventBell
• type EventClosed
• type EventMouseMode
  • func (ev *EventMouseMode) Flags() []tcell.MouseFlags
• type EventPanic
• type EventRedraw
• type EventTerminal
  • func (ev *EventTerminal) VT() *VT
  • func (ev *EventTerminal) When() time.Time
• type EventTitle
  • func (ev *EventTitle) Title() string
• type OSC
  • func (seq OSC) String() string
• type Parser
  • func NewParser(r io.Reader) *Parser
  • func (p *Parser) Next() Sequence
• type Print
  • func (seq Print) String() string
• type Sequence
• type Surface
• type VT
  • func New() *VT
  • func (vt *VT) Attach(fn func(ev tcell.Event))
  • func (vt *VT) Close()
  • func (vt *VT) Cursor() (int, int, tcell.CursorStyle, bool)
  • func (vt *VT) Detach()
  • func (vt *VT) Draw()
  • func (vt *VT) HandleEvent(e tcell.Event) bool
  • func (vt *VT) Resize(w int, h int)
  • func (vt *VT) SetSurface(srf Surface)
  • func (vt *VT) Start(cmd *exec.Cmd) error
  • func (vt *VT) String() string

Types

type C0

type C0 rune

A C0 control code

func (C0) String

func (seq C0) String() string

type CSI

type CSI struct {
	Final        rune
	Intermediate []rune
	Parameters   []int
}

A CSI Sequence

func (CSI) String

func (seq CSI) String() string

type DCS

type DCS struct {
	Final        rune
	Intermediate []rune
	Parameters   []int
}

Sent at the beginning of a DCS passthrough sequence.

type DCSData

type DCSData rune

A rune which is passed through during a DCS passthrough sequence

type DCSEndOfData

type DCSEndOfData struct{}

Sent at the end of a DCS passthrough sequence

type EOF

type EOF struct{}

Sent when the underlying PTY is closed

func (EOF) String

func (seq EOF) String() string

type ESC

type ESC struct {
	Final        rune
	Intermediate []rune
}

An escape sequence with intermediate characters

func (ESC) String

func (seq ESC) String() string

type EventBell

type EventBell struct {
	*EventTerminal
}

EventBell is emitted when BEL is received

type EventClosed

type EventClosed struct {
	*EventTerminal
}

EventClosed is emitted when the terminal exits

type EventMouseMode

type EventMouseMode struct {
	*EventTerminal
	// contains filtered or unexported fields
}

EventMouseMode is emitted when the terminal mouse mode changes

func (*EventMouseMode) Flags

func (ev *EventMouseMode) Flags() []tcell.MouseFlags

type EventPanic

type EventPanic struct {
	*EventTerminal
	Error error
}

type EventRedraw

type EventRedraw struct {
	*EventTerminal
}

EventRedraw is emitted when the terminal requires redrawing

type EventTerminal

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

EventTerminal is a generic terminal event

func (*EventTerminal) VT

func (ev *EventTerminal) VT() *VT

func (*EventTerminal) When

func (ev *EventTerminal) When() time.Time

type EventTitle

type EventTitle struct {
	*EventTerminal
	// contains filtered or unexported fields
}

EventTitle is emitted when the terminal's title changes

func (*EventTitle) Title

func (ev *EventTitle) Title() string

type OSC

type OSC struct {
	Payload []rune
}

An OSC sequence. The Payload is the raw runes received, and must be parsed externally

func (OSC) String

func (seq OSC) String() string

type Parser

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

https://vt100.net/emu/dec_ansi_parser

parser is an implementation of Paul Flo Williams' VT500-series parser, as seen [here](https://vt100.net/emu/dec_ansi_parser). The architecture is designed after Rob Pike's text/template parser, with a few modifications.

Many of the comments are directly from Paul Flo Williams description of the parser, licensed undo [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/)

func NewParser

func NewParser(r io.Reader) *Parser

func (*Parser) Next

func (p *Parser) Next() Sequence

Next returns the next Sequence. Sequences will be of the following types:

error          Sent on any parsing error
Print          Print the character to the screen
C0             Execute the C0 code
ESC            Execute the ESC sequence
CSI            Execute the CSI sequence
OSCStart       Signals the start of an OSC sequence
OSCData        Characters from the OSC sequence
OSCEnd         Signals end of the OSC sequence
DCS            Signals start of a DCS sequence, and DCS params/intermediates
DCSData        Raw DCS passthrough data
DCSEndOfData   Signals end of DCS sequence
EOF            Sent at end of input

type Print

type Print rune

A character which should be printed to the screen

func (Print) String

func (seq Print) String() string

type Sequence

type Sequence interface{}

Sequence is the generic data type of items emitted from the parser. These can be control sequences, escape sequences, or printable characters.

type Surface

type Surface interface {
	// SetContent is used to update the content of the Surface at the given
	// location.
	SetContent(x int, y int, ch rune, comb []rune, style tcell.Style)

	// Size represents the visible size.
	Size() (int, int)
}

Surface represents a logical view on an area. It uses a subset of methods from a tcell.Screen or a views.View, in order to be a more broad implementation. Both a Screen and a View are also a Surface

type VT

type VT struct {
	Logger *log.Logger
	// If true, OSC8 enables the output of OSC8 strings. Otherwise, any OSC8
	// sequences will be stripped
	OSC8 bool
	// Set the TERM environment variable to be passed to the command's
	// environment. If not set, xterm-256color will be used
	TERM string
	// contains filtered or unexported fields
}

VT models a virtual terminal

func New

func New() *VT

func (*VT) Attach

func (vt *VT) Attach(fn func(ev tcell.Event))

func (*VT) Close

func (vt *VT) Close()

func (*VT) Cursor

func (vt *VT) Cursor() (int, int, tcell.CursorStyle, bool)

row, col, style, vis

func (*VT) Detach

func (vt *VT) Detach()

func (*VT) Draw

func (vt *VT) Draw()

func (*VT) HandleEvent

func (vt *VT) HandleEvent(e tcell.Event) bool

func (*VT) Resize

func (vt *VT) Resize(w int, h int)

func (*VT) SetSurface

func (vt *VT) SetSurface(srf Surface)

func (*VT) Start

func (vt *VT) Start(cmd *exec.Cmd) error

Start starts the terminal with the specified command. Start returns when the command has been successfully started.

func (*VT) String

func (vt *VT) String() string