1<p align="center">
2    <img src="https://stuff.charm.sh/termenv.png" width="480" alt="termenv Logo">
3    <br />
4    <a href="https://github.com/muesli/termenv/releases"><img src="https://img.shields.io/github/release/muesli/termenv.svg" alt="Latest Release"></a>
5    <a href="https://godoc.org/github.com/muesli/termenv"><img src="https://godoc.org/github.com/golang/gddo?status.svg" alt="GoDoc"></a>
6    <a href="https://github.com/muesli/termenv/actions"><img src="https://github.com/muesli/termenv/workflows/build/badge.svg" alt="Build Status"></a>
7    <a href="https://coveralls.io/github/muesli/termenv?branch=master"><img src="https://coveralls.io/repos/github/muesli/termenv/badge.svg?branch=master" alt="Coverage Status"></a>
8    <a href="https://goreportcard.com/report/muesli/termenv"><img src="https://goreportcard.com/badge/muesli/termenv" alt="Go ReportCard"></a>
9</p>
10
11`termenv` lets you safely use advanced styling options on the terminal. It
12gathers information about the terminal environment in terms of its ANSI & color
13support and offers you convenient methods to colorize and style your output,
14without you having to deal with all kinds of weird ANSI escape sequences and
15color conversions.
16
17![Example output](https://github.com/muesli/termenv/raw/master/examples/hello-world/hello-world.png)
18
19## Features
20
21- RGB/TrueColor support
22- Detects the supported color range of your terminal
23- Automatically converts colors to the best matching, available colors
24- Terminal theme (light/dark) detection
25- Chainable syntax
26- Nested styles
27
28## Installation
29
30```bash
31go get github.com/muesli/termenv
32```
33
34## Query Terminal Support
35
36`termenv` can query the terminal it is running in, so you can safely use
37advanced features, like RGB colors. `ColorProfile` returns the color profile
38supported by the terminal:
39
40```go
41profile := termenv.ColorProfile()
42```
43
44This returns one of the supported color profiles:
45
46- `termenv.Ascii` - no ANSI support detected, ASCII only
47- `termenv.ANSI` - 16 color ANSI support
48- `termenv.ANSI256` - Extended 256 color ANSI support
49- `termenv.TrueColor` - RGB/TrueColor support
50
51You can also query the terminal for its color scheme, so you know whether your
52app is running in a light- or dark-themed environment:
53
54```go
55// Returns terminal's foreground color
56color := termenv.ForegroundColor()
57
58// Returns terminal's background color
59color := termenv.BackgroundColor()
60
61// Returns whether terminal uses a dark-ish background
62darkTheme := termenv.HasDarkBackground()
63```
64
65## Colors
66
67`termenv` supports multiple color profiles: ANSI (16 colors), ANSI Extended
68(256 colors), and TrueColor (24-bit RGB). Colors will automatically be degraded
69to the best matching available color in the desired profile:
70
71`TrueColor` => `ANSI 256 Colors` => `ANSI 16 Colors` => `Ascii`
72
73```go
74s := termenv.String("Hello World")
75
76// Retrieve color profile supported by terminal
77p := termenv.ColorProfile()
78
79// Supports hex values
80// Will automatically degrade colors on terminals not supporting RGB
81s.Foreground(p.Color("#abcdef"))
82// but also supports ANSI colors (0-255)
83s.Background(p.Color("69"))
84// ...or the color.Color interface
85s.Foreground(p.FromColor(color.RGBA{255, 128, 0, 255}))
86
87// Combine fore- & background colors
88s.Foreground(p.Color("#ffffff")).Background(p.Color("#0000ff"))
89
90// Supports the fmt.Stringer interface
91fmt.Println(s)
92```
93
94## Styles
95
96You can use a chainable syntax to compose your own styles:
97
98```go
99s := termenv.String("foobar")
100
101// Text styles
102s.Bold()
103s.Faint()
104s.Italic()
105s.CrossOut()
106s.Underline()
107s.Overline()
108
109// Reverse swaps current fore- & background colors
110s.Reverse()
111
112// Blinking text
113s.Blink()
114
115// Combine multiple options
116s.Bold().Underline()
117```
118
119## Template Helpers
120
121```go
122// load template helpers
123f := termenv.TemplateFuncs(termenv.ColorProfile())
124tpl := template.New("tpl").Funcs(f)
125
126// apply bold style in a template
127bold := `{{ Bold "Hello World" }}`
128
129// examples for colorized templates
130col := `{{ Color "#ff0000" "#0000ff" "Red on Blue" }}`
131fg := `{{ Foreground "#ff0000" "Red Foreground" }}`
132bg := `{{ Background "#0000ff" "Blue Background" }}`
133
134// wrap styles
135wrap := `{{ Bold (Underline "Hello World") }}`
136
137// parse and render
138tpl, err = tpl.Parse(bold)
139
140var buf bytes.Buffer
141tpl.Execute(&buf, nil)
142fmt.Println(&buf)
143```
144
145Other available helper functions are: `Faint`, `Italic`, `CrossOut`,
146`Underline`, `Overline`, `Reverse`, and `Blink`.
147
148## Screen
149
150```go
151// Reset the terminal to its default style, removing any active styles
152termenv.Reset()
153
154// Switch to the altscreen. The former view can be restored with ExitAltScreen()
155termenv.AltScreen()
156
157// Exit the altscreen and return to the former terminal view
158termenv.ExitAltScreen()
159
160// Clear the visible portion of the terminal
161termenv.ClearScreen()
162
163// Move the cursor to a given position
164termenv.MoveCursor(row, column)
165
166// Hide the cursor
167termenv.HideCursor()
168
169// Show the cursor
170termenv.ShowCursor()
171
172// Save the cursor position
173termenv.SaveCursorPosition()
174
175// Restore a saved cursor position
176termenv.RestoreCursorPosition()
177
178// Move the cursor up a given number of lines
179termenv.CursorUp(n)
180
181// Move the cursor down a given number of lines
182termenv.CursorDown(n)
183
184// Move the cursor up a given number of lines
185termenv.CursorForward(n)
186
187// Move the cursor backwards a given number of cells
188termenv.CursorBack(n)
189
190// Move the cursor down a given number of lines and place it at the beginning
191// of the line
192termenv.CursorNextLine(n)
193
194// Move the cursor up a given number of lines and place it at the beginning of
195// the line
196termenv.CursorPrevLine(n)
197
198// Clear the current line
199termenv.ClearLine()
200
201// Clear a given number of lines
202termenv.ClearLines(n)
203
204// Set the scrolling region of the terminal
205termenv.ChangeScrollingRegion(top, bottom)
206
207// Insert the given number of lines at the top of the scrollable region, pushing
208// lines below down
209termenv.InsertLines(n)
210
211// Delete the given number of lines, pulling any lines in the scrollable region
212// below up
213termenv.DeleteLines(n)
214```
215
216## Mouse
217
218```go
219// Enable X10 mouse mode, only button press events are sent
220termenv.EnableMousePress()
221
222// Disable X10 mouse mode
223termenv.DisableMousePress()
224
225// Enable Mouse Tracking mode
226termenv.EnableMouse()
227
228// Disable Mouse Tracking mode
229termenv.DisableMouse()
230
231// Enable Hilite Mouse Tracking mode
232termenv.EnableMouseHilite()
233
234// Disable Hilite Mouse Tracking mode
235termenv.DisableMouseHilite()
236
237// Enable Cell Motion Mouse Tracking mode
238termenv.EnableMouseCellMotion()
239
240// Disable Cell Motion Mouse Tracking mode
241termenv.DisableMouseCellMotion()
242
243// Enable All Motion Mouse mode
244termenv.EnableMouseAllMotion()
245
246// Disable All Motion Mouse mode
247termenv.DisableMouseAllMotion()
248```
249
250## Color Chart
251
252![ANSI color chart](https://github.com/muesli/termenv/raw/master/examples/color-chart/color-chart.png)
253
254You can find the source code used to create this chart in `termenv`'s examples.
255
256## Related Projects
257
258- [reflow](https://github.com/muesli/reflow) - ANSI-aware text operations
259- [Glow](https://github.com/charmbracelet/glow) - a markdown renderer for
260the command-line, which uses `termenv`
261
262## License
263
264[MIT](https://github.com/muesli/termenv/raw/master/LICENSE)
265