README
¶
termenv
termenv lets you safely use advanced styling options on the terminal. It
gathers information about the terminal environment in terms of its ANSI & color
support and offers you convenient methods to colorize and style your output,
without you having to deal with all kinds of weird ANSI escape sequences and
color conversions.
Installation
go get github.com/muesli/termenv
Query Terminal Status
// returns supported color profile: Ascii, ANSI, ANSI256, or TrueColor
termenv.ColorProfile()
// returns default foreground color
termenv.ForegroundColor()
// returns default background color
termenv.BackgroundColor()
// returns whether terminal uses a dark-ish background
termenv.HasDarkBackground()
Colors
termenv supports multiple color profiles: ANSI (16 colors), ANSI Extended
(256 colors), and TrueColor (24-bit RGB). Colors will automatically be degraded
to the best matching available color in the desired profile:
TrueColor => ANSI 256 Colors => ANSI 16 Colors => Ascii
out := termenv.String("Hello World")
// retrieve color profile supported by terminal
p := termenv.ColorProfile()
// supports hex values
// will automatically degrade colors on terminals not supporting RGB
out = out.Foreground(p.Color("#abcdef"))
// but also supports ANSI colors (0-255)
out = out.Background(p.Color("69"))
fmt.Println(out)
Styles
out := termenv.String("foobar")
// text styles
out.Bold()
out.Faint()
out.Italic()
out.CrossOut()
out.Underline()
out.Overline()
// reverse swaps current fore- & background colors
out.Reverse()
// blinking text
out.Blink()
// combine multiple options
out.Bold().Underline()
Template Helpers
// load template helpers
f := termenv.TemplateFuncs(termenv.ColorProfile())
tpl := template.New("tpl").Funcs(f)
// apply bold style in a template
bold := `{{ Bold "Hello World" }}`
// examples for colorized templates
col := `{{ Color "#ff0000" "#0000ff" "Red on Blue" }}`
fg := `{{ Foreground "#ff0000" "Red Foreground" }}`
bg := `{{ Background "#0000ff" "Blue Background" }}`
// wrap styles
wrap := `{{ Bold (Underline "Hello World") }}`
// parse and render
tpl = tpl.Parse(bold)
var buf bytes.Buffer
tpl.Execute(&buf, nil)
fmt.Println(buf)
Other available helper functions are: Faint, Italic, CrossOut,
Underline, Overline, Reverse, and Blink.
Color Chart
You can find the source code used to create this chart in termenv's examples.
Related Projects
Check out Glow, a markdown renderer for
the command-line, which uses termenv.
License
Documentation
¶
Index ¶
- Constants
- Variables
- func AltScreen()
- func ClearLine()
- func ClearLines(n int)
- func ClearScreen()
- func ConvertToRGB(c Color) colorful.Color
- func CursorNextLine(n int)
- func CursorPrevLine(n int)
- func ExitAltScreen()
- func HasDarkBackground() bool
- func HideCursor()
- func MoveCursor(row int, column int)
- func ShowCursor()
- func TemplateFuncs(p Profile) template.FuncMap
- type ANSI256Color
- type ANSIColor
- type Color
- type NoColor
- type Profile
- type RGBColor
- type Style
- func (t Style) Background(c Color) Style
- func (t Style) Blink() Style
- func (t Style) Bold() Style
- func (t Style) CrossOut() Style
- func (t Style) Faint() Style
- func (t Style) Foreground(c Color) Style
- func (t Style) Italic() Style
- func (t Style) Overline() Style
- func (t Style) Reverse() Style
- func (t Style) String() string
- func (t Style) Styled(s string) string
- func (t Style) Underline() Style
Constants ¶
const ( Foreground = "38" Background = "48" )
const ( AltScreenSeq = "?1049h" ExitAltScreenSeq = "?1049l" CursorUpSeq = "%dA" CursorDownSeq = "%dB" CursorForwardSeq = "%dC" CursorBackSeq = "%dD" CursorNextLineSeq = "%dE" CursorPreviousLineSeq = "%dF" CursorHorizontalSeq = "%dG" CursorPositionSeq = "%d;%dH" EraseDisplaySeq = "%dJ" EraseLineSeq = "%dK" ScrollUpSeq = "%dS" ScrollDownSeq = "%dT" ShowCursorSeq = "?25h" HideCursorSeq = "?25l" )
const ( ResetSeq = "0" BoldSeq = "1" FaintSeq = "2" ItalicSeq = "3" UnderlineSeq = "4" BlinkSeq = "5" ReverseSeq = "7" CrossOutSeq = "9" OverlineSeq = "53" )
const ( CSI = "\x1b[" Ascii = Profile(iota) ANSI ANSI256 TrueColor )
Variables ¶
var (
ErrInvalidColor = errors.New("invalid color")
)
var (
ErrStatusReport = errors.New("unable to retrieve status report")
)
var ForceColor bool = false
ForceColor overwrites the tty check, e.g. useful when generating shell prompts.
Functions ¶
func AltScreen ¶
func AltScreen()
AltScreen switches to the altscreen. The former view can be restored with ExitAltScreen().
func ConvertToRGB ¶
func ConvertToRGB(c Color) colorful.Color
func CursorNextLine ¶
func CursorNextLine(n int)
CursorNextLine moves the cursor down a given number of lines and places it at the beginning of the line.
func CursorPrevLine ¶
func CursorPrevLine(n int)
CursorPrevLine moves the cursor up a given number of lines and places it at the beginning of the line.
func ExitAltScreen ¶
func ExitAltScreen()
ExitAltScreen exits the altscreen and returns to the former terminal view.
func HasDarkBackground ¶
func HasDarkBackground() bool
HasDarkBackground returns whether terminal uses a dark-ish background
func MoveCursor ¶
MoveCursor moves the cursor to a given position.
func TemplateFuncs ¶
TemplateFuncs contains a few useful template helpers
Types ¶
type ANSI256Color ¶
type ANSI256Color int
ANSI256Color is a color (16-255) as defined by the ANSI Standard
func (ANSI256Color) Sequence ¶
func (c ANSI256Color) Sequence(bg bool) string
type Color ¶
func BackgroundColor ¶
func BackgroundColor() Color
BackgroundColor returns the terminal's default background color
func ForegroundColor ¶
func ForegroundColor() Color
ForegroundColor returns the terminal's default foreground color
type Profile ¶
type Profile int
func ColorProfile ¶
func ColorProfile() Profile
ColorProfile returns the supported color profile: Ascii, ANSI, ANSI256, or TrueColor
type Style ¶
type Style struct {
// contains filtered or unexported fields
}
Style is a string that various rendering styles can be applied to.
func (Style) Background ¶
Background sets a background color
func (Style) Foreground ¶
Foreground sets a foreground color
Source Files
Directories