Documentation
¶
Overview ¶
Package cellbuf provides terminal cell buffer functionality.
Index ¶
- Constants
- Variables
- func Clear(s CellBuffer)
- func ClearRect(s CellBuffer, rect Rectangle)
- func Fill(s CellBuffer, c *Cell)
- func FillRect(s CellBuffer, c *Cell, rect Rectangle)
- func Height(s string) int
- func ReadLink(p []byte, link *Link)
- func ReadStyle(params ansi.Params, pen *Style)
- func ReadStyleColor(params ansi.Params, c *color.Color) int
- func Render(d CellBuffer) string
- func RenderLine(d CellBuffer, n int) (w int, line string)
- func SetContent(s CellBuffer, str string)
- func SetContentRect(s CellBuffer, str string, rect Rectangle)
- func Wrap(s string, limit int, breakpoints string) string
- type AttrMask
- type Buffer
- func (b *Buffer) Bounds() Rectangle
- func (b *Buffer) Cell(x int, y int) *Cell
- func (b *Buffer) Clear()
- func (b *Buffer) ClearRect(rect Rectangle)
- func (b *Buffer) DeleteCell(x, y, n int, c *Cell)
- func (b *Buffer) DeleteCellRect(x, y, n int, c *Cell, rect Rectangle)
- func (b *Buffer) DeleteLine(y, n int, c *Cell)
- func (b *Buffer) DeleteLineRect(y, n int, c *Cell, rect Rectangle)
- func (b *Buffer) Fill(c *Cell)
- func (b *Buffer) FillRect(c *Cell, rect Rectangle)
- func (b *Buffer) Height() int
- func (b *Buffer) InsertCell(x, y, n int, c *Cell)
- func (b *Buffer) InsertCellRect(x, y, n int, c *Cell, rect Rectangle)
- func (b *Buffer) InsertLine(y, n int, c *Cell)
- func (b *Buffer) InsertLineRect(y, n int, c *Cell, rect Rectangle)
- func (b *Buffer) Line(y int) Line
- func (b *Buffer) Resize(width int, height int)
- func (b *Buffer) SetCell(x, y int, c *Cell) bool
- func (b *Buffer) String() (s string)
- func (b *Buffer) Width() int
- type Cell
- type CellBuffer
- type Cursor
- type Line
- type Link
- type PenWriter
- type Position
- type Rectangle
- type Screen
- func (s *Screen) Bounds() Rectangle
- func (s *Screen) Cell(x int, y int) *Cell
- func (s *Screen) Clear() bool
- func (s *Screen) ClearRect(r Rectangle) bool
- func (s *Screen) Close() (err error)
- func (s *Screen) EnterAltScreen()
- func (s *Screen) ExitAltScreen()
- func (s *Screen) Fill(cell *Cell) bool
- func (s *Screen) FillRect(cell *Cell, r Rectangle) bool
- func (s *Screen) Flush() (err error)
- func (s *Screen) Height() int
- func (s *Screen) HideCursor()
- func (s *Screen) InsertAbove(str string)
- func (s *Screen) MoveTo(x, y int)
- func (s *Screen) Redraw()
- func (s *Screen) Render()
- func (s *Screen) Resize(width, height int) bool
- func (s *Screen) SetCell(x int, y int, cell *Cell) (v bool)
- func (s *Screen) SetColorProfile(p colorprofile.Profile)
- func (s *Screen) SetMethod(method ansi.Method)
- func (s *Screen) SetRelativeCursor(v bool)
- func (s *Screen) ShowCursor()
- func (s *Screen) UseBackspaces(v bool)
- func (s *Screen) UseHardTabs(v bool)
- func (s *Screen) Width() int
- type ScreenOptions
- type ScreenWriter
- func (s *ScreenWriter) Print(str string, v ...any)
- func (s *ScreenWriter) PrintAt(x, y int, str string, v ...any)
- func (s *ScreenWriter) PrintCrop(str string, tail string)
- func (s *ScreenWriter) PrintCropAt(x, y int, str string, tail string)
- func (s *ScreenWriter) SetContent(str string)
- func (s *ScreenWriter) SetContentRect(str string, rect Rectangle)
- func (s *ScreenWriter) Write(p []byte) (n int, err error)
- type Style
- func (s *Style) Background(c ansi.Color) *Style
- func (s *Style) Bold(v bool) *Style
- func (s *Style) Clear() bool
- func (s *Style) Conceal(v bool) *Style
- func (s Style) DiffSequence(o Style) string
- func (s *Style) Empty() bool
- func (s *Style) Equal(o *Style) bool
- func (s *Style) Faint(v bool) *Style
- func (s *Style) Foreground(c ansi.Color) *Style
- func (s *Style) Italic(v bool) *Style
- func (s *Style) RapidBlink(v bool) *Style
- func (s *Style) Reset() *Style
- func (s *Style) Reverse(v bool) *Style
- func (s Style) Sequence() string
- func (s *Style) SlowBlink(v bool) *Style
- func (s *Style) Strikethrough(v bool) *Style
- func (s *Style) Underline(v bool) *Style
- func (s *Style) UnderlineColor(c ansi.Color) *Style
- func (s *Style) UnderlineStyle(style UnderlineStyle) *Style
- type TabStops
- type UnderlineStyle
Examples ¶
Constants ¶
const ( NoUnderline = ansi.NoUnderlineStyle SingleUnderline = ansi.SingleUnderlineStyle DoubleUnderline = ansi.DoubleUnderlineStyle CurlyUnderline = ansi.CurlyUnderlineStyle DottedUnderline = ansi.DottedUnderlineStyle DashedUnderline = ansi.DashedUnderlineStyle )
These are the available underline styles.
const DefaultTabInterval = 8
DefaultTabInterval is the default tab interval.
Variables ¶
var ( // BlankCell is a cell with a single space, width of 1, and no style or link. BlankCell = Cell{Rune: ' ', Width: 1} // EmptyCell is just an empty cell used for comparisons and as a placeholder // for wide cells. EmptyCell = Cell{} )
ErrInvalidDimensions is returned when the dimensions of a window are invalid for the operation.
ErrOutOfBounds is returned when the given x, y position is out of bounds.
Functions ¶
func ClearRect ¶
func ClearRect(s CellBuffer, rect Rectangle)
ClearRect clears the rectangle within the cell buffer with blank cells.
func FillRect ¶
func FillRect(s CellBuffer, c *Cell, rect Rectangle)
FillRect fills the rectangle within the cell buffer with the given cell. This will not fill cells outside the bounds of the cell buffer.
func ReadLink ¶
ReadLink reads a hyperlink escape sequence from a data buffer.
func ReadStyle ¶
ReadStyle reads a Select Graphic Rendition (SGR) escape sequences from a list of parameters.
func ReadStyleColor ¶
ReadStyleColor reads a color from a list of parameters. See ansi.ReadStyleColor for more information.
func Render ¶
func Render(d CellBuffer) string
Render returns a string representation of the grid with ANSI escape sequences.
func RenderLine ¶
func RenderLine(d CellBuffer, n int) (w int, line string)
RenderLine returns a string representation of the yth line of the grid along with the width of the line.
func SetContent ¶
func SetContent(s CellBuffer, str string)
SetContent clears the cell buffer with blank cells, and sets the given string as its content. If the height or width of the string exceeds the height or width of the cell buffer, it will be truncated.
func SetContentRect ¶
func SetContentRect(s CellBuffer, str string, rect Rectangle)
SetContentRect clears the rectangle within the cell buffer with blank cells, and sets the given string as its content. If the height or width of the string exceeds the height or width of the cell buffer, it will be truncated.
func Wrap ¶
Wrap returns a string that is wrapped to the specified limit applying any ANSI escape sequences in the string. It tries to wrap the string at word boundaries, but will break words if necessary.
The breakpoints string is a list of characters that are considered breakpoints for word wrapping. A hyphen (-) is always considered a breakpoint.
Note: breakpoints must be a string of 1-cell wide rune characters.
Example ¶
fmt.Println(Wrap("The quick brown fox jumped over the lazy dog.", 20, ""))
Output: The quick brown fox jumped over the lazy dog.
Types ¶
type AttrMask ¶
type AttrMask uint8
AttrMask is a bitmask for text attributes that can change the look of text. These attributes can be combined to create different styles.
type Buffer ¶
type Buffer struct {
// Lines holds the lines of the buffer.
Lines []Line
}
Buffer is a 2D grid of cells representing a screen or terminal.
func NewBuffer ¶
NewBuffer creates a new buffer with the given width and height. This is a convenience function that initializes a new buffer and resizes it.
func (*Buffer) Bounds ¶
Bounds returns the bounds of the buffer.
func (*Buffer) Clear ¶
func (b *Buffer) Clear()
Clear clears the buffer with space cells and rectangle.
func (*Buffer) ClearRect ¶
ClearRect clears the buffer with space cells within the specified rectangles. Only cells within the rectangle's bounds are affected.
func (*Buffer) DeleteCell ¶
DeleteCell deletes cells at the given position, with the given optional cell, within the specified rectangles. If no rectangles are specified, it deletes cells in the entire buffer. This follows terminal ansi.DCH behavior.
func (*Buffer) DeleteCellRect ¶
DeleteCellRect deletes cells at the given position, with the given optional cell, within the rectangle bounds. Only cells within the rectangle's bounds are affected, following terminal ansi.DCH behavior.
func (*Buffer) DeleteLine ¶
DeleteLine deletes n lines at the given line position, with the given optional cell, within the specified rectangles. If no rectangles are specified, it deletes lines in the entire buffer.
func (*Buffer) DeleteLineRect ¶
DeleteLineRect deletes lines at the given line position, with the given optional cell, within the rectangle bounds. Only cells within the rectangle's bounds are affected. Lines are shifted up within the bounds and new blank lines are created at the bottom. This follows terminal ansi.DL behavior.
func (*Buffer) Fill ¶
Fill fills the buffer with the given cell and rectangle.
func (*Buffer) FillRect ¶
FillRect fills the buffer with the given cell and rectangle.
func (*Buffer) InsertCell ¶
InsertCell inserts new cells at the given position, with the given optional cell, within the specified rectangles. If no rectangles are specified, it inserts cells in the entire buffer. This follows terminal ansi.ICH behavior.
func (*Buffer) InsertCellRect ¶
InsertCellRect inserts new cells at the given position, with the given optional cell, within the rectangle bounds. Only cells within the rectangle's bounds are affected, following terminal ansi.ICH behavior.
func (*Buffer) InsertLine ¶
InsertLine inserts n lines at the given line position, with the given optional cell, within the specified rectangles. If no rectangles are specified, it inserts lines in the entire buffer. Only cells within the rectangle's horizontal bounds are affected. Lines are pushed out of the rectangle bounds and lost. This follows terminal ansi.IL behavior. It returns the pushed out lines.
func (*Buffer) InsertLineRect ¶
InsertLineRect inserts new lines at the given line position, with the given optional cell, within the rectangle bounds. Only cells within the rectangle's horizontal bounds are affected. Lines are pushed out of the rectangle bounds and lost. This follows terminal ansi.IL behavior.
func (*Buffer) Line ¶
Line returns a pointer to the line at the given y position. If the line does not exist, it returns nil.
func (*Buffer) Resize ¶
Resize resizes the buffer to the given width and height.
func (*Buffer) SetCell ¶
SetCell sets the cell at the given x, y position.
func (*Buffer) String ¶
String returns the string representation of the buffer.
type Cell ¶
type Cell struct {
// The style of the cell. Nil style means no style. Zero value prints a
// reset sequence.
Style Style
// Link is the hyperlink of the cell.
Link Link
// Comb is the combining runes of the cell. This is nil if the cell is a
// single rune or if it's a zero width cell that is part of a wider cell.
Comb []rune
// Width is the mono-space width of the grapheme cluster.
Width int
// Rune is the main rune of the cell. This is zero if the cell is part of a
// wider cell.
Rune rune
}
Cell represents a single cell in the terminal screen.
func NewCell ¶
NewCell returns a new cell. This is a convenience function that initializes a new cell with the given content. The cell's width is determined by the content using runewidth.RuneWidth. This will only account for the first combined rune in the content. If the content is empty, it will return an empty cell with a width of 0.
func NewCellString ¶
NewCellString returns a new cell with the given string content. This is a convenience function that initializes a new cell with the given content. The cell's width is determined by the content using runewidth.StringWidth. This will only use the first combined rune in the string. If the string is empty, it will return an empty cell with a width of 0.
func NewGraphemeCell ¶
NewGraphemeCell returns a new cell. This is a convenience function that initializes a new cell with the given content. The cell's width is determined by the content using uniseg.FirstGraphemeClusterInString. This is used when the content is a grapheme cluster i.e. a sequence of runes that form a single visual unit. This will only return the first grapheme cluster in the string. If the string is empty, it will return an empty cell with a width of 0.
func (*Cell) Append ¶
Append appends runes to the cell without changing the width. This is useful when we want to use the cell to store escape sequences or other runes that don't affect the width of the cell.
func (*Cell) Blank ¶
Blank makes the cell a blank cell by setting the rune to a space, comb to nil, and the width to 1.
func (*Cell) Clear ¶
Clear returns whether the cell consists of only attributes that don't affect appearance of a space character.
func (Cell) Empty ¶
Empty returns whether the cell is an empty cell. An empty cell is a cell with a width of 0, a rune of 0, and no combining runes.
func (*Cell) Equal ¶
Equal returns whether the cell is equal to the other cell.
type CellBuffer ¶
type CellBuffer interface {
// Cell returns the cell at the given position.
Cell(x, y int) *Cell
// SetCell sets the cell at the given position to the given cell. It
// returns whether the cell was set successfully.
SetCell(x, y int, c *Cell) bool
// Bounds returns the bounds of the cell buffer.
Bounds() Rectangle
}
CellBuffer is a cell buffer that represents a set of cells in a screen or a grid.
type Line ¶
type Line []*Cell
Line represents a line in the terminal. A nil cell represents an blank cell, a cell with a space character and a width of 1. If a cell has no content and a width of 0, it is a placeholder for a wide cell.
func (Line) At ¶
At returns the cell at the given x position. If the cell does not exist, it returns nil.
func (Line) Set ¶
Set sets the cell at the given x position. If a wide cell is given, it will set the cell and the following cells to EmptyCell. It returns true if the cell was set.
func (Line) String ¶
String returns the string representation of the line. Any trailing spaces are removed.
type Link ¶
Link represents a hyperlink in the terminal screen.
func ConvertLink ¶
func ConvertLink(h Link, p colorprofile.Profile) Link
ConvertLink converts a hyperlink to respect the given color profile.
func (*Link) Equal ¶
Equal returns whether the hyperlink is equal to the other hyperlink.
type PenWriter ¶
type PenWriter struct {
// contains filtered or unexported fields
}
PenWriter is a writer that writes to a buffer and keeps track of the current pen style and link state for the purpose of wrapping with newlines.
func (*PenWriter) Close ¶
Close closes the writer, resets the style and link if necessary, and releases its parser. Calling it is performance critical, but forgetting it does not cause safety issues or leaks.
type Position ¶
Position represents an x, y position.
type Rectangle ¶
Rectangle represents a rectangle.
type Screen ¶
type Screen struct {
// contains filtered or unexported fields
}
Screen represents the terminal screen.
func NewScreen ¶
func NewScreen(w io.Writer, width, height int, opts *ScreenOptions) (s *Screen)
NewScreen creates a new Screen.
func (*Screen) Clear ¶
Clear clears the screen with blank cells. This is a convenience method for Screen.Fill with a nil cell.
func (*Screen) ClearRect ¶
ClearRect clears the given rectangle with blank cells. This is a convenience method for Screen.FillRect with a nil cell.
func (*Screen) Close ¶
Close writes the final screen update and resets the screen.
func (*Screen) EnterAltScreen ¶
func (s *Screen) EnterAltScreen()
EnterAltScreen enters the alternate screen buffer.
func (*Screen) ExitAltScreen ¶
func (s *Screen) ExitAltScreen()
ExitAltScreen exits the alternate screen buffer.
func (*Screen) FillRect ¶
FillRect implements Window.
func (*Screen) InsertAbove ¶
InsertAbove inserts string above the screen. The inserted string is not managed by the screen. This does nothing when alternate screen mode is enabled.
func (*Screen) MoveTo ¶
MoveTo moves the cursor to the given position.
func (*Screen) Render ¶
func (s *Screen) Render()
Render renders changes of the screen to the internal buffer. Call Screen.Flush to flush pending changes to the screen.
func (*Screen) SetCell ¶
SetCell implements Window.
func (*Screen) SetColorProfile ¶
func (s *Screen) SetColorProfile(p colorprofile.Profile)
SetColorProfile sets the color profile to use when writing to the screen.
func (*Screen) SetMethod ¶
SetMethod sets the method used to calculate the width of cells.
func (*Screen) SetRelativeCursor ¶
SetRelativeCursor sets whether to use relative cursor movements.
func (*Screen) UseBackspaces ¶
UseBackspaces sets whether to use backspace characters to move the cursor.
func (*Screen) UseHardTabs ¶
UseHardTabs sets whether to use hard tabs to optimize cursor movements.
type ScreenOptions ¶
type ScreenOptions struct {
// Term is the terminal type to use when writing to the screen. When empty,
// `$TERM` is used from [os.Getenv].
Term string
// Profile is the color profile to use when writing to the screen.
Profile colorprofile.Profile
// RelativeCursor is whether to use relative cursor movements. This is
// useful when alt-screen is not used or when using inline mode.
RelativeCursor bool
// AltScreen is whether to use the alternate screen buffer.
AltScreen bool
// ShowCursor is whether to show the cursor.
ShowCursor bool
// HardTabs is whether to use hard tabs to optimize cursor movements.
HardTabs bool
// Backspace is whether to use backspace characters to move the cursor.
Backspace bool
// MapNL whether we have ONLCR mapping enabled. When we set the terminal to
// raw mode, the ONLCR mode gets disabled. ONLCR maps any newline/linefeed
// (`\n`) character to carriage return + line feed (`\r\n`).
MapNL bool
}
ScreenOptions are options for the screen.
type ScreenWriter ¶
type ScreenWriter struct {
*Screen
}
ScreenWriter represents a writer that writes to a Screen parsing ANSI escape sequences and Unicode characters and converting them into cells that can be written to a cell Buffer.
func NewScreenWriter ¶
func NewScreenWriter(s *Screen) *ScreenWriter
NewScreenWriter creates a new ScreenWriter that writes to the given Screen. This is a convenience function for creating a ScreenWriter.
func (*ScreenWriter) Print ¶
func (s *ScreenWriter) Print(str string, v ...any)
Print prints the string at the current cursor position. It will wrap the string to the width of the screen if it exceeds the width of the screen. This will recognize ANSI ansi.SGR style and ansi.SetHyperlink escape sequences.
func (*ScreenWriter) PrintAt ¶
func (s *ScreenWriter) PrintAt(x, y int, str string, v ...any)
PrintAt prints the string at the given position. It will wrap the string to the width of the screen if it exceeds the width of the screen. This will recognize ANSI ansi.SGR style and ansi.SetHyperlink escape sequences.
func (*ScreenWriter) PrintCrop ¶
func (s *ScreenWriter) PrintCrop(str string, tail string)
PrintCrop prints the string at the current cursor position and truncates the text if it exceeds the width of the screen. Use tail to specify a string to append if the string is truncated. This will recognize ANSI ansi.SGR style and ansi.SetHyperlink escape sequences.
func (*ScreenWriter) PrintCropAt ¶
func (s *ScreenWriter) PrintCropAt(x, y int, str string, tail string)
PrintCropAt prints the string at the given position and truncates the text if it exceeds the width of the screen. Use tail to specify a string to append if the string is truncated. This will recognize ANSI ansi.SGR style and ansi.SetHyperlink escape sequences.
func (*ScreenWriter) SetContent ¶
func (s *ScreenWriter) SetContent(str string)
SetContent clears the screen with blank cells, and sets the given string as its content. If the height or width of the string exceeds the height or width of the screen, it will be truncated.
This will recognize ANSI ansi.SGR style and ansi.SetHyperlink escape sequences.
func (*ScreenWriter) SetContentRect ¶
func (s *ScreenWriter) SetContentRect(str string, rect Rectangle)
SetContentRect clears the rectangle within the screen with blank cells, and sets the given string as its content. If the height or width of the string exceeds the height or width of the screen, it will be truncated.
This will recognize ANSI ansi.SGR style and ansi.SetHyperlink escape sequences.
func (*ScreenWriter) Write ¶
func (s *ScreenWriter) Write(p []byte) (n int, err error)
Write writes the given bytes to the screen. This will recognize ANSI ansi.SGR style and ansi.SetHyperlink escape sequences.
type Style ¶
type Style struct {
Fg ansi.Color
Bg ansi.Color
Ul ansi.Color
Attrs AttrMask
UlStyle UnderlineStyle
}
Style represents the Style of a cell.
func ConvertStyle ¶
func ConvertStyle(s Style, p colorprofile.Profile) Style
ConvertStyle converts a style to respect the given color profile.
func (*Style) Background ¶
Background sets the background color.
func (*Style) Clear ¶
Clear returns whether the style consists of only attributes that don't affect appearance of a space character.
func (Style) DiffSequence ¶
DiffSequence returns the ANSI sequence that sets the style as a diff from another style.
func (*Style) Equal ¶
Equal returns true if the style is equal to the other style.
func (*Style) Foreground ¶
Foreground sets the foreground color.
func (*Style) RapidBlink ¶
RapidBlink sets the rapid blink attribute.
func (Style) Sequence ¶
Sequence returns the ANSI sequence that sets the style.
func (*Style) SlowBlink ¶
SlowBlink sets the slow blink attribute.
func (*Style) Strikethrough ¶
Strikethrough sets the strikethrough attribute.
func (*Style) Underline ¶
Underline sets the underline attribute. This is a syntactic sugar for UnderlineStyle.
func (*Style) UnderlineColor ¶
UnderlineColor sets the underline color.
func (*Style) UnderlineStyle ¶
func (s *Style) UnderlineStyle(style UnderlineStyle) *Style
UnderlineStyle sets the underline style.
type TabStops ¶
type TabStops struct {
// contains filtered or unexported fields
}
TabStops represents horizontal line tab stops.
func DefaultTabStops ¶
DefaultTabStops creates a new set of tab stops with the default interval.
func NewTabStops ¶
NewTabStops creates a new set of tab stops from a number of columns and an interval.
func (TabStops) Find ¶
Find returns the prev/next tab stop before/after the given column and delta. If delta is positive, it returns the next tab stop after the given column. If delta is negative, it returns the previous tab stop before the given column. If delta is zero, it returns the given column.
func (TabStops) IsStop ¶
IsStop returns true if the given column is a tab stop.
func (TabStops) Next ¶
Next returns the next tab stop after the given column.
func (TabStops) Prev ¶
Prev returns the previous tab stop before the given column.
func (*TabStops) Reset ¶
Reset removes the tab stop at the given column.
func (*TabStops) Resize ¶
Resize resizes the tab stops to the given width.
type UnderlineStyle ¶
type UnderlineStyle = ansi.UnderlineStyle
UnderlineStyle is the style of underline to use for text.
Source Files
¶
- buffer.go
- cell.go
- errors.go
- geom.go
- hardscroll.go
- hashmap.go
- link.go
- pen.go
- screen.go
- sequence.go
- style.go
- tabstop.go
- utils.go
- wrap.go
- writer.go