vendor/github.com/fatih/color/doc.go

   1 /*
   2 Package color is an ANSI color package to output colorized or SGR defined
   3 output to the standard output. The API can be used in several way, pick one
   4 that suits you.
   5
   6 Use simple and default helper functions with predefined foreground colors:
   7
   8     color.Cyan("Prints text in cyan.")
   9
  10     // a newline will be appended automatically
  11     color.Blue("Prints %s in blue.", "text")
  12
  13     // More default foreground colors..
  14     color.Red("We have red")
  15     color.Yellow("Yellow color too!")
  16     color.Magenta("And many others ..")
  17
  18     // Hi-intensity colors
  19     color.HiGreen("Bright green color.")
  20     color.HiBlack("Bright black means gray..")
  21     color.HiWhite("Shiny white color!")
  22
  23 However there are times where custom color mixes are required. Below are some
  24 examples to create custom color objects and use the print functions of each
  25 separate color object.
  26
  27     // Create a new color object
  28     c := color.New(color.FgCyan).Add(color.Underline)
  29     c.Println("Prints cyan text with an underline.")
  30
  31     // Or just add them to New()
  32     d := color.New(color.FgCyan, color.Bold)
  33     d.Printf("This prints bold cyan %s\n", "too!.")
  34
  35
  36     // Mix up foreground and background colors, create new mixes!
  37     red := color.New(color.FgRed)
  38
  39     boldRed := red.Add(color.Bold)
  40     boldRed.Println("This will print text in bold red.")
  41
  42     whiteBackground := red.Add(color.BgWhite)
  43     whiteBackground.Println("Red text with White background.")
  44
  45     // Use your own io.Writer output
  46     color.New(color.FgBlue).Fprintln(myWriter, "blue color!")
  47
  48     blue := color.New(color.FgBlue)
  49     blue.Fprint(myWriter, "This will print text in blue.")
  50
  51 You can create PrintXxx functions to simplify even more:
  52
  53     // Create a custom print function for convenient
  54     red := color.New(color.FgRed).PrintfFunc()
  55     red("warning")
  56     red("error: %s", err)
  57
  58     // Mix up multiple attributes
  59     notice := color.New(color.Bold, color.FgGreen).PrintlnFunc()
  60     notice("don't forget this...")
  61
  62 You can also FprintXxx functions to pass your own io.Writer:
  63
  64     blue := color.New(FgBlue).FprintfFunc()
  65     blue(myWriter, "important notice: %s", stars)
  66
  67     // Mix up with multiple attributes
  68     success := color.New(color.Bold, color.FgGreen).FprintlnFunc()
  69     success(myWriter, don't forget this...")
  70
  71
  72 Or create SprintXxx functions to mix strings with other non-colorized strings:
  73
  74     yellow := New(FgYellow).SprintFunc()
  75     red := New(FgRed).SprintFunc()
  76
  77     fmt.Printf("this is a %s and this is %s.\n", yellow("warning"), red("error"))
  78
  79     info := New(FgWhite, BgGreen).SprintFunc()
  80     fmt.Printf("this %s rocks!\n", info("package"))
  81
  82 Windows support is enabled by default. All Print functions work as intended.
  83 However only for color.SprintXXX functions, user should use fmt.FprintXXX and
  84 set the output to color.Output:
  85
  86     fmt.Fprintf(color.Output, "Windows support: %s", color.GreenString("PASS"))
  87
  88     info := New(FgWhite, BgGreen).SprintFunc()
  89     fmt.Fprintf(color.Output, "this %s rocks!\n", info("package"))
  90
  91 Using with existing code is possible. Just use the Set() method to set the
  92 standard output to the given parameters. That way a rewrite of an existing
  93 code is not required.
  94
  95     // Use handy standard colors.
  96     color.Set(color.FgYellow)
  97
  98     fmt.Println("Existing text will be now in Yellow")
  99     fmt.Printf("This one %s\n", "too")
 100
 101     color.Unset() // don't forget to unset
 102
 103     // You can mix up parameters
 104     color.Set(color.FgMagenta, color.Bold)
 105     defer color.Unset() // use it in your function
 106
 107     fmt.Println("All text will be now bold magenta.")
 108
 109 There might be a case where you want to disable color output (for example to
 110 pipe the standard output of your app to somewhere else). `Color` has support to
 111 disable colors both globally and for single color definition. For example
 112 suppose you have a CLI app and a `--no-color` bool flag. You can easily disable
 113 the color output with:
 114
 115     var flagNoColor = flag.Bool("no-color", false, "Disable color output")
 116
 117     if *flagNoColor {
 118         color.NoColor = true // disables colorized output
 119     }
 120
 121 It also has support for single color definitions (local). You can
 122 disable/enable color output on the fly:
 123
 124      c := color.New(color.FgCyan)
 125      c.Println("Prints cyan text")
 126
 127      c.DisableColor()
 128      c.Println("This is printed without any color")
 129
 130      c.EnableColor()
 131      c.Println("This prints again cyan...")
 132 */
 133 package color