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 ..")
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.")
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...")
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 works 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 ¶
- Variables
- func Black(format string, a ...interface{})
- func BlackString(format string, a ...interface{}) string
- func Blue(format string, a ...interface{})
- func BlueString(format string, a ...interface{}) string
- func Cyan(format string, a ...interface{})
- func CyanString(format string, a ...interface{}) string
- func Green(format string, a ...interface{})
- func GreenString(format string, a ...interface{}) string
- func Magenta(format string, a ...interface{})
- func MagentaString(format string, a ...interface{}) string
- func Red(format string, a ...interface{})
- func RedString(format string, a ...interface{}) string
- func Unset()
- func White(format string, a ...interface{})
- func WhiteString(format string, a ...interface{}) string
- func Yellow(format string, a ...interface{})
- func YellowString(format string, a ...interface{}) string
- type Attribute
- type Color
- func (c *Color) Add(value ...Attribute) *Color
- func (c *Color) DisableColor()
- func (c *Color) EnableColor()
- func (c *Color) Equals(c2 *Color) bool
- func (c *Color) Print(a ...interface{}) (n int, err error)
- func (c *Color) PrintFunc() func(a ...interface{})
- func (c *Color) Printf(format string, a ...interface{}) (n int, err error)
- func (c *Color) PrintfFunc() func(format string, a ...interface{})
- func (c *Color) Println(a ...interface{}) (n int, err error)
- func (c *Color) PrintlnFunc() func(a ...interface{})
- func (c *Color) Set() *Color
- func (c *Color) SprintFunc() func(a ...interface{}) string
- func (c *Color) SprintfFunc() func(format string, a ...interface{}) string
- func (c *Color) SprintlnFunc() func(a ...interface{}) string
Constants ¶
This section is empty.
Variables ¶
var NoColor = !isatty.IsTerminal(os.Stdout.Fd())
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.
var Output = colorable.NewColorableStdout()
Output defines the standard output of the print functions. By default os.Stdout is used.
Functions ¶
func Black ¶
func Black(format string, a ...interface{})
Black is an convenient helper function to print with black foreground. A newline is appended to format by default.
func BlackString ¶
BlackString is an convenient helper function to return a string with black foreground.
func Blue ¶
func Blue(format string, a ...interface{})
Blue is an convenient helper function to print with blue foreground. A newline is appended to format by default.
func BlueString ¶
BlueString is an convenient helper function to return a string with blue foreground.
func Cyan ¶
func Cyan(format string, a ...interface{})
Cyan is an convenient helper function to print with cyan foreground. A newline is appended to format by default.
func CyanString ¶
CyanString is an convenient helper function to return a string with cyan foreground.
func Green ¶
func Green(format string, a ...interface{})
Green is an convenient helper function to print with green foreground. A newline is appended to format by default.
func GreenString ¶
GreenString is an convenient helper function to return a string with green foreground.
func Magenta ¶
func Magenta(format string, a ...interface{})
Magenta is an convenient helper function to print with magenta foreground. A newline is appended to format by default.
func MagentaString ¶
MagentaString is an convenient helper function to return a string with magenta foreground.
func Red ¶
func Red(format string, a ...interface{})
Red is an convenient helper function to print with red foreground. A newline is appended to format by default.
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 an convenient helper function to print with white foreground. A newline is appended to format by default.
func WhiteString ¶
WhiteString is an convenient helper function to return a string with white foreground.
func Yellow ¶
func Yellow(format string, a ...interface{})
Yellow is an convenient helper function to print with yellow foreground. A newline is appended to format by default.
func YellowString ¶
YellowString is an 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
Foreground text colors
const ( FgHiBlack Attribute = iota + 90 FgHiRed FgHiGreen FgHiYellow FgHiBlue FgHiMagenta FgHiCyan FgHiWhite )
Foreground Hi-Intensity text colors
Background 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 Set ¶
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 ¶
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 conjuction with DisableColor(). Otherwise this method has no side effects.
func (*Color) Print ¶
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 ¶
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 ¶
PrintfFunc returns a new function that prints the passed arguments as colorized with color.Printf().
func (*Color) Println ¶
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) SprintFunc ¶
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 conjuction with color.Output, example:
put := New(FgYellow).SprintFunc() fmt.Fprintf(color.Output, "This is a %s", put("warning"))
func (*Color) SprintfFunc ¶
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 conjuction with color.Output.
func (*Color) SprintlnFunc ¶
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 conjuction with color.Output.