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