style

Documentation

Overview

Package style provides support for styling terminal output.

See the documentation for the `Enabled` function to understand how styled output support is determined.

Index

• func Enabled() bool
• func ForceDisable()
• func ForceEnable()
• func ForceWrap(s string, c Code) string
• func Wrap(s string, c Code) string
• type Code
  • func Background256(v uint8) Code
  • func BackgroundRGB(r uint8, g uint8, b uint8) Code
  • func Foreground256(v uint8) Code
  • func ForegroundRGB(r uint8, g uint8, b uint8) Code
  • func Undercurl256(v uint8) Code
  • func UndercurlRGB(r uint8, g uint8, b uint8) Code
  • func (c Code) EscapeCodes() string
  • func (c Code) String() string

Functions

func Enabled

func Enabled() bool

Enabled returns whether styled output is enabled. This can be forced using the `ForceEnable` and `ForceDisable` functions, but will default to using the following heuristic:

* If the environment variable TERMSTYLE=0, then styled output is disabled.

* If TERMSTYLE=2, then styled output is enabled.

* Otherwise, styled output is only enabled if stdout is connected to a terminal.

This heuristic is run at startup using the stdout value at `os.Stdout`.

func ForceDisable

func ForceDisable()

ForceDisable forces styled output to be disabled.

func ForceEnable

func ForceEnable()

ForceEnable forces styled output to be enabled.

func ForceWrap

func ForceWrap(s string, c Code) string

ForceWrap encloses the given text with escape codes to stylize it and then resets the output back to normal. Unlike Wrap, this function doesn't pay any heed to whether styled output is enabled or not.

func Wrap

func Wrap(s string, c Code) string

Wrap encloses the given text with escape codes to stylize it and then resets the output back to normal. If styled output is not enabled, this function will return the given text without any changes.

Types

type Code

type Code uint64

Code represents colors and text effects for styling terminal output. You can OR multiple codes together with the following exceptions:

* If Reset is set, all other codes will be ignored.

* The Bold and Dim text effects cannot be OR-ed together. If they are, only Bold will be applied.

* The Undercurl and Underline text effects cannot be OR-ed together. If they are, only Undercurl will be applied.

* The Bright text effect only works with the base foreground and background colors.

* At most, only two colors can be OR-ed together: a foreground color and a background color, or a foreground color and an undercurl color. Any other color combination, e.g. a foreground with another foreground color, will result in undefined behavior.

const (
	Blink Code = 1 << iota
	Bold
	Bright
	Dim
	Invert
	Italic
	Reset
	Strikethrough
	Undercurl
	Underline
)

Codes for various text effects.

const (
	Black Code = (iota << 16) | (1 << 10)
	Red
	Green
	Yellow
	Blue
	Magenta
	Cyan
	White
)

Codes for the base foreground colors.

const (
	BlackBG Code = (iota << 40) | (1 << 12)
	RedBG
	GreenBG
	YellowBG
	BlueBG
	MagentaBG
	CyanBG
	WhiteBG
)

Codes for the base background colors.

func Background256

func Background256(v uint8) Code

Background256 returns the background color code representing the given 256 color value.

func BackgroundRGB

func BackgroundRGB(r uint8, g uint8, b uint8) Code

BackgroundRGB returns the background color code representing the given 24-bit color.

func Foreground256

func Foreground256(v uint8) Code

Foreground256 returns the foreground color code representing the given 256 color value.

func ForegroundRGB

func ForegroundRGB(r uint8, g uint8, b uint8) Code

ForegroundRGB returns the foreground color code representing the given 24-bit color.

func Undercurl256

func Undercurl256(v uint8) Code

Undercurl256 returns an undercurl color code representing the given 256 color value.

func UndercurlRGB

func UndercurlRGB(r uint8, g uint8, b uint8) Code

UndercurlRGB returns an undercurl color code representing the given 24-bit color.

func (Code) EscapeCodes

func (c Code) EscapeCodes() string

EscapeCodes returns the ANSI escape codes for the Code. This function doesn't pay any heed to whether styled output is enabled or not.

func (Code) String

func (c Code) String() string

String returns the ANSI escape codes for the Code. If styled output is not enabled, this function will return an empty string.