Colorful text in your terminal implemented in Go

The termcols package implements ANSI color codes that can be used to color text on the terminal. Different styles and foreground/background colors can be chained together through an intuitive package API to arrive at some cool visual effects.

The selection of style and color control sequences implemented by the package was largely based on an exhaustive list of Select Graphic Rendition (SGR) control sequences available at Wikipedia ANSI. It is a great resource in case one or more elements appear not to be supported in a given terminal.

The Escape sequence for termcols is set to \033, which means that it should work without any issues with Bash, Zsh or Dash. Other shells might not support it.

The same applies to 8-bit and 24-bit colors: there is no guarantee that these escape sequences are supported will be rendered properly on some terminals. Results may vary, so it is good practice to test it first for compatibility.

Consult the package documentation or see Usage section below to check how to use the public API of the termcols package.

Installation

Use the following command to add the package to an existing project.

go get github.com/mdm-code/termcols

Install the package to use the command-line tcols command to colorize text on the terminal.

go install github.com/mdm-code/termcols@latest

Usage

Here is an example of how to use the public API of the termcols package.

package main

import (
	"fmt"

	"github.com/mdm-code/termcols"
)

func main() {
	s := termcols.Colorize(
		"Colorized text!",
		termcols.RedFg,
		termcols.Underline,
		termcols.Rgb24(termcols.BG, 120, 255, 54),
	)
	fmt.Println(s)
}

Aside from using the termcols package API that can be used in your Go project, can use the tcols terminal command:

tcols --style 'redfg underline rgb24=bg:120:255:54' < <(echo -n 'Hello, world!')

Type tcols -h to get a list of styles and colors to (1) see what is implemented and (2) what is supported by your terminal.

Alternatively, tcols can be run from inside of the Docker container:

docker run --rm --tty --volume "$(pwd)/:/files" ghcr.io/mdm-code/tcols tcols -s "redfg bluebg" files/test.txt

This however, requires some additional configuration to how the container is run. The default stdout of the container is not recognized as tty by the process run inside of the container even though it would be printed out to the terminal by default. tcols detects if stdout is attached to tty or whether its piped to stdin of some other process. In the case of the latter, the output is not colored because additional SGR control sequences and escape sequences would mess up the text and possibly result in some unexpected output being piped out.

This means that in order to print out the colored output docker run has to include the --tty flag to attach the pseudo-tty to the container. This prevents piping data with through the stdin of the container as its already reserved by the pseudo-tty, so this option is out. tcols accepts file names as positional arguments, but since files are not immediately accessible from inside of the container, one way to go about it is to attach a volume to the container and then reference these files accordingly. This is what the example above does.

Development

Consult Makefile to see how to format, examine code with go vet, run unit test, run code linter with golint get test coverage and check if the package builds all right.

Remember to install golint before you try to run tests and test the build:

go install golang.org/x/lint/golint@latest

In order to run the benchmark test on unsafe pointers in the tercmols package, fire up the following command:

go test -bench=.

This will give you ns/op value for the setup it's been benchmarked on.

License

Copyright (c) 2024 Michał Adamczyk.

This project is licensed under the MIT license. See LICENSE for more details.