midterm

package module
v0.2.2 Latest Latest
Warning

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

 Go to latest Published: Feb 26, 2025 License: MIT Imports: 16 Imported by: 6

README

midterm GoDoc

a pretty mid terminal library

Midterm is a virtual terminal emulator. There is no GUI, but it has conveniences for rendering back to a terminal or to HTML.

Some examples:

  • Progrock uses it for displaying progress logs.
  • Dagger uses it for interactive shells, also rendered via Progrock.
  • Bass uses it for rendering terminal output in its docs. (And also uses Progrock.)
Project goals
  • Compatibility with everyday tools like htop and vim.
  • Good enough performance, though optimizations haven't been sought out yet so there's probably some low hanging fruit.
  • Composability/versatility, e.g. forwarding OSC requests/responses between an outer terminal and a remote shell in a container.
  • Anything you'd expect for interactive shells: full mouse support, 256 colors, copy/paste, etc. - though there's no GUI so this really just amounts to forwarding ANSI sequences between local/remote shells.
What's it for?

This is not a GUI terminal emulator intended for everyday use. It's all in-memory. If you want to wrap it in a GUI, feel free!

Right now it's used for rendering terminals embedded in other TUIs (Progrock), and for rendering terminal output in documentation.

What's with the name?

It used to be called vt100, but then I added support for things beyond vt100 like scroll regions, and I don't want to keep renaming it.

I went with midterm because this library often sits in between a local and remote terminal (e.g. dagger shell), so it's a middle terminal. 🤷♂

Credit

Based on tonistiigi/vt100 which was was based on jaguilar/vt100.

Documentation

Overview

package midterm implements an in-memory terminal emulator, designed to be used as a component within a larger application for displaying logs, running interactive shells, or rendering terminal output.

Index

Constants

View Source 
const (
	ResetBit uint8 = 1 << iota
	BoldBit
	FaintBit
	ItalicBit
	UnderlineBit
	BlinkBit
	ReverseBit
	ConcealBit
)

Constants for property bit positions

Variables

View Source 
var EmptyFormat = Format{}
View Source 
var Reset = Format{Properties: ResetBit}
View Source 
var ReverseFormat = Format{Properties: ReverseBit}

Functions

func DebugLogsTo added in v0.2.1 

func DebugLogsTo(w io.Writer)

Types

type Canvas added in v0.2.1 

type Canvas struct {
	Width int
	Rows  []*Region
}

func (*Canvas) Delete added in v0.2.1 

func (canvas *Canvas) Delete(row, col, n int)

TODO: untested

func (*Canvas) Height added in v0.2.1 

func (canvas *Canvas) Height() int

func (*Canvas) Insert added in v0.2.1 

func (canvas *Canvas) Insert(row, col int, f Format, n int)

func (*Canvas) Paint added in v0.2.1 

func (canvas *Canvas) Paint(row, col int, format Format)

func (*Canvas) Regions added in v0.2.1 

func (canvas *Canvas) Regions(row int) iter.Seq[*Region]

func (*Canvas) Resize added in v0.2.1 

func (canvas *Canvas) Resize(h, w int)

func (*Canvas) ResizeX added in v0.2.1 

func (canvas *Canvas) ResizeX(w int)

func (*Canvas) ResizeY added in v0.2.1 

func (canvas *Canvas) ResizeY(h int)

type Cursor 

type Cursor struct {
	// Y and X are the coordinates.
	Y, X int

	// F is the format that will be displayed.
	F Format

	// S is the cursor style.
	S ansicode.CursorStyle
}

Cursor represents both the position and text type of the cursor.

func (Cursor) MarshalBinary added in v0.2.1 

func (c Cursor) MarshalBinary() (data []byte, err error)

type Format 

type Format struct {
	// Fg and Bg are the foreground and background colors.
	Fg, Bg termenv.Color

	// Properties packed into a single byte.
	Properties uint8
}

Format represents the text formatting options. 

func (f *Format) IsBlink() bool

func (*Format) IsBold added in v0.2.0 

func (f *Format) IsBold() bool

func (*Format) IsConceal added in v0.2.0 

func (f *Format) IsConceal() bool

func (*Format) IsFaint added in v0.2.0 

func (f *Format) IsFaint() bool

func (*Format) IsItalic added in v0.2.0 

func (f *Format) IsItalic() bool

func (*Format) IsReset added in v0.2.0 

func (f *Format) IsReset() bool

func (*Format) IsReverse added in v0.2.0 

