README

color PkgGoDev

Color lets you use colorized outputs in terms of ANSI Escape Codes in Go (Golang). It has support for Windows too! The API can be used in several ways, pick one that suits you.

Color

Install

go get github.com/fatih/color

Examples

Standard colors
// Print with default helper functions
color.Cyan("Prints text in cyan.")

// A newline will be appended automatically
color.Blue("Prints %s in blue.", "text")

// These are using the default foreground colors
color.Red("We have red")
color.Magenta("And many others ..")

Mix and reuse colors
// Create a new color object
c := color.New(color.FgCyan).Add(color.Underline)
c.Println("Prints cyan text with an underline.")

// Or just add them to New()
d := color.New(color.FgCyan, color.Bold)
d.Printf("This prints bold cyan %s\n", "too!.")

// Mix up foreground and background colors, create new mixes!
red := color.New(color.FgRed)

boldRed := red.Add(color.Bold)
boldRed.Println("This will print text in bold red.")

whiteBackground := red.Add(color.BgWhite)
whiteBackground.Println("Red text with white background.")
Use your own output (io.Writer)
// Use your own io.Writer output
color.New(color.FgBlue).Fprintln(myWriter, "blue color!")

blue := color.New(color.FgBlue)
blue.Fprint(writer, "This will print text in blue.")
Custom print functions (PrintFunc)
// Create a custom print function for convenience
red := color.New(color.FgRed).PrintfFunc()
red("Warning")
red("Error: %s", err)

// Mix up multiple attributes
notice := color.New(color.Bold, color.FgGreen).PrintlnFunc()
notice("Don't forget this...")
Custom fprint functions (FprintFunc)
blue := color.New(FgBlue).FprintfFunc()
blue(myWriter, "important notice: %s", stars)

// Mix up with multiple attributes
success := color.New(color.Bold, color.FgGreen).FprintlnFunc()
success(myWriter, "Don't forget this...")
Insert into noncolor strings (SprintFunc)
// Create SprintXxx functions to mix strings with other non-colorized strings:
yellow := color.New(color.FgYellow).SprintFunc()
red := color.New(color.FgRed).SprintFunc()
fmt.Printf("This is a %s and this is %s.\n", yellow("warning"), red("error"))

info := color.New(color.FgWhite, color.BgGreen).SprintFunc()
fmt.Printf("This %s rocks!\n", info("package"))

// Use helper functions
fmt.Println("This", color.RedString("warning"), "should be not neglected.")
fmt.Printf("%v %v\n", color.GreenString("Info:"), "an important message.")

// Windows supported too! Just don't forget to change the output to color.Output
fmt.Fprintf(color.Output, "Windows support: %s", color.GreenString("PASS"))
Plug into existing code
// Use handy standard colors
color.Set(color.FgYellow)

fmt.Println("Existing text will now be in yellow")
fmt.Printf("This one %s\n", "too")

color.Unset() // Don't forget to unset

// You can mix up parameters
color.Set(color.FgMagenta, color.Bold)
defer color.Unset() // Use it in your function

fmt.Println("All text will now be bold magenta.")
Disable/Enable color

There might be a case where you want to explicitly disable/enable color output. the go-isatty package will automatically disable color output for non-tty output streams (for example if the output were piped directly to less)

Color has support to disable/enable colors both globally and for single color definitions. For example suppose you have a CLI app and a --no-color bool flag. You can easily disable the color output with:


var flagNoColor = flag.Bool("no-color", false, "Disable color output")

if *flagNoColor {
	color.NoColor = true // disables colorized output
}

It also has support for single color definitions (local). You can disable/enable color output on the fly:

c := color.New(color.FgCyan)
c.Println("Prints cyan text")

c.DisableColor()
c.Println("This is printed without any color")

c.EnableColor()
c.Println("This prints again cyan...")

Todo

  • Save/Return previous values
  • Evaluate fmt.Formatter interface

Credits

License

