color

package module
v0.0.0-...-1121d4e Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 9, 2016 License: Apache-2.0 Imports: 9 Imported by: 1

README

color GoDoc

DEPRECATED

Color extends fmt.Printf with verbs for producing colored output.

It has full terminfo support with github.com/nhooyr/terminfo!

note: things may change but it looks pretty stable. email me if you have any new ideas.

Install

go get github.com/nhooyr/color

Examples

See godoc for more information.

Setting Attributes
// "panic:" with a red foreground then normal "foo".
color.Printf("%h[fgRed]panic:%r %s\n", "foo")

// "panic:" with a red background then normal "bar".
color.Printf("%h[bgRed]panic:%r %s\n", "bar")

// Bold "panic:" then normal "foo".
color.Printf("%h[bold]panic:%r %s\n", "foo")

// Underlined "panic:" with then normal "bar".
color.Printf("%h[underline]panic:%r %s\n", "bar")

// "panic:" using color 83 as the foreground then normal "foo".
color.Printf("%h[fg83]panic:%r %s\n", "foo")

// "panic:" using color 158 as the background then normal "bar".
color.Printf("%h[bg158]panic:%r %s\n", "bar")
Mixing Attributes
// Bolded "panic:" with a green foreground then normal "foo".
color.Printf("%h[fgGreen+bold]panic:%r %s\n", "foo")

// Underlined "panic:" with a bright black background then normal "bar".
color.Printf("%h[bg8+underline]panic:%r %s\n", "bar")
Prepare
// Prepare only processes the highlight verbs in the string,
// letting you print it repeatedly with performance.
panicFormat := color.Prepare("%h[fgRed+bold]panic:%r %s\n")

// Each will print "panic:" and some normal text after, but if standard output
// is a terminal, "panic:" will be printed in bold with a red foreground.
color.Printfp(panicFormat, "foo")
color.Printfp(panicFormat, "bar")
color.Printfp(panicFormat, "foo")

hello := color.Prepare("%h[fgBlue+bold]HELLO%r")

// Each will print "HELLO", but if standard output is a terminal,
// "HELLO" will be printed in bold with a blue foreground.
color.Println(hello)
color.Println(hello)
color.Println(hello)
Printer

A Printer writes to an io.Writer.

redFormat := color.Prepare("%h[fgRed]%s%r\n")

// If standard error is a terminal, this will print in color.
// Otherwise it will print a normal "bar".
p := color.New(os.Stderr, color.IsTerminal(os.Stderr))
p.Printfp(redFormat, "bar")

// "foo" with red foreground.
p = color.New(os.Stderr, true)
p.Printfp(redFormat, "foo")

// Normal "bar", the highlight verbs are ignored.
p = color.New(os.Stderr, false)
p.Printfp(redFormat, "bar")
github.com/nhooyr/color/log
redFormat := color.Prepare("%h[fgRed]%s%r\n")

// If os.Stderr is a terminal, this will print in color.
// Otherwise it will be a normal "foo".
log.Printfp(redFormat, "foo")

// Normal "bar", the highlight verbs are ignored.
log.SetColor(false)
log.Printfp(redFormat, "bar")

// "foo" with a red foreground.
log.SetColor(true)
log.Fatalfp(redFormat, "foo")

Vim syntax highlighting

Add the following to after/syntax/go.vim to highlight the highlight verbs within strings.

