README
¶
Berry
A golang package for colorizing printed string on ANSI terminals.
This implement according to:
https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_parameters
https://en.wikipedia.org/wiki/X11_color_names#Color_name_chart
Aim
- Near zero abstraction cost.
- Test coverage 100%.
- Easy to use.
- Good document and examples.
Doc
https://godoc.org/github.com/tnclong/berry
Install
go get -u -v github.com/tnclong/berry
Usage
package main
import (
"fmt"
"github.com/tnclong/berry"
)
func main() {
fmt.Println(berry.Yellow.S("FgYellow"))
fmt.Println(berry.New(berry.BgYellow).S("BgYellow"))
berry.Red.Println("FgRed")
berry.New(berry.BgRed).Println("BgRed")
fmt.Println(berry.New(berry.Italic).S("Italic"))
fmt.Println(berry.New(berry.Underline).S("Underline"))
fmt.Println(berry.New(berry.FgSet, berry.Bit8, 88).S("Fg Bit8"))
fmt.Println(berry.New(berry.BgSet, berry.Bit8, 88).S("Bg Bit8"))
pFg := berry.New(berry.FgSet, berry.Bit24, 100, 100, 1)
pFg.Println("Fg Bit24")
pBg := berry.New(berry.BgSet, berry.Bit24, 100, 100, 1)
pBg.Println("Bg Bit24")
berry.Enable(false)
fmt.Println(berry.Yellow.S("FgYellow(enabled=false)"))
}
Test
go test -v -p=1 -count=1 .
Benchmark
$ go test -bench=. -benchmem -count=1
goos: darwin
goarch: amd64
pkg: github.com/tnclong/berry
BenchmarkS1-8 30000000 51.3 ns/op 16 B/op 1 allocs/op
BenchmarkS10-8 30000000 54.0 ns/op 32 B/op 1 allocs/op
BenchmarkS50-8 20000000 59.9 ns/op 64 B/op 1 allocs/op
BenchmarkS100-8 20000000 68.5 ns/op 112 B/op 1 allocs/op
BenchmarkSS100-8 3000000 433 ns/op 360 B/op 5 allocs/op
BenchmarkBestS100-8 20000000 60.8 ns/op 112 B/op 1 allocs/op
BenchmarkSprint100-8 5000000 249 ns/op 176 B/op 3 allocs/op
BenchmarkBestSprintUseBerry100-8 10000000 169 ns/op 128 B/op 2 allocs/op
BenchmarkBestSprint100-8 10000000 168 ns/op 128 B/op 2 allocs/op
BenchmarkSprintf100-8 10000000 200 ns/op 144 B/op 3 allocs/op
BenchmarkBestSprintfUseBerry100-8 10000000 169 ns/op 128 B/op 2 allocs/op
BenchmarkBestSprintf100-8 10000000 139 ns/op 128 B/op 2 allocs/op
BenchmarkS500-8 10000000 119 ns/op 512 B/op 1 allocs/op
BenchmarkS1000-8 10000000 190 ns/op 1024 B/op 1 allocs/op
BenchmarkSS1000-8 2000000 831 ns/op 3096 B/op 5 allocs/op
BenchmarkBestS1000-8 10000000 181 ns/op 1024 B/op 1 allocs/op
BenchmarkSprint1000-8 5000000 390 ns/op 1088 B/op 3 allocs/op
BenchmarkBestSprintUseBerry1000-8 5000000 314 ns/op 1040 B/op 2 allocs/op
BenchmarkBestSprint1000-8 5000000 311 ns/op 1040 B/op 2 allocs/op
BenchmarkSprintf1000-8 5000000 346 ns/op 1056 B/op 3 allocs/op
BenchmarkBestSprintfUseBerry1000-8 5000000 310 ns/op 1040 B/op 2 allocs/op
BenchmarkBestSprintf1000-8 5000000 277 ns/op 1040 B/op 2 allocs/op
BenchmarkS10000-8 1000000 1016 ns/op 10240 B/op 1 allocs/op
PASS
ok github.com/tnclong/berry 40.922s
Documentation
¶
Index ¶
- Constants
- Variables
- func Enable(e bool)
- type R
- func (r R) Fprint(w io.Writer, a ...interface{}) (n int, err error)
- func (r R) Fprintf(w io.Writer, format string, a ...interface{}) (n int, err error)
- func (r R) Fprintln(w io.Writer, a ...interface{}) (n int, err error)
- func (r R) Print(a ...interface{}) (n int, err error)
- func (r R) Printf(format string, a ...interface{}) (n int, err error)
- func (r R) Println(a ...interface{}) (n int, err error)
- func (r R) R() string
- func (r R) RI() interface{}
- func (r R) S(str string) string
- func (r R) SS(str string) string
- func (r R) Sprint(a ...interface{}) string
- func (r R) Sprintf(format string, a ...interface{}) string
- func (r R) Sprintln(a ...interface{}) string
Constants ¶
const ( // Reset terminal to default colors/backgrounds(attributes) // It shouldn't be needed to use this because all methods // append reset code to end of string. Reset uint8 = iota Bright Faint Italic Underline Blink Inverse Hide CrossOut )
A subset of SGR parameters that be used in New. https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_parameters
const ( FgBlack uint8 = iota + 30 FgRed FgGreen FgYellow FgBlue FgMagenta FgCyan FgWhite // 8-bit or 24-bit foreground color of text, see Bit8 and Bit24 FgSet )
3/4-bit foreground color of text that be used in New.
const ( BgBlack uint8 = iota + 40 BgRed BgGreen BgYellow BgBlue BgMagenta BgCyan BgWhite // 8-bit or 24-bit background color of text, see Bit8 and Bit24 BgSet )
3/4-bit background color of text that be used in New.
const ( // Bit8 is a flag that be used after FgSet and BgSet for specify a 8-bit color. // examples: // berry.New(berry.FgSet, berry.Bit8, 1).S("Red") => "\x1b[38;5;1mRed\x1b[0m" // berry.New(berry.BgSet, berry.Bit8, 11).S("Yellow") => "\x1b[48;5;11mYellow\x1b[0m" Bit8 uint8 = 5 // Bit24 is a flag that be used after FgSet and BgSet for specify a 24-bit color. // examples: // berry.New(berry.FgSet, berry.Bit24, 0, 0, 0).S("Black") => "\x1b[38;2;0;0;0mBlack\x1b[0m" // berry.New(berry.BgSet, berry.Bit24, 0, 0, 0).S("Black") => "\x1b[48;2;0;0;0mBlack\x1b[0m" Bit24 uint8 = 2 // Color256 is alias of Bit8 Color256 = Bit8 // RGB is alias of bit24 RGB = Bit24 // TrueColor is alias of bit24 TrueColor = Bit24 )
Variables ¶
var ( Black = New(FgBlack) Red = New(FgRed) Green = New(FgGreen) Yellow = New(FgYellow) Blue = New(FgBlue) Magenta = New(FgMagenta) Cyan = New(FgCyan) White = New(FgWhite) // It's convenient global variable when you need controll reset manually // for higher performance. RReset = New(Reset) )
convenient basic foreground colors, useful in many cases.
Functions ¶
Types ¶
type R ¶
type R struct {
// contains filtered or unexported fields
}
R is a sequence of SGR parameters and Colors.
When the length of R is 0, the S will clear all surrounding in str.
This implement reference to:
https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_parameters https://en.wikipedia.org/wiki/ANSI_escape_code#Colors
See exmaples in:
https://github.com/tnclong/berry#usage exmaples/*.go *_test.go
func New ¶
New create a new R
If r already matched `^(\x1b\[([\d;]+)m)`, original r will be returned.
examples:
r := berry.New(berry.FgSet, berry.Bit8, 1) => "\x1b[38;5;1m"
r.S("s") => "\x1b[38;5;1ms\x1b[0m"
func (R) R ¶
R return a sequence of SGR parameters that able to append to str directly.
berry.Red.R() + "red" + berry.RRset.R() => "\x1b[31mred\x1b[0m"
use this method when you need higher performance.
func (R) RI ¶
func (r R) RI() interface{}
RI is a interface{} that contains R() value. this method avoid a alloc op when use R as interface{} in golang.
example:
fmt.Sprint(berry.Blue.RI(), "1", 2, berry.RRset.RI())
aa := make([]interface{}, 2)
aa[0] = berry.Yellow.RI()
use this method when you need higher performance.
you can see more detail in https://github.com/golang/go/issues/32305#issuecomment-497051905
func (R) S ¶
S wraps str around a sequence of SGR parameters that store in r.
When the length of R is 0, the S will clear all surrounding in str.
func (R) SS ¶
SS is strict S method.
This method is about 4~6x slower than S in benchmark result.
If you have a str already arrounded with SGR:
Red.S("\x1b[3mItalic then BgRed\x1b[0m")
=> "\x1b[41m\x1b[3mItalic then BgRed\x1b[0m\x1b[0m"
Red.SS("\x1b[3mItalic then BgRed\x1b[0m")
=> "\x1b[3m\x1b[41mItalic then BgRed\x1b[0m"
Source Files
Directories