termtext

README

termtext is a Go package to deal with monospace text as interpreted by terminals.

Mostly intended to nearly align/wrap stuff terminal. There are a few tricky bits with this:

1. Multiple codepoints can be combined to render one character (or "grapheme cluster" in Unicode speak).
2. Some characters are rendered as double-width, such as East-Asian characters and some emojis.
3. A single tab can render as multiple spaces, and the number of spaces depends on its position in the string.
4. Some characters aren't actually printed to the screen, such as the zero-width space and escape sequences to set the colour.

uniseg takes care of the first point, go-runewidth of the second, and this package of the third and fourth.

Import as arp242.net/termtext – godoc: https://pkg.go.dev/arp242.net/termtext

---

The main function is Width(); for example:

Width("\ta")                → 9    Tab expands to 8 spaces, followed by a.
Width("a\t")                → 8    Tab expands to 7 spaces.
Width("🧑\t🧑")             → 10   🧑 is double-width
Width("\x1b[1mbold\x1b[0m") → 4    Escape sequences are ignored.

You can configure the tab width by setting termtext.TabWidth.

There are a few auxiliary functions:

Expand()            Expand tabs.
Slice()             Slice a string by display width, like str[n:m].

AlignLeft()         Align a string, filling up the remainder with spaces.
AlignRight()
AlignCenter()

Wrap()              Wrap a string, this is a simple wrap which just breaks
                    if a line is more than w characters.
WordWrap()          Word-wrap a string: lines are at most w characters, but
                    don't break in the middle of words.

Documentation

Overview

Package termtext deals with monospace text as interpreted by terminals.

Index

• Variables
• func AlignCenter(s string, w int) string
• func AlignLeft(s string, w int) string
• func AlignRight(s string, w int) string
• func Expand(s string) string
• func Slice(s string, start, stop int) string
• func Width(s string) int
• func WordWrap(s string, w int, prefix string) string
• func Wrap(s string, w int, prefix string) string

Variables

var TabWidth = 8

Number of spaces to count a tab as.

Functions

func AlignCenter

func AlignCenter(s string, w int) string

AlignCenter centre-aligns a string, filling up any remaining width with spaces.

Tabs will be expanded to spaces.

func AlignLeft

func AlignLeft(s string, w int) string

AlignLeft left-aligns a string, filling up any remaining width with spaces.

Tabs will be expanded to spaces.

func AlignRight

func AlignRight(s string, w int) string

AlignRight right-aligns a string, filling up any remaining width with spaces.

Tabs will be expanded to spaces.

func Expand

func Expand(s string) string

Expand tabs to spaces.

func Slice

func Slice(s string, start, stop int) string

Slice a string by character index. This works the same as str[n:m] slicing.

Tabs will be expanded to spaces.

func Width

func Width(s string) int

Width gets the display width of a string.

The "display width" is the number of columns a string will occupy in a monospace terminal.

func WordWrap

func WordWrap(s string, w int, prefix string) string

WordWrap wraps lines to be at most w characters wide, but doesn't break in the middle of words.

Lines will be prefixed with prefix. The prefix isn't counted in line length calculations.

Tabs will be expanded to spaces.

func Wrap

func Wrap(s string, w int, prefix string) string

Wrap lines to be at most w characters wide.

Lines will be prefixed with prefix. The prefix isn't counted in line length calculations.

This does not use word wrap, use WordWrap() for this instead.

Tabs will be expanded to spaces.