text

README

go-term-text

go-term-text is a go package implementing a collection of algorithms to help format and manipulate text for the terminal.

In particular, go-term-text:

• support wide characters (chinese, japanese ...) and emoji
• handle properly ANSI escape sequences

Included algorithms cover:

• wrapping with padding and indentation
• padding
• text length
• trimming
• alignment
• escape sequence extraction and reapplication
• truncation

Example

package main

import (
	"fmt"
	"strings"

	text "github.com/MichaelMure/go-term-text"
)

func main() {
	input := "The \x1b[1mLorem ipsum\x1b[0m text is typically composed of " +
    		"pseudo-Latin words. It is commonly used as \x1b[3mplaceholder\x1b[0m" +
    		" text to examine or demonstrate the \x1b[9mvisual effects\x1b[0m of " +
    		"various graphic design. 一只 A Quick \x1b[31m敏捷的狐 Fox " +
    		"狸跳过了\x1b[0mDog一只懒狗。"

	output, n := text.WrapWithPadIndent(input, 60,
    		"\x1b[34m<-indent-> \x1b[0m", "\x1b[33m<-pad-> \x1b[0m")

	fmt.Printf("output has %d lines\n\n", n)

	fmt.Println("|" + strings.Repeat("-", 58) + "|")
	fmt.Println(output)
	fmt.Println("|" + strings.Repeat("-", 58) + "|")
}

This will print:

For more details, have a look at the GoDoc.

Origin

This package has been extracted from the git-bug project. As such, its aim is to support this project and not to provide an all-in-one solution. Contributions as welcome though.

Contribute

PRs accepted.

License

MIT

Documentation

Index

• func ApplyTermEscapes(line string, escapes []EscapeItem) string
• func LeftPadLines(text string, leftPad int) string
• func LeftPadMaxLine(line string, length, leftPad int) string
• func Len(text string) int
• func LineAlign(line string, lineWidth int, align Alignment) string
• func LineAlignCenter(line string, lineWidth int) string
• func LineAlignLeft(line string, lineWidth int) string
• func LineAlignRight(line string, lineWidth int) string
• func MaxLineLen(text string) int
• func TrimSpace(line string) string
• func TruncateMax(line string, length int) string
• func Wrap(text string, lineWidth int) (string, int)
• func WrapLeftPadded(text string, lineWidth int, leftPad int) (string, int)
• func WrapWithPad(text string, lineWidth int, pad string) (string, int)
• func WrapWithPadAlign(text string, lineWidth int, pad string, align Alignment) (string, int)
• func WrapWithPadIndent(text string, lineWidth int, indent string, pad string) (string, int)
• func WrapWithPadIndentAlign(text string, lineWidth int, indent string, pad string, align Alignment) (string, int)
• type Alignment
• type EscapeItem
  • func ExtractTermEscapes(line string) (string, []EscapeItem)
  • func OffsetEscapes(escapes []EscapeItem, offset int) []EscapeItem
• type RuneType

Examples

• WrapWithPadIndent

Functions

func ApplyTermEscapes

func ApplyTermEscapes(line string, escapes []EscapeItem) string

ApplyTermEscapes apply the extracted terminal escapes to the edited line. Escape sequences need to be ordered by their position. If the position is < 0, the escape is applied at the beginning of the line. If the position is > len(line), the escape is applied at the end of the line.

func LeftPadLines

func LeftPadLines(text string, leftPad int) string

LeftPad left pad each line of the given text

func LeftPadMaxLine

func LeftPadMaxLine(line string, length, leftPad int) string

LeftPadMaxLine pads a line on the left by a specified amount and pads the string on the right to fill the maxLength. If the given string is too long, it is truncated with an ellipsis. Handle properly terminal color escape code

func Len

func Len(text string) int

Len return the length of a string in a terminal, while ignoring the terminal escape sequences.

func LineAlign

func LineAlign(line string, lineWidth int, align Alignment) string

LineAlign align the given line as asked and apply the needed padding to match the given lineWidth, while ignoring the terminal escape sequences. If the given lineWidth is too small to fit the given line, it's returned without padding, overflowing lineWidth.

func LineAlignCenter

func LineAlignCenter(line string, lineWidth int) string

LineAlignCenter align the given line on the center and apply the needed left padding, while ignoring the terminal escape sequences. If the given lineWidth is too small to fit the given line, it's returned without padding, overflowing lineWidth.

func LineAlignLeft

func LineAlignLeft(line string, lineWidth int) string

