colors

README

🦜 colors

One more Go library for using colors in the terminal console. The most important features are:

• ANSI colors support (using Escape Sequences)
• Multi-thread safe
• Support FORCE_COLOR, NO_COLOR and TERM variables out of the box
• Super-lightweight and extremely fast
• Color codes are not pre-allocated, but cached (in memory) and re-used upon further usage
• Easy to integrate with the existing code-base
• Has no dependencies (except the standard library and golang.org/x)

Usage examples

package main

import (
  "fmt"

  "gh.tarampamp.am/colors"
)

func main() {
  fmt.Println((colors.FgGreen | colors.Bold).Wrap("green color + bold text"))

  var bg = colors.BgRed

  fmt.Printf("%s red background %s\n", bg.Start(), bg.Reset())

  colors.Enabled(false) // disable colors
  colors.Enabled(true)  // enable colors
}

For more examples see examples directory.

Documentation

Index

• func Enabled(newState ...bool) bool
• type TextStyle
  • func (ts *TextStyle) Add(styles ...TextStyle)
  • func (ts TextStyle) ColorCodes() (start, reset string)
  • func (ts TextStyle) Has(z TextStyle) bool
  • func (ts *TextStyle) Remove(styles ...TextStyle)
  • func (ts TextStyle) Reset() (reset string)
  • func (ts TextStyle) Start() (start string)
  • func (ts TextStyle) String() string
  • func (ts TextStyle) Wrap(s string) string

Examples

• TextStyle.Start
• TextStyle.Wrap

Functions

func Enabled

func Enabled(newState ...bool) bool

Enabled returns true if colors are enabled. Also, you can set a new state (enable or disable colors).

Types

type TextStyle

type TextStyle uint32

TextStyle is a set of text styles.

Developer note:

uint32 = 0b11111111111111111111111111111111
                                  ^^^^^^^^^ - foreground color
                                 ^ - bright foreground color bit
                        ^^^^^^^^^ - background color
                       ^ - bright background color bit
               ^^^^^^^^ - text style
              ^ - reset style bit
           ^^^ - reserved bits

Pretty doc: <https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797>

const (
	FgBlack   TextStyle = 1 << iota // Black text color
	FgRed                           // Red text color
	FgGreen                         // Green text color
	FgYellow                        // Yellow text color
	FgBlue                          // Blue text color
	FgMagenta                       // Magenta text color
	FgCyan                          // Cyan text color
	FgWhite                         // White text color
	FgDefault                       // Default text color

	FgBright // Bright text color, usage example: (FgRed | FgBright).Wrap("hello world")

	BgBlack   // Black background color
	BgRed     // Red background color
	BgGreen   // Green background color
	BgYellow  // Yellow background color
	BgBlue    // Blue background color
	BgMagenta // Magenta background color
	BgCyan    // Cyan background color
	BgWhite   // White background color
	BgDefault // Default background color

	BgBright // Bright background color, usage example: (BgRed | BgBright).Wrap("hello world")

	Bold      // Bold text
	Faint     // Faint text
	Italic    // Italic text
	Underline // Underline text
	Blinking  // Blinking text
	Reverse   // Reverse text
	Invisible // Invisible text
	Strike    // Strike text

	Reset // Reset text style

)

func (*TextStyle) Add

func (ts *TextStyle) Add(styles ...TextStyle)

Add adds styles to the test style.

func (TextStyle) ColorCodes

func (ts TextStyle) ColorCodes() (start, reset string)

ColorCodes returns color codes for the text style. Important note: the result of this function working does not depend on the colors enabling state.

func (TextStyle) Has

func (ts TextStyle) Has(z TextStyle) bool

Has returns true if provided text style included into this one.

func (*TextStyle) Remove

func (ts *TextStyle) Remove(styles ...TextStyle)

Remove removes provided text styles.

func (TextStyle) Reset

func (ts TextStyle) Reset() (reset string)

Reset returns current text style resetting code. An empty string will return when colors are disabled or when called on FgDefault, BgDefault, or Reset.

func (TextStyle) Start

func (ts TextStyle) Start() (start string)

Start returns current text style starting code. An empty string will return when colors are disabled.

Example

package main

import (
	"fmt"

	"gh.tarampamp.am/colors"
)

func main() {
	colors.Enabled(false) // change to true to see colors

	var style = colors.FgRed | colors.Bold

	fmt.Println(style.Start(), "Foo Bar", style.Reset())

}

Output:

Foo Bar

func (TextStyle) String

func (ts TextStyle) String() string

String returns a string starting text styling (useful for usage with fmt.Sprintf). Note: Don't forget to use Reset() to reset the styling (resting is NOT needed for FgDefault, BgDefault and Reset).

func (TextStyle) Wrap

func (ts TextStyle) Wrap(s string) string

Wrap wraps provided string with staring and reset color codes. The provided string will return without any modifications when colors are disabled.

Example

package main

import (
	"fmt"

	"gh.tarampamp.am/colors"
)

func main() {
	colors.Enabled(false) // change to true to see colors

	fmt.Println((colors.FgRed | colors.Bold).Wrap("Foo Bar"))

}

Output:

Foo Bar