func (f *Format) IsReverse() bool

func (*Format) IsUnderline added in v0.2.0 

func (f *Format) IsUnderline() bool

func (Format) MarshalBinary added in v0.2.1 

func (f Format) MarshalBinary() (data []byte, err error)

func (Format) Render 

func (f Format) Render() string

func (Format) RenderFgBg added in v0.2.2 

func (f Format) RenderFgBg(fg, bg termenv.Color) string
func (f *Format) SetBlink(value bool)

func (*Format) SetBold added in v0.2.0 

func (f *Format) SetBold(value bool)

func (*Format) SetConceal added in v0.2.0 

func (f *Format) SetConceal(value bool)

func (*Format) SetFaint added in v0.2.0 

func (f *Format) SetFaint(value bool)

func (*Format) SetItalic added in v0.2.0 

func (f *Format) SetItalic(value bool)

func (*Format) SetReset added in v0.2.0 

func (f *Format) SetReset(value bool)

func (*Format) SetReverse added in v0.2.0 

func (f *Format) SetReverse(value bool)

func (*Format) SetUnderline added in v0.2.0 

func (f *Format) SetUnderline(value bool)

type Line added in v0.2.0 

type Line struct {
	Content []rune
	Format  []Format
}

func (Line) Display added in v0.2.0 

func (line Line) Display() string

type OnResizeFunc 

type OnResizeFunc func(rows, cols int)

type OnScrollbackFunc added in v0.2.0 

type OnScrollbackFunc func(line Line)

type Region added in v0.2.1 

type Region struct {
	// Format that applies to this region.
	F Format

	// Size is the number of characters to which the format applies.
	Size int

	// Next is the next region in the row.
	Next *Region
}

Region represents a segment of a row with a specific format.

func (*Region) String added in v0.2.1 

func (region *Region) String() string

type Screen added in v0.1.4 

type Screen struct {
	// Height and Width are the dimensions of the terminal.
	Height, Width int

	// Content is the text in the terminal.
	Content [][]rune

	// Format contains the display properties of each cell.
	Format *Canvas

	// Changes counts the number of times each row has been modified so that the
	// UI can know which content needs to be redrawn.
	//
	// Note that this includes changes to the cursor position, in case the cursor
	// is visible: if the cursor moves from row 0 to row 3, both rows will be
	// incremented.
	Changes []uint64

	// Cursor is the current state of the cursor.
	Cursor Cursor

	// ScrollRegion is the region of the terminal that is scrollable. If it is
	// nil, the entire terminal is scrollable.
	//
	// This value is set by the CSI ; Ps ; Ps r command.
	ScrollRegion *ScrollRegion

	// CursorVisible indicates whether the cursor is visible.
	//
	// This value is set by CSI ? 25 h and unset by CSI ? 25 l.
	CursorVisible bool

	// CursorBlinking indicates whether the cursor is blinking, and the start of
	// the blinking interval.
	CursorBlinkEpoch *time.Time

	// SavedCursor is the state of the cursor last time save() was called.
	SavedCursor Cursor

	// MaxY is the maximum vertical offset that a character has been printed.
	MaxY int
	// MaxX is the maximum horizontal offset that a character has been printed.
	MaxX int
}

type ScrollRegion 

type ScrollRegion struct {
	Start, End int
}

ScrollRegion represents a region of the terminal that is scrollable.

type Terminal 

type Terminal struct {
	// Screen is the current screen, embedded so that Terminal is a pass-through.
	*Screen

	// The title of the terminal
	Title string

	// Alt is either the alternate screen (if !IsAlt) or the main screen (if
	// IsAlt).
	Alt *Screen

	// IsAlt indicates whether the alt screen is active.
	IsAlt bool

	// AutoResizeY indicates whether the terminal should automatically resize
	// when the content exceeds its maximum height.
	AutoResizeY bool

	// AutoResizeX indicates that the terminal has no defined width - instead,
	// columns are dynamically allocated as text is printed, and not all rows
	// will be the same width.
	AutoResizeX bool

	// ForwardRequests is the writer to which we send requests to forward
	// to the terminal.
	ForwardRequests io.Writer

	// ForwardResponses is the writer to which we send responses to CSI/OSC queries.
	ForwardResponses io.Writer

	// Enable "raw" mode. Line endings do not imply a carriage return.
	Raw bool

	// AppendOnly instructs the terminal to not respect sequences that might
	// cause output to be lost - for example, setting a scrolling region.
	AppendOnly bool

	*ansicode.Decoder
	// contains filtered or unexported fields
}

