pd93 / ansi Goto Github PK

If you've ever worked on a CLI application before, you probably know the struggle of working with ANSI escape codes. Often, you just want to quickly apply a style to a string, but you either have to interrupt your workflow to look up the escape sequence and codes, or you have to import a large package that does more than you need.

The ansi package is extremely lightweight 🪶 and has no external dependencies 📦 It allows you to quickly apply styles to strings using human-readable style blocks. Because the styles are defined inline, there is no need to call a function for each style, making it easy to apply/reset multiple styles to a single string.

With ansi, the mess at the top of this page becomes:

Strings are formatted using "style blocks". A style block is delimited by square brackets ([]) and contains a list of styles separated by colons. For example, the style block [red:bold] applies the red and bold styles to any text following the block.

Styles can be reset by using the corresponding reset code or by using the global reset ([/]) to reset all styles.

import "github.com/pd93/ansi"

str := ansi.Parse("This is a [red:bold]red and bold[/] string")
fmt.Println(str)

// Or use the provided fmt package function wrappers
ansi.Println("This is a [red:bold]red and bold[/] string")

If you need to print a literal string that conflicts with a valid style block, you can escape the block by prepending it with a backslash (\). For example, \[red] will print [red] instead of applying the red style.

// Note that we need to escape the escaping backslash otherwise it will be removed.
ansi.Println("This is \\[red:bold]an escaped style block\\[/]")

// We can avoid this in most situations by using a raw string (backticks) instead:
ansi.Println(`This is \[red:bold]an escaped style block\[/]`)

For more info, check out the style reference below or take a look at our examples.

* faint and dim do not work when using 8-bit (256) or 24-bit (RGB) color modes.

** The /bold, /faint, and /dim codes all equal because they share an ANSI code. This means it is not possible to reset them individually.