1Aurora
2======
3
4[](https://pkg.go.dev/github.com/logrusorgru/aurora/v3?tab=doc)
5[](http://unlicense.org/)
6[](https://travis-ci.org/logrusorgru/aurora)
7[](https://coveralls.io/r/logrusorgru/aurora?branch=master)
8[](https://goreportcard.com/report/logrusorgru/aurora)
9[](https://gitter.im/logrusorgru/aurora)
10
11Ultimate ANSI colors for Golang. The package supports Printf/Sprintf etc.
12
13
14
15
16# TOC
17
18- [Installation](#installation)
19- [Usage](#usage)
20 + [Simple](#simple)
21 + [Printf](#printf)
22 + [aurora.Sprintf](#aurorasprintf)
23 + [Enable/Disable colors](#enabledisable-colors)
24- [Chains](#chains)
25- [Colorize](#colorize)
26- [Grayscale](#grayscale)
27- [8-bit colors](#8-bit-colors)
28- [Supported Colors & Formats](#supported-colors--formats)
29 + [All colors](#all-colors)
30 + [Standard and bright colors](#standard-and-bright-colors)
31 + [Formats are likely supported](#formats-are-likely-supported)
32 + [Formats are likely unsupported](#formats-are-likely-unsupported)
33- [Limitations](#limitations)
34 + [Windows](#windows)
35 + [TTY](#tty)
36- [Licensing](#licensing)
37
38# Installation
39
40### Version 1.x
41
42Using gopkg.in.
43
44```
45go get -u gopkg.in/logrusorgru/aurora.v1
46```
47
48### Version 2.x
49
50```
51go get -u github.com/logrusorgru/aurora
52```
53
54### Go modules support, version v3+
55
56Get
57```
58go get -u github.com/logrusorgru/aurora/v3
59```
60
61The v3 was introduced to support `go.mod` and leave previous import paths as is.
62Currently, there is no changes between them (excluding the importpath's /v3 tail).
63
64# Test
65
66```
67go test -cover github.com/logrusorgru/aurora/v3
68```
69
70Replace the import path with your, if it's different.
71
72# Usage
73
74### Simple
75
76```go
77package main
78
79import (
80 "fmt"
81
82 . "github.com/logrusorgru/aurora"
83)
84
85func main() {
86 fmt.Println("Hello,", Magenta("Aurora"))
87 fmt.Println(Bold(Cyan("Cya!")))
88}
89
90```
91
92
93
94### Printf
95
96```go
97package main
98
99import (
100 "fmt"
101
102 . "github.com/logrusorgru/aurora"
103)
104
105func main() {
106 fmt.Printf("Got it %d times\n", Green(1240))
107 fmt.Printf("PI is %+1.2e\n", Cyan(3.14))
108}
109
110```
111
112
113
114### aurora.Sprintf
115
116```go
117package main
118
119import (
120 "fmt"
121
122 . "github.com/logrusorgru/aurora"
123)
124
125func main() {
126 fmt.Println(Sprintf(Magenta("Got it %d times"), Green(1240)))
127}
128
129```
130
131
132
133### Enable/Disable colors
134
135```go
136package main
137
138import (
139 "fmt"
140 "flag"
141
142 "github.com/logrusorgru/aurora"
143)
144
145// colorizer
146var au aurora.Aurora
147
148var colors = flag.Bool("colors", false, "enable or disable colors")
149
150func init() {
151 flag.Parse()
152 au = aurora.NewAurora(*colors)
153}
154
155func main() {
156 // use colorizer
157 fmt.Println(au.Green("Hello"))
158}
159
160```
161Without flags:
162
163
164With `-colors` flag:
165
166
167# Chains
168
169The following samples are equal
170
171```go
172x := BgMagenta(Bold(Red("x")))
173```
174
175```go
176x := Red("x").Bold().BgMagenta()
177```
178
179The second is more readable
180
181# Colorize
182
183There is `Colorize` function that allows to choose some colors and
184format from a side
185
186```go
187
188func getColors() Color {
189 // some stuff that returns appropriate colors and format
190}
191
192// [...]
193
194func main() {
195 fmt.Println(Colorize("Greeting", getColors()))
196}
197
198```
199Less complicated example
200
201```go
202x := Colorize("Greeting", GreenFg|GrayBg|BoldFm)
203```
204
205Unlike other color functions and methods (such as Red/BgBlue etc)
206a `Colorize` clears previous colors
207
208```go
209x := Red("x").Colorize(BgGreen) // will be with green background only
210```
211
212# Grayscale
213
214```go
215fmt.Println(" ",
216 Gray(1-1, " 00-23 ").BgGray(24-1),
217 Gray(4-1, " 03-19 ").BgGray(20-1),
218 Gray(8-1, " 07-15 ").BgGray(16-1),
219 Gray(12-1, " 11-11 ").BgGray(12-1),
220 Gray(16-1, " 15-07 ").BgGray(8-1),
221 Gray(20-1, " 19-03 ").BgGray(4-1),
222 Gray(24-1, " 23-00 ").BgGray(1-1),
223)
224```
225
226
227
228# 8-bit colors
229
230Methods `Index` and `BgIndex` implements 8-bit colors.
231
232| Index/BgIndex | Meaning | Foreground | Background |
233| -------------- | --------------- | ---------- | ---------- |
234| 0- 7 | standard colors | 30- 37 | 40- 47 |
235| 8- 15 | bright colors | 90- 97 | 100-107 |
236| 16-231 | 216 colors | 38;5;n | 48;5;n |
237| 232-255 | 24 grayscale | 38;5;n | 48;5;n |
238
239
240# Supported colors & formats
241
242- formats
243 + bold (1)
244 + faint (2)
245 + doubly-underline (21)
246 + fraktur (20)
247 + italic (3)
248 + underline (4)
249 + slow blink (5)
250 + rapid blink (6)
251 + reverse video (7)
252 + conceal (8)
253 + crossed out (9)
254 + framed (51)
255 + encircled (52)
256 + overlined (53)
257- background and foreground colors, including bright
258 + black
259 + red
260 + green
261 + yellow (brown)
262 + blue
263 + magenta
264 + cyan
265 + white
266 + 24 grayscale colors
267 + 216 8-bit colors
268
269### All colors
270
271
272
273
274### Standard and bright colors
275
276
277
278
279### Formats are likely supported
280
281
282
283### Formats are likely unsupported
284
285
286
287# Limitations
288
289There is no way to represent `%T` and `%p` with colors using
290a standard approach
291
292```go
293package main
294
295import (
296 "fmt"
297
298 . "github.com/logrusorgru/aurora"
299)
300
301func main() {
302 r := Red("red")
303 var i int
304 fmt.Printf("%T %p\n", r, Green(&i))
305}
306```
307
308Output will be without colors
309
310```
311aurora.value %!p(aurora.value={0xc42000a310 768 0})
312```
313
314The obvious workaround is `Red(fmt.Sprintf("%T", some))`
315
316### Windows
317
318The Aurora provides ANSI colors only, so there is no support for Windows. That said, there are workarounds available.
319Check out these comments to learn more:
320
321- [Using go-colorable](https://github.com/logrusorgru/aurora/issues/2#issuecomment-299014211).
322- [Using registry for Windows 10](https://github.com/logrusorgru/aurora/issues/10#issue-476361247).
323
324### TTY
325
326The Aurora has no internal TTY detectors by design. Take a look
327 [this comment](https://github.com/logrusorgru/aurora/issues/2#issuecomment-299030108) if you want turn
328on colors for a terminal only, and turn them off for a file.
329
330### Licensing
331
332Copyright © 2016-2020 The Aurora Authors. This work is free.
333It comes without any warranty, to the extent permitted by applicable
334law. You can redistribute it and/or modify it under the terms of the
335the Unlicense. See the LICENSE file for more details.
336
337
View as plain text