The MIT License (MIT) - see LICENSE.md for more details

Expand ▾ Collapse ▴

Documentation

Overview

    Package color is an ANSI color package to output colorized or SGR defined output to the standard output. The API can be used in several way, pick one that suits you.

    Use simple and default helper functions with predefined foreground colors:

    color.Cyan("Prints text in cyan.")
    
    // a newline will be appended automatically
    color.Blue("Prints %s in blue.", "text")
    
    // More default foreground colors..
    color.Red("We have red")
    color.Yellow("Yellow color too!")
    color.Magenta("And many others ..")
    
    // Hi-intensity colors
    color.HiGreen("Bright green color.")
    color.HiBlack("Bright black means gray..")
    color.HiWhite("Shiny white color!")
    

    However there are times where custom color mixes are required. Below are some examples to create custom color objects and use the print functions of each separate color object.

    // Create a new color object
    c := color.New(color.FgCyan).Add(color.Underline)
    c.Println("Prints cyan text with an underline.")
    
    // Or just add them to New()
    d := color.New(color.FgCyan, color.Bold)
    d.Printf("This prints bold cyan %s\n", "too!.")
    
    // Mix up foreground and background colors, create new mixes!
    red := color.New(color.FgRed)
    
    boldRed := red.Add(color.Bold)
    boldRed.Println("This will print text in bold red.")
    
    whiteBackground := red.Add(color.BgWhite)
    whiteBackground.Println("Red text with White background.")
    
    // Use your own io.Writer output
    color.New(color.FgBlue).Fprintln(myWriter, "blue color!")
    
    blue := color.New(color.FgBlue)
    blue.Fprint(myWriter, "This will print text in blue.")
    

    You can create PrintXxx functions to simplify even more:

    // Create a custom print function for convenient
    red := color.New(color.FgRed).PrintfFunc()
    red("warning")
    red("error: %s", err)
    
    // Mix up multiple attributes
    notice := color.New(color.Bold, color.FgGreen).PrintlnFunc()
    notice("don't forget this...")
    

    You can also FprintXxx functions to pass your own io.Writer:

    blue := color.New(FgBlue).FprintfFunc()
    blue(myWriter, "important notice: %s", stars)
    
    // Mix up with multiple attributes
    success := color.New(color.Bold, color.FgGreen).FprintlnFunc()
    success(myWriter, don't forget this...")
    

    Or create SprintXxx functions to mix strings with other non-colorized strings:

    yellow := New(FgYellow).SprintFunc()
    red := New(FgRed).SprintFunc()
    
    fmt.Printf("this is a %s and this is %s.\n", yellow("warning"), red("error"))
    
    info := New(FgWhite, BgGreen).SprintFunc()
    fmt.Printf("this %s rocks!\n", info("package"))
    

    Windows support is enabled by default. All Print functions work as intended. However only for color.SprintXXX functions, user should use fmt.FprintXXX and set the output to color.Output:

    fmt.Fprintf(color.Output, "Windows support: %s", color.GreenString("PASS"))
    
    info := New(FgWhite, BgGreen).SprintFunc()
    fmt.Fprintf(color.Output, "this %s rocks!\n", info("package"))
    

    Using with existing code is possible. Just use the Set() method to set the standard output to the given parameters. That way a rewrite of an existing code is not required.

    // Use handy standard colors.
    color.Set(color.FgYellow)
    
    fmt.Println("Existing text will be now in Yellow")
    fmt.Printf("This one %s\n", "too")
    
    color.Unset() // don't forget to unset
    
    // You can mix up parameters
    color.Set(color.FgMagenta, color.Bold)
    defer color.Unset() // use it in your function
    
    fmt.Println("All text will be now bold magenta.")
    

    There might be a case where you want to disable color output (for example to pipe the standard output of your app to somewhere else). `Color` has support to disable colors both globally and for single color definition. For example suppose you have a CLI app and a `--no-color` bool flag. You can easily disable the color output with:

    var flagNoColor = flag.Bool("no-color", false, "Disable color output")
    
    if *flagNoColor {
    	color.NoColor = true // disables colorized output
    }
    

    It also has support for single color definitions (local). You can disable/enable color output on the fly:

    c := color.New(color.FgCyan)
    c.Println("Prints cyan text")
    
    c.DisableColor()
    c.Println("This is printed without any color")
    
    c.EnableColor()
    c.Println("This prints again cyan...")
    

    Index

    Constants

    This section is empty.

    Variables

    View Source
    var (
    	// NoColor defines if the output is colorized or not. It's dynamically set to
    	// false or true based on the stdout's file descriptor referring to a terminal
    	// or not. This is a global option and affects all colors. For more control
    	// over each color block use the methods DisableColor() individually.
    	NoColor = os.Getenv("TERM") == "dumb" ||
    		(!isatty.IsTerminal(os.Stdout.Fd()) && !isatty.IsCygwinTerminal(os.Stdout.Fd()))
    
    	// Output defines the standard output of the print functions. By default
    	// os.Stdout is used.
    	Output = colorable.NewColorableStdout()
    
    	// Error defines a color supporting writer for os.Stderr.
    	Error = colorable.NewColorableStderr()
    )

    Functions

    func Black

    func Black(format string, a ...interface{})

      Black is a convenient helper function to print with black foreground. A newline is appended to format by default.

      func BlackString

      func BlackString(format string, a ...interface{}) string

        BlackString is a convenient helper function to return a string with black foreground.

        func Blue

        func Blue(format string, a ...interface{})

          Blue is a convenient helper function to print with blue foreground. A newline is appended to format by default.

          func BlueString

          func BlueString(format string, a ...interface{}) string

            BlueString is a convenient helper function to return a string with blue foreground.

            func Cyan

            func Cyan(format string, a ...interface{})

              Cyan is a convenient helper function to print with cyan foreground. A newline is appended to format by default.

              func CyanString

              func CyanString(format string, a ...interface{}) string

                CyanString is a convenient helper function to return a string with cyan foreground.

                func Green

                func Green(format string, a ...interface{})

                  Green is a convenient helper function to print with green foreground. A newline is appended to format by default.

                  func GreenString

                  func GreenString(format string, a ...interface{}) string

                    GreenString is a convenient helper function to return a string with green foreground.

                    func HiBlack

                    func HiBlack(format string, a ...interface{})

                      HiBlack is a convenient helper function to print with hi-intensity black foreground. A newline is appended to format by default.

                      func HiBlackString

                      func HiBlackString(format string, a ...interface{}) string

                        HiBlackString is a convenient helper function to return a string with hi-intensity black foreground.

                        func HiBlue

                        func HiBlue(format string, a ...interface{})

                          HiBlue is a convenient helper function to print with hi-intensity blue foreground. A newline is appended to format by default.

                          func HiBlueString

                          func HiBlueString(format string, a ...interface{}) string

                            HiBlueString is a convenient helper function to return a string with hi-intensity blue foreground.

                            func HiCyan

                            func HiCyan(format string, a ...interface{})

                              HiCyan is a convenient helper function to print with hi-intensity cyan foreground. A newline is appended to format by default.

                              func HiCyanString

                              func HiCyanString(format string, a ...interface{}) string

                                HiCyanString is a convenient helper function to return a string with hi-intensity cyan foreground.

                                func HiGreen

                                func HiGreen(format string, a ...interface{})

                                  HiGreen is a convenient helper function to print with hi-intensity green foreground. A newline is appended to format by default.

                                  func HiGreenString

                                  func HiGreenString(format string, a ...interface{}) string

                                    HiGreenString is a convenient helper function to return a string with hi-intensity green foreground.

                                    func HiMagenta

                                    func HiMagenta(format string, a ...interface{})

                                      HiMagenta is a convenient helper function to print with hi-intensity magenta foreground. A newline is appended to format by default.

                                      func HiMagentaString

                                      func HiMagentaString(format string, a ...interface{}) string

                                        HiMagentaString is a convenient helper function to return a string with hi-intensity magenta foreground.

                                        func HiRed

                                        func HiRed(format string, a ...interface{})

                                          HiRed is a convenient helper function to print with hi-intensity red foreground. A newline is appended to format by default.

                                          func HiRedString

                                          func HiRedString(format string, a ...interface{}) string

                                            HiRedString is a convenient helper function to return a string with hi-intensity red foreground.

                                            func HiWhite

                                            func HiWhite(format string, a ...interface{})

                                              HiWhite is a convenient helper function to print with hi-intensity white foreground. A newline is appended to format by default.

                                              func HiWhiteString

                                              func HiWhiteString(format string, a ...interface{}) string

                                                HiWhiteString is a convenient helper function to return a string with hi-intensity white foreground.

                                                func HiYellow

                                                func HiYellow(format string, a ...interface{})

                                                  HiYellow is a convenient helper function to print with hi-intensity yellow foreground. A newline is appended to format by default.

                                                  func HiYellowString

                                                  func HiYellowString(format string, a ...interface{}) string

                                                    HiYellowString is a convenient helper function to return a string with hi-intensity yellow foreground.

                                                    func Magenta

                                                    func Magenta(format string, a ...interface{})

                                                      Magenta is a convenient helper function to print with magenta foreground. A newline is appended to format by default.

                                                      func MagentaString

                                                      func MagentaString(format string, a ...interface{}) string

                                                        MagentaString is a convenient helper function to return a string with magenta foreground.

                                                        func Red

                                                        func Red(format string, a ...interface{})

                                                          Red is a convenient helper function to print with red foreground. A newline is appended to format by default.

                                                          func RedString

                                                          func RedString(format string, a ...interface{}) string

                                                            RedString is a convenient helper function to return a string with red foreground.

                                                            func Unset

                                                            func Unset()

                                                              Unset resets all escape attributes and clears the output. Usually should be called after Set().

                                                              func White

                                                              func White(format string, a ...interface{})

                                                                White is a convenient helper function to print with white foreground. A newline is appended to format by default.

                                                                func WhiteString

                                                                func WhiteString(format string, a ...interface{}) string

                                                                  WhiteString is a convenient helper function to return a string with white foreground.

                                                                  func Yellow

                                                                  func Yellow(format string, a ...interface{})

                                                                    Yellow is a convenient helper function to print with yellow foreground. A newline is appended to format by default.

                                                                    func YellowString

                                                                    func YellowString(format string, a ...interface{}) string

                                                                      YellowString is a convenient helper function to return a string with yellow foreground.

                                                                      Types

                                                                      type Attribute

                                                                      type Attribute int

                                                                        Attribute defines a single SGR Code

                                                                        const (
                                                                        	Reset Attribute = iota
                                                                        	Bold
                                                                        	Faint
                                                                        	Italic
                                                                        	Underline
                                                                        	BlinkSlow
                                                                        	BlinkRapid
                                                                        	ReverseVideo
                                                                        	Concealed
                                                                        	CrossedOut
                                                                        )

                                                                          Base attributes

                                                                          const (
                                                                          	FgBlack Attribute = iota + 30
                                                                          	FgRed
                                                                          	FgGreen
                                                                          	FgYellow
                                                                          	FgBlue
                                                                          	FgMagenta
                                                                          	FgCyan
                                                                          	FgWhite
                                                                          )

                                                                            Foreground text colors

                                                                            const (
                                                                            	FgHiBlack Attribute = iota + 90
                                                                            	FgHiRed
                                                                            	FgHiGreen
                                                                            	FgHiYellow
                                                                            	FgHiBlue
                                                                            	FgHiMagenta
                                                                            	FgHiCyan
                                                                            	FgHiWhite
                                                                            )

                                                                              Foreground Hi-Intensity text colors

                                                                              const (
                                                                              	BgBlack Attribute = iota + 40
                                                                              	BgRed
                                                                              	BgGreen
                                                                              	BgYellow
                                                                              	BgBlue
                                                                              	BgMagenta
                                                                              	BgCyan
                                                                              	BgWhite
                                                                              )

                                                                                Background text colors

                                                                                const (
                                                                                	BgHiBlack Attribute = iota + 100
                                                                                	BgHiRed
                                                                                	BgHiGreen
                                                                                	BgHiYellow
                                                                                	BgHiBlue
                                                                                	BgHiMagenta
                                                                                	BgHiCyan
                                                                                	BgHiWhite
                                                                                )

                                                                                  Background Hi-Intensity text colors

                                                                                  type Color

                                                                                  type Color struct {
                                                                                  	// contains filtered or unexported fields
                                                                                  }

                                                                                    Color defines a custom color object which is defined by SGR parameters.

                                                                                    func New

                                                                                    func New(value ...Attribute) *Color

                                                                                      New returns a newly created color object.

                                                                                      func Set

                                                                                      func Set(p ...Attribute) *Color

                                                                                        Set sets the given parameters immediately. It will change the color of output with the given SGR parameters until color.Unset() is called.

                                                                                        func (*Color) Add

                                                                                        func (c *Color) Add(value ...Attribute) *Color

                                                                                          Add is used to chain SGR parameters. Use as many as parameters to combine and create custom color objects. Example: Add(color.FgRed, color.Underline).

                                                                                          func (*Color) DisableColor

                                                                                          func (c *Color) DisableColor()

                                                                                            DisableColor disables the color output. Useful to not change any existing code and still being able to output. Can be used for flags like "--no-color". To enable back use EnableColor() method.

                                                                                            func (*Color) EnableColor

                                                                                            func (c *Color) EnableColor()

                                                                                              EnableColor enables the color output. Use it in conjunction with DisableColor(). Otherwise this method has no side effects.

                                                                                              func (*Color) Equals

                                                                                              func (c *Color) Equals(c2 *Color) bool

                                                                                                Equals returns a boolean value indicating whether two colors are equal.

                                                                                                func (*Color) Fprint

                                                                                                func (c *Color) Fprint(w io.Writer, a ...interface{}) (n int, err error)

                                                                                                  Fprint formats using the default formats for its operands and writes to w. Spaces are added between operands when neither is a string. It returns the number of bytes written and any write error encountered. On Windows, users should wrap w with colorable.NewColorable() if w is of type *os.File.

                                                                                                  func (*Color) FprintFunc

                                                                                                  func (c *Color) FprintFunc() func(w io.Writer, a ...interface{})

                                                                                                    FprintFunc returns a new function that prints the passed arguments as colorized with color.Fprint().

                                                                                                    func (*Color) Fprintf

                                                                                                    func (c *Color) Fprintf(w io.Writer, format string, a ...interface{}) (n int, err error)

                                                                                                      Fprintf formats according to a format specifier and writes to w. It returns the number of bytes written and any write error encountered. On Windows, users should wrap w with colorable.NewColorable() if w is of type *os.File.

                                                                                                      func (*Color) FprintfFunc

                                                                                                      func (c *Color) FprintfFunc() func(w io.Writer, format string, a ...interface{})

                                                                                                        FprintfFunc returns a new function that prints the passed arguments as colorized with color.Fprintf().

                                                                                                        func (*Color) Fprintln

                                                                                                        func (c *Color) Fprintln(w io.Writer, a ...interface{}) (n int, err error)

                                                                                                          Fprintln formats using the default formats for its operands and writes to w. Spaces are always added between operands and a newline is appended. On Windows, users should wrap w with colorable.NewColorable() if w is of type *os.File.

                                                                                                          func (*Color) FprintlnFunc

                                                                                                          func (c *Color) FprintlnFunc() func(w io.Writer, a ...interface{})

                                                                                                            FprintlnFunc returns a new function that prints the passed arguments as colorized with color.Fprintln().

                                                                                                            func (*Color) Print

                                                                                                            func (c *Color) Print(a ...interface{}) (n int, err error)

                                                                                                              Print formats using the default formats for its operands and writes to standard output. Spaces are added between operands when neither is a string. It returns the number of bytes written and any write error encountered. This is the standard fmt.Print() method wrapped with the given color.

                                                                                                              func (*Color) PrintFunc

                                                                                                              func (c *Color) PrintFunc() func(a ...interface{})

                                                                                                                PrintFunc returns a new function that prints the passed arguments as colorized with color.Print().

                                                                                                                func (*Color) Printf

                                                                                                                func (c *Color) Printf(format string, a ...interface{}) (n int, err error)

                                                                                                                  Printf formats according to a format specifier and writes to standard output. It returns the number of bytes written and any write error encountered. This is the standard fmt.Printf() method wrapped with the given color.

                                                                                                                  func (*Color) PrintfFunc

                                                                                                                  func (c *Color) PrintfFunc() func(format string, a ...interface{})

                                                                                                                    PrintfFunc returns a new function that prints the passed arguments as colorized with color.Printf().

                                                                                                                    func (*Color) Println

                                                                                                                    func (c *Color) Println(a ...interface{}) (n int, err error)

                                                                                                                      Println formats using the default formats for its operands and writes to standard output. Spaces are always added between operands and a newline is appended. It returns the number of bytes written and any write error encountered. This is the standard fmt.Print() method wrapped with the given color.

                                                                                                                      func (*Color) PrintlnFunc

                                                                                                                      func (c *Color) PrintlnFunc() func(a ...interface{})

                                                                                                                        PrintlnFunc returns a new function that prints the passed arguments as colorized with color.Println().

                                                                                                                        func (*Color) Set

                                                                                                                        func (c *Color) Set() *Color

                                                                                                                          Set sets the SGR sequence.

                                                                                                                          func (*Color) Sprint

                                                                                                                          func (c *Color) Sprint(a ...interface{}) string

                                                                                                                            Sprint is just like Print, but returns a string instead of printing it.

                                                                                                                            func (*Color) SprintFunc

                                                                                                                            func (c *Color) SprintFunc() func(a ...interface{}) string

                                                                                                                              SprintFunc returns a new function that returns colorized strings for the given arguments with fmt.Sprint(). Useful to put into or mix into other string. Windows users should use this in conjunction with color.Output, example:

                                                                                                                              put := New(FgYellow).SprintFunc()
                                                                                                                              fmt.Fprintf(color.Output, "This is a %s", put("warning"))
                                                                                                                              

                                                                                                                              func (*Color) Sprintf

                                                                                                                              func (c *Color) Sprintf(format string, a ...interface{}) string

                                                                                                                                Sprintf is just like Printf, but returns a string instead of printing it.

                                                                                                                                func (*Color) SprintfFunc

                                                                                                                                func (c *Color) SprintfFunc() func(format string, a ...interface{}) string

                                                                                                                                  SprintfFunc returns a new function that returns colorized strings for the given arguments with fmt.Sprintf(). Useful to put into or mix into other string. Windows users should use this in conjunction with color.Output.

                                                                                                                                  func (*Color) Sprintln

                                                                                                                                  func (c *Color) Sprintln(a ...interface{}) string

                                                                                                                                    Sprintln is just like Println, but returns a string instead of printing it.

                                                                                                                                    func (*Color) SprintlnFunc

                                                                                                                                    func (c *Color) SprintlnFunc() func(a ...interface{}) string

                                                                                                                                      SprintlnFunc returns a new function that returns colorized strings for the given arguments with fmt.Sprintln(). Useful to put into or mix into other string. Windows users should use this in conjunction with color.Output.

                                                                                                                                      Source Files