git.sr.ht/~rj/sgr

Package sgr

Package sgr provides formatters to write ANSI escape sequences that can format and colorize text.

• Coverage of the Select Graphic Rendition (SGR) section of the ANSI escape sequences.
• Statically typed API avoids the use of untyped or embedded formatting strings.
• Automatic mapping to lower bit-width colours, when necessary, to match the terminal's support
• Performance aware API.
• Compatible with using io.Writer and the standard library.

Install

The package can be installed from the command line using the go tool. There are no dependencies beyond the standard library. Any version of Go should work.

go get git.sr.ht/~rj/sgr

Getting Started

Package documentation and examples are on Go Reference.

As a small introduction, the following snippet prints to the console using some bold text. You can experiment with the snippet on the go playground.

func main() {
	// The formatter is responsible for deciding when and what escape
	// codes to use.  The call to NewFormatter will return a formatter
	// suitable for use with standard out.
	f := sgr.NewFormatter()

	// Print some text with bold.
	fmt.Println("Hello,", f.Bold("world!"))
}

Contribute

To submit bug reports and suggestions, please use the issue tracker.

Discussions occur using the mailing list. The mailing list can also be used to submit patches.

Scope

This packages does not aim to support a complete list of SGR escape codes, either for all possible terminals or even as defined in the standard. The supported codes should be widely portable across many terminals and operating systems.

Windows: Terminals on windows will increasingly support ANSI escape sequences, but current support may be uneven. The legacy API for setting text attributes has been, if not deprecated, discouraged. Therefore, direct support for the legacy API is not planned. If older terminials must be supported, then go-colorable can be used.

Related Projects

• github.com/fatih/color: Color lets you use colorized outputs in terms of ANSI Escape Codes in Go (Golang).
• github.com/mattn/go-colorable: Colorable writer for windows.
• github.com/mitchellh/colorstring: colorstring is a Go library for outputting colored strings to a console using a simple inline syntax in your string to specify the color to print as.
• github.com/wzshiming/ctc: The non-invasive cross-platform terminal color library does not need to modify the Print method.
• github.com/muesli/termenv: Lets you safely use advanced styling options on the terminal.
• github.com/gdamore/tcell: Tcell is a Go package that provides a cell based view for text terminals.
• github.com/juju/ansiterm: Package ansiterm provides a Writer that writes out the ANSI escape codes for color and styles.

License

BSD (c) Robert Johnstone