Terminal represents a raw terminal capable of handling VT100 and VT102 ANSI escape sequences, some of which are handled by forwarding them to a local or remote session (e.g. OSC52 copy/paste).

func NewAutoResizingTerminal added in v0.1.1 

func NewAutoResizingTerminal() *Terminal

NewAutoResizingTerminal creates a new Terminal object with small initial dimensions, configured to automatically resize width and height as needed.

This may be useful for applications that want to display dynamically sized content.

func NewTerminal 

func NewTerminal(rows, cols int) *Terminal

NewTerminal creates a new Terminal object with the specified dimensions. y and x must both be greater than zero.

Each cell is set to contain a ' ' rune, and all formats are left as the default.

func (*Terminal) Backspace added in v0.2.1 

func (v *Terminal) Backspace()

Backspace moves the cursor one position to the left.

func (*Terminal) Bell added in v0.2.1 

func (v *Terminal) Bell()

Bell rings the bell.

func (*Terminal) CarriageReturn added in v0.2.1 

func (v *Terminal) CarriageReturn()

CarriageReturn moves the cursor to the beginning of the line.

func (*Terminal) ClearLine added in v0.2.1 

func (v *Terminal) ClearLine(mode ansicode.LineClearMode)

ClearLine clears the line.

func (*Terminal) ClearScreen added in v0.2.1 

func (v *Terminal) ClearScreen(mode ansicode.ClearMode)

ClearScreen clears the screen.

func (*Terminal) ClearTabs added in v0.2.1 

func (v *Terminal) ClearTabs(mode ansicode.TabulationClearMode)

ClearTabs clears the tab stops.

func (*Terminal) ClipboardLoad added in v0.2.1 

func (v *Terminal) ClipboardLoad(clipboard byte, terminator string)

ClipboardLoad loads data from the clipboard.

func (*Terminal) ClipboardStore added in v0.2.1 

func (v *Terminal) ClipboardStore(clipboard byte, data []byte)

ClipboardStore stores data in the clipboard.

func (*Terminal) ConfigureCharset added in v0.2.1 

func (v *Terminal) ConfigureCharset(index ansicode.CharsetIndex, charset ansicode.Charset)

ConfigureCharset configures the charset.

func (*Terminal) Decaln added in v0.2.1 

func (v *Terminal) Decaln()

Decaln runs the DECALN command.

func (*Terminal) DeleteChars added in v0.2.1 

func (v *Terminal) DeleteChars(n int)

DeleteChars deletes n characters.

func (*Terminal) DeleteLines added in v0.2.1 

func (v *Terminal) DeleteLines(n int)

DeleteLines deletes n lines.

func (*Terminal) DeviceStatus added in v0.2.1 

func (v *Terminal) DeviceStatus(n int)

DeviceStatus reports the device status.

func (*Terminal) EraseChars added in v0.2.1 

func (v *Terminal) EraseChars(n int)

EraseChars erases n characters.

func (*Terminal) Goto added in v0.2.1 

func (v *Terminal) Goto(y int, x int)

Goto moves the cursor to the specified position.

func (*Terminal) GotoCol added in v0.2.1 

func (v *Terminal) GotoCol(n int)

GotoCol moves the cursor to the specified column.

func (*Terminal) GotoLine added in v0.2.1 

func (v *Terminal) GotoLine(n int)

GotoLine moves the cursor to the specified line.

func (*Terminal) HTML 

func (v *Terminal) HTML() string

HTML renders v as an HTML fragment. One idea for how to use this is to debug the current state of the screen reader.

func (*Terminal) HorizontalTabSet added in v0.2.1 

func (v *Terminal) HorizontalTabSet()

HorizontalTab sets the current position as a tab stop.

func (*Terminal) IdentifyTerminal added in v0.2.1 

func (v *Terminal) IdentifyTerminal(b byte)

IdentifyTerminal identifies the terminal.

func (*Terminal) Input added in v0.2.1 

func (v *Terminal) Input(r rune)

Input inputs a rune to be displayed.

func (*Terminal) InsertBlank added in v0.2.1 

func (v *Terminal) InsertBlank(n int)

InsertBlank inserts n blank characters.

func (*Terminal) InsertBlankLines added in v0.2.1 

func (v *Terminal) InsertBlankLines(n int)

InsertBlankLines inserts n blank lines.

func (*Terminal) LineFeed added in v0.2.1 

