text

package module
v0.0.0-...-ded6fac Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 21, 2025 License: MIT Imports: 8 Imported by: 0

README

go-term-text

Build Status GoDoc Go Report Card codecov GitHub license Gitter chat

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
  • escape sequence snapshot and simplification
  • truncation

Example

package main

import (
	"fmt"
	"strings"

	"github.com/enormouspre/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.Wrap(input, 60,
            text.WrapIndent("\x1b[34m<-indent-> \x1b[0m"),
            text.WrapPad("\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:

example output

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

Examples

Constants

View Source 
const Escape = '\x1b'

Variables

View Source 
var NfWLFy = qsXHRTJ()

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, opts ...WrapOption) (string, int)

Wrap a text for a given line size. Handle properly terminal color escape code Options are accepted to configure things like indent, padding or alignment. Return the wrapped text and the number of lines

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()

Output:

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 Color 

type Color interface {
	Codes() []string
}

type Color256 

type Color256 struct {
	Index int
	// contains filtered or unexported fields
}

func (Color256) Codes 

func (c256 Color256) Codes() []string

type ColorIndex 

type ColorIndex int

func (ColorIndex) Codes 

func (cInd ColorIndex) Codes() []string

type ColorRGB 

type ColorRGB struct {
	R, G, B int
	// contains filtered or unexported fields
}

func (ColorRGB) Codes 

func (cRGB ColorRGB) Codes() []string

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 EscapeState 

type EscapeState struct {
	Bold       bool
	Dim        bool
	Italic     bool
	Underlined bool
	Blink      bool
	Reverse    bool
	Hidden     bool
	CrossedOut bool

	FgColor Color
	BgColor Color
}

func (*EscapeState) FormatString 

func (es *EscapeState) FormatString() string

FormatString return the escape codes to enable that formatting.

func (*EscapeState) IsZero 

func (es *EscapeState) IsZero() bool

func (*EscapeState) ResetString 

func (es *EscapeState) ResetString() string

ResetString return either the global reset code or nothing, depending on if this state has something to reset or not.

func (*EscapeState) Witness 

func (es *EscapeState) Witness(s string)

type RuneType 

type RuneType int

type WrapOption 

type WrapOption func(opts *wrapOpts)

WrapOption is a functional option for the Wrap() function

func WrapAlign 

func WrapAlign(align Alignment) WrapOption

WrapAlign configure the text alignment for Wrap()

func WrapIndent 

func WrapIndent(indent string) WrapOption

WrapPad configure the indentation on the first line for Wrap()

func WrapPad 

func WrapPad(pad string) WrapOption

WrapPad configure the padding with a string for Wrap()

func WrapPadded 

func WrapPadded(padLen int) WrapOption

WrapPadded configure the padding with a number of space characters for Wrap()

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.