render

Documentation

Overview

Package render is the cell-diffing renderer behind the root package's default renderer. Cells.Frame turns a view, either lines of styled text or a GridSource drawn directly, into a grid of cells, compares it with the previous frame and emits only the escape sequences and text needed to repaint the cells that changed. It performs no terminal I/O itself: callers write the bytes it returns.

Index

• func AppendSGR(dst []byte, from, to Style) []byte
• func BidiLine(line string, m ansi.Measurer) string
• func KittyDelete(id uint32) string
• type Cells
  • func New() *Cells
  • func (c *Cells) Frame(in Frame) (string, Stats, bool)
  • func (c *Cells) GridRows() int
  • func (c *Cells) Invalidate()
  • func (c *Cells) PatchedRows() []bool
  • func (c *Cells) Reason() string
  • func (c *Cells) SetNoCache(v bool)
  • func (c *Cells) SetNoPatch(v bool)
  • func (c *Cells) Valid() bool
  • func (c *Cells) Width() int
• type Frame
• type Glyph
  • func ParseGlyphs(line string, m ansi.Measurer) (glyphs []Glyph, reason string, ok bool)
• type GridSource
• type RowFallback
• type Stats
• type Style

Functions

func AppendSGR

func AppendSGR(dst []byte, from, to Style) []byte

AppendSGR appends the SGR bytes that take the terminal from pen from to pen to (nothing when the SGR state is equal). Links are not part of SGR and are ignored.

func BidiLine

func BidiLine(line string, m ansi.Measurer) string

BidiLine returns line with its characters in visual order per the Unicode Bidirectional Algorithm (UAX #9), taking the paragraph direction from the first strong character, for terminals that draw text in logical order. Each character keeps its own style and hyperlink, and a character at an odd level that has an exact mirror image (a bracket) is replaced by it.

A line with no right-to-left or formatting character, and a line the cell parser declines (graphics, malformed escapes), is returned unchanged, byte for byte. The reordering is for display only; the caller keeps the logical text.

func KittyDelete

func KittyDelete(id uint32) string

KittyDelete returns the kitty graphics command that deletes every placement of image id and frees its data, with the terminal's reply suppressed.

Types

type Cells

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

func New

func New() *Cells

func (*Cells) Frame

func (c *Cells) Frame(in Frame) (string, Stats, bool)

Frame draws in.Lines (padded to in.Max rows) as the change from the previous frame. ok is false when this frame must be drawn by the line renderer instead; nothing has been recorded then, and Reason says why. With in.LazyFit the lines are not yet fitted to the terminal: this fits each one it cannot show to be unchanged in width with in.FitLine, in place.

func (*Cells) GridRows

func (c *Cells) GridRows() int

GridRows is the number of rows in the held previous frame. For tests.

func (*Cells) Invalidate

func (c *Cells) Invalidate()

Invalidate drops the previous frame, so the next Frame redraws every row.

func (*Cells) PatchedRows

func (c *Cells) PatchedRows() []bool

PatchedRows reports, per row of the last frame, whether it was patched rather than parsed. For tests.

func (*Cells) Reason

func (c *Cells) Reason() string

Reason is why the last Frame fell back to the line renderer, a slug such as "control_character"; "" when it did not.

func (*Cells) SetNoCache

func (c *Cells) SetNoCache(v bool)

SetNoCache makes every row be parsed every frame. For tests and benchmarks.

func (*Cells) SetNoPatch

func (c *Cells) SetNoPatch(v bool)

SetNoPatch stops rows being patched from the previous frame. For tests.

func (*Cells) Valid

func (c *Cells) Valid() bool

Valid reports whether a previous frame is held for diffing.

func (*Cells) Width

func (c *Cells) Width() int

Width is the terminal width the previous frame was fitted to.

type Frame

type Frame struct {
	Lines         []string      // the view, one string per row
	Max           int           // rows to draw: max(len(Lines), rows of the previous frame)
	LazyFit       bool          // Lines are not yet fitted to Width; see Cells.Frame
	Width, Height int           // terminal size; Height <= 0 when unknown
	PrevRows      int           // rows the caller recorded for the previous frame; 0 for none
	RegionTop     func() string // moves the cursor to the top of the live region
	FitLine       func(string) string
	Measurer      ansi.Measurer // how the terminal draws grapheme clusters; zero follows the process default
	// Grid, when non-nil, is drawn instead of Lines: GridRows rows of Width
	// columns, with no string parsed. Rows past GridRows (up to Max) are blank.
	Grid     GridSource
	GridRows int
}

Frame is one frame for Cells.Frame.

type Glyph

type Glyph struct {
	Text  string
	Width uint8
	Style Style
}

Glyph is one parsed cell: a head cell carries its cluster text and width (1 or 2); the continuation cell of a wide cluster has Width 0 and no Text.

func ParseGlyphs

func ParseGlyphs(line string, m ansi.Measurer) (glyphs []Glyph, reason string, ok bool)

ParseGlyphs parses one view line (no newline) into cells with the same rules the cell renderer applies, measuring widths with m. ok is false, with the renderer's fallback slug in reason, when the line uses something the grid cannot represent. Trailing blank cells are kept.

type GridSource

type GridSource interface {
	// Cell returns the cell at column x of row y: its cluster text ("" for the
	// continuation of a wide cluster), its width (0, 1 or 2) and its style.
	Cell(x, y int) (text string, width uint8, st Style)
}

GridSource is a grid of cells that Cells.Frame draws without parsing a string: the entry point for models that draw cells directly.

type RowFallback

type RowFallback struct {
	Row    int    // 0-based row of the frame
	Reason string // slug, for example "control_character"
}

RowFallback names a row drawn with the line strategy and why.

type Stats

type Stats struct {
	Rows, Changed int
	Full          bool
	// Fallbacks lists the rows drawn with the line strategy this frame (rows
	// the grid could not represent) and why; nil when there were none. The
	// slice is reused by the next Frame.
	Fallbacks []RowFallback
}

Stats describes a drawn frame, for the frame log.

type Style

type Style struct {
	Attrs  uint16
	FG, BG uint32
	UL     uint8
	Link   string
}

Style is the decoded pen of a cell with the colours and attributes in the renderer's own encoding (see cellStyle). Link is the hyperlink target URI, "" for none. It is comparable.