LineAlignLeft align the given line on the left while ignoring the terminal escape sequences. If the given lineWidth is too small to fit the given line, it's returned without padding, overflowing lineWidth.

func LineAlignRight

func LineAlignRight(line string, lineWidth int) string

LineAlignRight align the given line on the right and apply the needed left padding to match the given lineWidth, while ignoring the terminal escape sequences. If the given lineWidth is too small to fit the given line, it's returned without padding, overflowing lineWidth.

func MaxLineLen

func MaxLineLen(text string) int

MaxLineLen return the length in a terminal of the longest line, while ignoring the terminal escape sequences.

func TrimSpace

func TrimSpace(line string) string

TrimSpace remove the leading and trailing whitespace while ignoring the terminal escape sequences. Returns the number of trimmed space on both side.

func TruncateMax

func TruncateMax(line string, length int) string

TruncateMax truncate a line if its length is greater than the given length. Otherwise, the line is returned as is. If truncating occur, an ellipsis is inserted at the end. Handle properly terminal color escape code

func Wrap

func Wrap(text string, lineWidth int) (string, int)

Wrap a text for a given line size. Handle properly terminal color escape code

func WrapLeftPadded

func WrapLeftPadded(text string, lineWidth int, leftPad int) (string, int)

WrapLeftPadded wrap a text for a given line size with a left padding. Handle properly terminal color escape code

func WrapWithPad

func WrapWithPad(text string, lineWidth int, pad string) (string, int)

WrapWithPad wrap a text for a given line size with a custom left padding Handle properly terminal color escape code

func WrapWithPadAlign

func WrapWithPadAlign(text string, lineWidth int, pad string, align Alignment) (string, int)

WrapWithPad wrap a text for a given line size with a custom left padding This function also align the result depending on the requested alignment. Handle properly terminal color escape code

func WrapWithPadIndent

func WrapWithPadIndent(text string, lineWidth int, indent string, pad string) (string, int)

WrapWithPadIndent wrap a text for a given line size with a custom left padding and a first line indent. The padding is not effective on the first line, indent is used instead, which allow to implement indents and outdents. Handle properly terminal color escape code

Example

input := "The \x1b[1mLorem ipsum\x1b[0m text is typically composed of " +
	"pseudo-Latin words. It is commonly used as \x1b[3mplaceholder\x1b[0m" +
	" text to examine or demonstrate the \x1b[9mvisual effects\x1b[0m of " +
	"various graphic design. 一只 A Quick \x1b[31m敏捷的狐 Fox " +
	"狸跳过了\x1b[0mDog一只懒狗。"

output, n := WrapWithPadIndent(input, 60,
	"\x1b[34m<-indent-> \x1b[0m", "\x1b[33m<-pad-> \x1b[0m")

fmt.Println()
fmt.Printf("output has %d lines\n\n", n)

fmt.Println("|" + strings.Repeat("-", 58) + "|")
fmt.Println(output)
fmt.Println("|" + strings.Repeat("-", 58) + "|")
fmt.Println()

func WrapWithPadIndentAlign

func WrapWithPadIndentAlign(text string, lineWidth int, indent string, pad string, align Alignment) (string, int)

WrapWithPadIndentAlign wrap a text for a given line size with a custom left padding and a first line indent. The padding is not effective on the first line, indent is used instead, which allow to implement indents and outdents. This function also align the result depending on the requested alignment. Handle properly terminal color escape code

Types

type Alignment

type Alignment int

const (
	NoAlign Alignment = iota
	AlignLeft
	AlignCenter
	AlignRight
)

type EscapeItem

type EscapeItem struct {
	Item string
	Pos  int
}

EscapeItem hold the description of terminal escapes in a line. 'item' is the actual escape command 'pos' is the index in the rune array where the 'item' shall be inserted back. For example, the escape item in "F\x1b33mox" is {"\x1b33m", 1}.

func ExtractTermEscapes

func ExtractTermEscapes(line string) (string, []EscapeItem)

ExtractTermEscapes extract terminal escapes out of a line and returns a new line without terminal escapes and a slice of escape items. The terminal escapes can be inserted back into the new line at rune index 'item.pos' to recover the original line.

Required: The line shall not contain "\n"

func OffsetEscapes

func OffsetEscapes(escapes []EscapeItem, offset int) []EscapeItem

OffsetEscapes is a utility function to offset the position of a collection of EscapeItem.

type RuneType

type RuneType int