textbuffer

Documentation

Overview

Package textbuffer implements a buffer for displaying and editing UTF-8 text.

Lines are separated by newlines ('\n', the Unicode code point U+000A) and the newline character is not contained explicitly in the lines of a text buffer. This makes addressing lines trivial, we use the y-coordinate starting at 0 for addressing them.

However, handling UTF-8 within lines is more complicated and we have to differentiate multiple coordinate systems to handle them properly:

• the rune coordinate system
• the character coordinate system
• the cell coordinate system

On the lowest level UTF-8 text is just an ordinary stream of bytes (Go type: byte). A text buffer does not explicitly address bytes.

One or multiple bytes encode one UTF-8 code point (Go type: rune). Package "unicode/utf8" is used to split bytes into runes. We address runes in the rune coordinate system starting at 0.

One or multiple runes encode one character. The mapping between runes and characters is usually one-to-one. That is, one rune encodes one character. However, UTF-8 also allows combining characters, for example for diacritical marks. This leads to different possible UTF-8 encodings for some characters and for other characters a multiple rune encoding is the only possible one. With the help of package "github.com/mattn/go-runewidth" a stream of runes is split into characters. We address characters in the character coordinate system starting at 0.

When displaying characters in a terminal they usually occupy one cell. However, wide characters occupy two cells (for example, East Asian full width characters). Package "github.com/mattn/go-runewidth" is used to determine the width of characters. We address cells in the cell coordinate system starting at 0.

For more information on UTF-8 in Go see also https://blog.golang.org/strings

Index

• Constants
• type TextBuffer
  • func New(b []byte) *TextBuffer
  • func (tb *TextBuffer) GetCell(x, y int) (c []rune, width int)
  • func (tb *TextBuffer) GetChar(x, y int) []rune
  • func (tb *TextBuffer) GetRune(x, y int) rune
  • func (tb *TextBuffer) LineLenCell(y int) int
  • func (tb *TextBuffer) LineLenChar(y int) int
  • func (tb *TextBuffer) LineLenRune(y int) int
  • func (tb *TextBuffer) Lines() int
  • func (tb *TextBuffer) MaxLineLenCell() int
  • func (tb *TextBuffer) Write(w io.Writer) error

Constants

const (
	// SOS defines the start of string (used for links)
	SOS = "\x1bX"
	// APC defines the application program command (NOWRAP, CURSOR, ENDSOS)
	APC = "\x1b_"
	// ST defines the string terminator, terminates SOS and APC
	ST = "\x1b\\"
)

Types

type TextBuffer

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

TextBuffer is a line-oriented text buffer for displaying and editing UTF-8 text.

func New

func New(b []byte) *TextBuffer

New converts the UTF-8 buffer b into a new TextBuffer.

func (*TextBuffer) GetCell

func (tb *TextBuffer) GetCell(x, y int) (c []rune, width int)

GetCell returns the character c in line y at position x of the cell coordinate system. It also returns the width of the character: 1: narrow, 2: wide, first half, 0: wide, second half.

func (*TextBuffer) GetChar

func (tb *TextBuffer) GetChar(x, y int) []rune

GetChar returns the character in line y at position x of the character coordinate system.

func (*TextBuffer) GetRune

func (tb *TextBuffer) GetRune(x, y int) rune

GetRune returns the rune in line y at position x of the rune coordinate system.

func (*TextBuffer) LineLenCell

func (tb *TextBuffer) LineLenCell(y int) int

LineLenCell returns the length of line y in the cell coordinate system. Returns 0 if y is an invalid coordinate.

func (*TextBuffer) LineLenChar

func (tb *TextBuffer) LineLenChar(y int) int

LineLenChar returns the length of line y in the character coordinate system. Returns 0 if y is an invalid coordinate.

func (*TextBuffer) LineLenRune

func (tb *TextBuffer) LineLenRune(y int) int

LineLenRune returns the length of line y in the rune coordinate system. Returns 0 if y is an invalid coordinate.

func (*TextBuffer) Lines

func (tb *TextBuffer) Lines() int

Lines returns the number of lines.

func (*TextBuffer) MaxLineLenCell

func (tb *TextBuffer) MaxLineLenCell() int

MaxLineLenCell returns the maximum line length in the cell coordinate system.

func (*TextBuffer) Write

func (tb *TextBuffer) Write(w io.Writer) error

Write writes the content of tb to w (including newlines).