syn match goFormatSpecifier /%[-#0 +]*\%(\*\|\d\+\)\=\%(\.\%(\*\|\d\+\)\)*\%([vTtbcdoqxXUeEfgGspr]\|h\[[a-zA-Z+0-9]\+\]\)/ contained containedin=goString

TODO

  • True color support
  • Windows support
  • Respect $TERM
  • Seperate log package
  • color.Format docs
  • A better way to combine color.Formats
  • Logging/Printing/Format tests
  • cleanup above tests

Documentation

Overview

Package color extends fmt.Printf with verbs for producing colored output.

Printing

Verbs: 

%h[attr...]	replaced with a SGR code that sets all of the attributes in []
		multiple attributes are + separated
%r		an abbreviation for %h[reset]

Preparing Strings:

While this package is heavily optimized, processing the highlighting verbs is still very expensive. Thus, it makes more sense to process the verbs once and then store the results into a Format structure. The format structure, holds two strings, one for when colored output is enabled and the other for when it is disabled.

Use the Prepare function to create Format structures. Then, use the Printfp like functions to use them as the base format strings, or send them as part of the variadic arguments to any Print function and they will be expanded to their appropriate strings. See Prepare below for an example.

Errors:

If an error occurs, the generated string will contain a description of the problem, as in these examples. 

Invalid character in the highlight verb:
	Printf("%h(fgRed)%s", "hi"):		%!h(INVALID)
No attributes in the highlight verb:
	Printf("%h[]%s", "hi"):			%!h(MISSING)
Unknown attribute in the highlight verb:
	Printf("%h[fgGdsds]%s", "hi"):		%!h(BADATTR)
String ended before the verb:
	Printf("%h[fg", "hi"):			%!h(SHORT)

Everything else is handled by the fmt package. You should read its documentation.

Attributes Reference

Named Colors: 

%h[xgBlack]
%h[xgRed]
%h[xgGreen]
%h[xgYellow]
%h[xgBlue]
%h[xgMagenta]
%h[xgCyan]
%h[xgWhite]
%h[xgBrightBlack]
%h[xgBrightRed]
%h[xgBrightGreen]
%h[xgBrightYellow]
%h[xgBrightBlue]
%h[xgBrightMagenta]
%h[xgBrightCyan]
%h[xgBrightWhite]

Where 'x' is either 'f' or 'b'.

256 Colors: 

%h[fgx]
%h[bgx]

Where x is any number from 0-255.

Modes: 

%h[reset] or the %r verb
%h[bold]
%h[underline]
%h[reverse]
%h[blink]
%h[dim]

See http://goo.gl/LRLA7o for information on the attributes. Scroll down to the SGR section.

See http://goo.gl/fvtHLs and ISO-8613-3 (according to above document) for more information on 256 colors.

Example (Attributes) 
package main

import (
	"github.com/nhooyr/color"
)

func main() {
	// "panic:" with a red foreground then normal "foo".
	color.Printf("%h[fgRed]panic:%r %s\n", "foo")

	// "panic:" with a red background then normal "bar".
	color.Printf("%h[bgRed]panic:%r %s\n", "bar")

	// Bold "panic:" then normal "foo".
	color.Printf("%h[bold]panic:%r %s\n", "foo")

	// Underlined "panic:" with then normal "bar".
	color.Printf("%h[underline]panic:%r %s\n", "bar")

	// "panic:" using color 83 as the foreground then normal "foo".
	color.Printf("%h[fg83]panic:%r %s\n", "foo")

	// "panic:" using color 158 as the background then normal "bar".
	color.Printf("%h[bg158]panic:%r %s\n", "bar")
}

Output:
Example (Mixing) 
package main

import (
	"github.com/nhooyr/color"
)

func main() {
	// Bolded "panic:" with a green foreground then normal "foo".
	color.Printf("%h[fgGreen+bold]panic:%r %s\n", "foo")

	// Underlined "panic:" with a bright black background then normal "bar".
	color.Printf("%h[bg8+underline]panic:%r %s\n", "bar")
}

Output:

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func ExpandFormats 

func ExpandFormats(color bool, a []interface{})

ExpandFormats replaces each Format in a with its appropriate string according to color.

func Highlight 

func Highlight(s string) string

Highlight replaces the highlight verbs in s with the appropriate control sequences and then returns the resulting string. It is a thin wrapper around Run.

func IsTerminal 

func IsTerminal(f *os.File) bool

IsTerminal returns true if f is a terminal and false otherwise.

func Print 

func Print(a ...interface{}) (n int, err error)

Print calls the standard output Printer's Print method.

func Printf 

func Printf(format string, a ...interface{}) (n int, err error)

Printf calls the standard output Printer's Printf method.

func Printfp 

func Printfp(f *Format, a ...interface{}) (n int, err error)

Printfp calls the standard output Printer's Printfp method.

func Println 

func Println(a ...interface{}) (n int, err error)

Println calls the standard output Printer's Println method.

func Run 

func Run(s string, color bool) string

Run runs a highlighter with s as the input and then returns the output. The color argument determines whether the highlight verbs will be replaced with their appropriate control sequences or instead stripped.

func Strip 

func Strip(s string) string

Strip removes all highlight verbs in s and then returns the resulting string. It is a thin wrapper around Run.

Types

type Format 

type Format struct {
	// contains filtered or unexported fields
}

Format represents a format string with the highlight verbs fully parsed. TODO interface

func Prepare 

func Prepare(f string) *Format

Prepare returns a Format structure using f as the base string.

Example 
package main

import (
	"github.com/nhooyr/color"
)

func main() {
	// Prepare only processes the highlight verbs in the string,
	// letting you print it repeatedly with performance.
	panicFormat := color.Prepare("%h[fgRed+bold]panic:%r %s\n")

	// Each will print "panic:" and some normal text after, but if standard output
	// is a terminal, "panic:" will be printed in bold with a red foreground.
	color.Printfp(panicFormat, "foo")
	color.Printfp(panicFormat, "bar")
	color.Printfp(panicFormat, "foo")

	hello := color.Prepare("%h[fgBlue+bold]HELLO%r")

	// Each will print "HELLO", but if standard output is a terminal,
	// "HELLO" will be printed in bold with a blue foreground.
	color.Println(hello)
	color.Println(hello)
	color.Println(hello)
}

Output:

func (*Format) Eprintfp 

func (f *Format) Eprintfp(a ...interface{}) *Format

Eprintfp calls fmt.Sprintf using f's strings and the rest of the arguments. It will expand each Format in a to its appropriate string before calling Sprintf. It then returns the resulting Format.

func (*Format) Get 

func (f *Format) Get(color bool) string

Get returns the colored string if color is true, and the stripped string otherwise.

type Printer 

type Printer struct {
	// contains filtered or unexported fields
}

Printer prints to a writer using highlight verbs.

Example 
package main

import (
	"os"

	"github.com/nhooyr/color"
)

func main() {
	redFormat := color.Prepare("%h[fgRed]%s%r\n")

	// If standard error is a terminal, this will print in color.
	// Otherwise it will print a normal "bar".
	p := color.New(os.Stderr, color.IsTerminal(os.Stderr))
	p.Printfp(redFormat, "bar")

	// "foo" with red foreground.
	p = color.New(os.Stderr, true)
	p.Printfp(redFormat, "foo")

	// Normal "bar", the highlight verbs are ignored.
	p = color.New(os.Stderr, false)
	p.Printfp(redFormat, "bar")
}

Output:

func New 

func New(out io.Writer, color bool) *Printer

New creates a new Printer that writes to out. The color argument dictates whether color output is enabled.

func (*Printer) Print 

func (p *Printer) Print(a ...interface{}) (n int, err error)

Print calls fmt.Fprint to print to the underlying writer. It will expand each Format in a to its appropriate string before calling fmt.Fprint.

func (*Printer) Printf 

func (p *Printer) Printf(format string, a ...interface{}) (n int, err error)

Printf first processes the highlight verbs in format and then calls fmt.Fprintf with the processed format and the other arguments. It will expand each Format in a to its appropriate string before calling fmt.Fprintf. It returns the number of bytes written an any write error encountered.

func (*Printer) Printfp 

func (p *Printer) Printfp(f *Format, a ...interface{}) (n int, err error)

Printfp is the same as p.Printf but takes a prepared format struct.

func (*Printer) Println 

func (p *Printer) Println(a ...interface{}) (n int, err error)

Println calls fmt.Fprintln to print to the underlying writer. It will expand each Format in a to its appropriate string before calling fmt.Fprintln.

Source Files

View all Source files

Directories

Path Synopsis
Package log implements a simple logging package with support for highlight verbs.
 Package log implements a simple logging package with support for highlight verbs.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.