func (v *Terminal) LineFeed()

LineFeed moves the cursor to the next line.

func (*Terminal) MarshalBinary added in v0.2.1 

func (vt *Terminal) MarshalBinary() (data []byte, err error)

func (*Terminal) MoveBackward added in v0.2.1 

func (v *Terminal) MoveBackward(n int)

MoveBackward moves the cursor backward n columns.

func (*Terminal) MoveBackwardTabs added in v0.2.1 

func (v *Terminal) MoveBackwardTabs(n int)

MoveBackwardTabs moves the cursor backward n tab stops.

func (*Terminal) MoveDown added in v0.2.1 

func (v *Terminal) MoveDown(n int)

MoveDown moves the cursor down n lines.

func (*Terminal) MoveDownCr added in v0.2.1 

func (v *Terminal) MoveDownCr(n int)

MoveDownCr moves the cursor down n lines and to the beginning of the line.

func (*Terminal) MoveForward added in v0.2.1 

func (v *Terminal) MoveForward(n int)

MoveForward moves the cursor forward n columns.

func (*Terminal) MoveForwardTabs added in v0.2.1 

func (v *Terminal) MoveForwardTabs(n int)

MoveForwardTabs moves the cursor forward n tab stops.

func (*Terminal) MoveUp added in v0.2.1 

func (v *Terminal) MoveUp(n int)

MoveUp moves the cursor up n lines.

func (*Terminal) MoveUpCr added in v0.2.1 

func (v *Terminal) MoveUpCr(n int)

MoveUpCr moves the cursor up n lines and to the beginning of the line.

func (*Terminal) OnResize 

func (v *Terminal) OnResize(f OnResizeFunc)

OnResize sets a hook that is called every time the terminal resizes.

func (*Terminal) OnScrollback added in v0.2.0 

func (v *Terminal) OnScrollback(f OnScrollbackFunc)

OnScrollback sets a hook that is called every time a line is about to be pushed out of the visible screen region.

func (*Terminal) PopKeyboardMode added in v0.2.1 

func (v *Terminal) PopKeyboardMode(n int)

PopKeyboardMode pops the given amount n of keyboard modes from the stack.

func (*Terminal) PopTitle added in v0.2.1 

func (v *Terminal) PopTitle()

PopTitle pops the title from the stack.

func (*Terminal) PushKeyboardMode added in v0.2.1 

func (v *Terminal) PushKeyboardMode(mode ansicode.KeyboardMode)

PushKeyboardMode pushes the given keyboard mode to the stack.

func (*Terminal) PushTitle added in v0.2.1 

func (v *Terminal) PushTitle()

PushTitle pushes the given title to the stack.

func (*Terminal) Render 

func (vt *Terminal) Render(w io.Writer) error

func (*Terminal) RenderFgBg added in v0.2.1 

func (vt *Terminal) RenderFgBg(w io.Writer, fg, bg termenv.Color) error

func (*Terminal) RenderLine 

func (vt *Terminal) RenderLine(w io.Writer, row int) error

func (*Terminal) RenderLineFgBg added in v0.2.1 

func (vt *Terminal) RenderLineFgBg(w io.Writer, row int, fg, bg termenv.Color) error

func (*Terminal) ReportKeyboardMode added in v0.2.1 

func (v *Terminal) ReportKeyboardMode()

ReportKeyboardMode reports the keyboard mode.

func (*Terminal) ReportModifyOtherKeys added in v0.2.1 

func (v *Terminal) ReportModifyOtherKeys()

ReportModifyOtherKeys reports the modify other keys mode. (XTERM)

func (*Terminal) Reset 

func (v *Terminal) Reset()

func (*Terminal) ResetColor added in v0.2.1 

func (v *Terminal) ResetColor(i int)

ResetColor resets the color at the given index.

func (*Terminal) ResetState added in v0.2.1 

func (v *Terminal) ResetState()

ResetState resets the terminal state.

func (*Terminal) Resize 

func (v *Terminal) Resize(rows, cols int)

Resize sets the terminal height and width to rows and cols and disables auto-resizing on both axes.

func (*Terminal) ResizeX added in v0.1.3 

func (v *Terminal) ResizeX(cols int)

Resize sets the terminal width to cols and disables auto-resizing width.

func (*Terminal) ResizeY added in v0.1.3 

func (v *Terminal) ResizeY(rows int)

Resize sets the terminal height to rows rows and disables auto-resizing height.

func (*Terminal) RestoreCursorPosition added in v0.2.1 

