ansi

README

A library for parsing ANSI encoded strings

Go ANSI Parser converts strings with ANSI escape codes into a slice of structs that represent styled text. Features:

• Can parse ANSI 16, 256 and TrueColor
• Supports all styles: Regular, Bold, Faint, Italic, Blinking, Inversed, Invisible, Underlined, Strikethrough
• Provides RGB, Hex, HSL, ANSI ID and Name for parsed colours
• Truncation - works with emojis and grapheme clusters
• Length - works with emojis and grapheme clusters
• Cleanse - removes the ansi escape codes
• Configurable colour map for customisation
• 100% Test Coverage

Installation

go get github.com/leaanthony/go-ansi-parser

Usage

Parse

text, err := ansi.Parse("\u001b[1;31;40mHello World\033[0m")

// is the equivalent of...

text := []*ansi.StyledText{
    {
        Label: "Hello World",
        FgCol: &ansi.Col{
            Id:   9,
            Hex:  "#ff0000",
            Rgb:  &ansi.Rgb{ R: 255, G: 0, B: 0 },
            Hsl:  &ansi.Hsl{ H: 0, S: 100, L: 50 },
            Name: "Red",
        },
        BgCol: &ansi.Col{
            Id:   0,
            Hex:  "#000000",
            Rgb:  &ansi.Rgb{0, 0, 0},
            Hsl:  &ansi.Hsl{0, 0, 0},
            Name: "Black",
        },
        Style: 1,
    },
}

Truncating

shorter, err := ansi.Truncate("\u001b[1;31;40mHello\033[0m \u001b[0;30mWorld!\033[0m", 8)

// is the equivalent of...

shorter := "\u001b[1;31;40mHello\033[0m \u001b[0;30mWo\033[0m"

Cleanse

cleaner, err := ansi.Cleanse("\u001b[1;31;40mHello\033[0m \u001b[0;30mWorld!\033[0m")

// is the equivalent of...

cleaner := "Hello World!"

Length

length, err := ansi.Length("\u001b[1;31;40mHello\033[0m \u001b[0;30mWorld!\033[0m")

// is the equivalent of...

length := 12

// Works with grapheme clusters and emoji
length, err := ansi.Length("\u001b[1;31;40m👩🏽‍🔧😎\033[0m") // 2

Documentation

Index

• Variables
• func Cleanse(input string) (string, error)
• func HasEscapeCodes(input string) bool
• func Length(input string) (int, error)
• func String(input []*StyledText) string
• func Truncate(input string, maxChars int) (string, error)
• type Col
• type Hsl
• type Rgb
• type StyledText
  • func Parse(input string) ([]*StyledText, error)
  • func (s *StyledText) Blinking() bool
  • func (s *StyledText) Bold() bool
  • func (s *StyledText) Faint() bool
  • func (s *StyledText) Inversed() bool
  • func (s *StyledText) Invisible() bool
  • func (s *StyledText) Italic() bool
  • func (s *StyledText) Strikethrough() bool
  • func (s *StyledText) String() string
  • func (s *StyledText) Underlined() bool
• type TextStyle

Variables

var ColourMap = map[string]map[string]*Col{
	"Regular": {
		"30": Cols[0],
		"31": Cols[1],
		"32": Cols[2],
		"33": Cols[3],
		"34": Cols[4],
		"35": Cols[5],
		"36": Cols[6],
		"37": Cols[7],
	},
	"Bold": {
		"30": Cols[8],
		"31": Cols[9],
		"32": Cols[10],
		"33": Cols[11],
		"34": Cols[12],
		"35": Cols[13],
		"36": Cols[14],
		"37": Cols[15],
	},
	"Faint": {
		"30": Cols[0],
		"31": Cols[1],
		"32": Cols[2],
		"33": Cols[3],
		"34": Cols[4],
		"35": Cols[5],
		"36": Cols[6],
		"37": Cols[7],
	},
}

ColourMap maps ansi identifiers to a colour

var Cols = []*Col{}/* 256 elements not displayed */

Cols represents the default colour definitions used by the library. This may be overridden.

Functions

func Cleanse

func Cleanse(input string) (string, error)

func HasEscapeCodes

func HasEscapeCodes(input string) bool

func Length

func Length(input string) (int, error)

func String

func String(input []*StyledText) string

func Truncate

func Truncate(input string, maxChars int) (string, error)

Types

type Col

type Col struct {
	Id   int    `json:"id"`
	Hex  string `json:"hex"`
	Rgb  Rgb    `json:"rgb"`
	Hsl  Hsl    `json:"hsl"`
	Name string `json:"name"`
}

Col represents a colour value. The Id is the ANSI colour ID.

type Hsl

type Hsl struct {
	H float64 `json:"h"`
	S float64 `json:"s"`
	L float64 `json:"l"`
}

Hsl represents the HSL value of the colour

type Rgb

type Rgb struct {
	R uint8 `json:"r"`
	G uint8 `json:"g"`
	B uint8 `json:"b"`
}

Rgb represents an RGB colour value with 8bits per channel

type StyledText

type StyledText struct {
	Label string
	FgCol *Col
	BgCol *Col
	Style TextStyle
}

StyledText represents a single formatted string

func Parse

func Parse(input string) ([]*StyledText, error)

Parse will convert an ansi encoded string and return a slice of StyledText structs that represent the text. If parsing is unsuccessful, an error is returned.

func (*StyledText) Blinking

func (s *StyledText) Blinking() bool

Blinking will return true if the text has a Blinking style

func (*StyledText) Bold

func (s *StyledText) Bold() bool

Bold will return true if the text has a Bold style

func (*StyledText) Faint

func (s *StyledText) Faint() bool

Faint will return true if the text has a Faint style

func (*StyledText) Inversed

func (s *StyledText) Inversed() bool

Inversed will return true if the text has an Inversed style

func (*StyledText) Invisible

func (s *StyledText) Invisible() bool

Invisible will return true if the text has an Invisible style

func (*StyledText) Italic

func (s *StyledText) Italic() bool

Italic will return true if the text has an Italic style

func (*StyledText) Strikethrough

func (s *StyledText) Strikethrough() bool

Strikethrough will return true if the text has a Strikethrough style

func (*StyledText) String

func (s *StyledText) String() string

func (*StyledText) Underlined

func (s *StyledText) Underlined() bool

Underlined will return true if the text has an Underlined style

type TextStyle

type TextStyle int

TextStyle is a type representing the ansi text styles

const (
	// Bold Style
	Bold TextStyle = 1 << 0
	// Faint Style
	Faint TextStyle = 1 << 1
	// Italic Style
	Italic TextStyle = 1 << 2
	// Blinking Style
	Blinking TextStyle = 1 << 3
	// Inversed Style
	Inversed TextStyle = 1 << 4
	// Invisible Style
	Invisible TextStyle = 1 << 5
	// Underlined Style
	Underlined TextStyle = 1 << 6
	// Strikethrough Style
	Strikethrough TextStyle = 1 << 7
)