func (v *Terminal) RestoreCursorPosition()

RestoreCursorPosition restores the cursor position.

func (*Terminal) ReverseIndex added in v0.2.1 

func (v *Terminal) ReverseIndex()

ReverseIndex moves the active position to the same horizontal position on the preceding line.

func (*Terminal) SaveCursorPosition added in v0.2.1 

func (v *Terminal) SaveCursorPosition()

SaveCursorPosition saves the cursor position.

func (*Terminal) ScrollDown added in v0.2.1 

func (v *Terminal) ScrollDown(n int)

ScrollDown scrolls the screen down n lines.

func (*Terminal) ScrollUp added in v0.2.1 

func (v *Terminal) ScrollUp(n int)

ScrollUp scrolls the screen up n lines.

func (*Terminal) SetActiveCharset added in v0.2.1 

func (v *Terminal) SetActiveCharset(n int)

SetActiveCharset sets the active charset.

func (*Terminal) SetColor added in v0.2.1 

func (v *Terminal) SetColor(index int, color color.Color)

SetColor sets the color at the given index.

func (*Terminal) SetCursorStyle added in v0.2.1 

func (v *Terminal) SetCursorStyle(style ansicode.CursorStyle)

SetCursorStyle sets the cursor style.

func (*Terminal) SetDynamicColor added in v0.2.1 

func (v *Terminal) SetDynamicColor(prefix string, index int, terminator string)

SetDynamicColor sets the dynamic color at the given index. 

func (v *Terminal) SetHyperlink(hyperlink *ansicode.Hyperlink)

SetHyperlink sets the hyperlink.

func (*Terminal) SetKeyboardMode added in v0.2.1 

func (v *Terminal) SetKeyboardMode(mode ansicode.KeyboardMode, behavior ansicode.KeyboardModeBehavior)

SetKeyboardMode sets the keyboard mode.

func (*Terminal) SetKeypadApplicationMode added in v0.2.1 

func (v *Terminal) SetKeypadApplicationMode()

SetKeypadApplicationMode sets keypad to applications mode.

func (*Terminal) SetMode added in v0.2.1 

func (v *Terminal) SetMode(mode ansicode.TerminalMode)

SetMode sets the given mode.

func (*Terminal) SetModifyOtherKeys added in v0.2.1 

func (v *Terminal) SetModifyOtherKeys(modify ansicode.ModifyOtherKeys)

SetModifyOtherKeys sets the modify other keys mode. (XTERM)

func (*Terminal) SetScrollingRegion added in v0.2.1 

func (v *Terminal) SetScrollingRegion(top int, bottom int)

SetScrollingRegion sets the scrolling region.

func (*Terminal) SetTerminalCharAttribute added in v0.2.1 

func (v *Terminal) SetTerminalCharAttribute(attr ansicode.TerminalCharAttribute)

SetTerminalCharAttribute sets the terminal char attribute.

func (*Terminal) SetTitle added in v0.2.1 

func (v *Terminal) SetTitle(title string)

SetTitle sets the window title.

func (*Terminal) Substitute added in v0.2.1 

func (v *Terminal) Substitute()

Substitute replaces the character under the cursor.

func (*Terminal) Tab added in v0.2.1 

func (v *Terminal) Tab(n int)

Tab moves the cursor to the next tab stop.

func (*Terminal) TextAreaSizeChars added in v0.2.1 

func (v *Terminal) TextAreaSizeChars()

TextAreaSizeChars reports the text area size in characters.

func (*Terminal) TextAreaSizePixels added in v0.2.1 

func (v *Terminal) TextAreaSizePixels()

TextAreaSizePixels reports the text area size in pixels.

func (*Terminal) UnsetKeypadApplicationMode added in v0.2.1 

func (v *Terminal) UnsetKeypadApplicationMode()

UnsetKeypadApplicationMode sets the keypad to numeric mode.

func (*Terminal) UnsetMode added in v0.2.1 

func (v *Terminal) UnsetMode(mode ansicode.TerminalMode)

UnsetMode unsets the given mode.

func (*Terminal) UsedHeight 

func (v *Terminal) UsedHeight() int

func (*Terminal) UsedWidth added in v0.2.0 

func (v *Terminal) UsedWidth() int

func (*Terminal) Write 

func (v *Terminal) Write(p []byte) (int, error)

Write writes the input sequence to the terminal.

Source Files

View all Source files

Directories

Path Synopsis

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.
JackTT - Gopher 🇻🇳