README
¶
If you've ever worked on a CLI application before, you probably know the struggle of working with ANSI escape codes. Often, you just want to quickly apply a style to a string, but you either have to interrupt your workflow to look up the escape sequence and codes, or you have to import a large package that does more than you need.
The ansi package is extremely lightweight 🪶 and has no external
dependencies 📦 It allows you to quickly apply styles to strings using
human-readable style blocks. Because the styles are defined inline,
there is no need to call a function for each style, making it easy to
apply/reset multiple styles to a single string.
With ansi, the mess at the top of this page becomes: 
Usage
Strings are formatted using "style blocks". A style block is delimited by square
brackets ([]) and contains a list of styles separated by colons. For example,
the style block [red:bold] applies the red and bold styles to any text
following the block.
Styles can be reset by using the corresponding reset code or by using the global
reset ([/]) to reset all styles.
import "github.com/pd93/ansi"
str := ansi.Parse("This is a [red:bold]red and bold[/] string")
fmt.Println(str)
// Or use the provided fmt package function wrappers
ansi.Println("This is a [red:bold]red and bold[/] string")
If you need to print a literal string that conflicts with a valid style block,
you can escape the block by prepending it with a backslash (\). For example,
\[red] will print [red] instead of applying the red style.
// Note that we need to escape the escaping backslash otherwise it will be removed.
ansi.Println("This is \\[red:bold]an escaped style block\\[/]")
// We can avoid this in most situations by using a raw string (backticks) instead:
ansi.Println(`This is \[red:bold]an escaped style block\[/]`)
For more info, check out the style reference below or take a look at our examples.
Style Reference
Reset
| Code | ANSI Code | Description |
|---|---|---|
/ |
0 |
Resets all styles |
Formatting
| Code | ANSI Code | Description |
|---|---|---|
bold |
1 |
Sets the font weight to bold |
faint, dim |
2 |
Sets the text brightness to its faint/dim variant * |
italic |
3 |
Sets the font style to italic |
underline |
4 |
Sets the text decoration to underline |
blink |
5 |
Sets the text to blink in and out |
invert |
7 |
Inverts the foreground and background colors |
hidden |
8 |
Sets the text to be hidden |
strike |
9 |
Sets the text decoration to line-through |
*
faintanddimdo not work when using 8-bit (256) or 24-bit (RGB) color modes.
| Code | ANSI Code | Description |
|---|---|---|
/bold |
22 |
Resets the font weight ** |
/faint, /dim |
22 |
Resets the text brightness ** |
/italic |
23 |
Resets the font style |
/underline |
24 |
Resets the underline text decoration |
/blink |
25 |
Stops the text from blinking |
/invert |
27 |
Resets the text inversion |
/hidden |
28 |
Resets the text visibility |
/strike |
29 |
Resets the line-through text decoration |
** The
/bold,/faint, and/dimcodes all equal because they share an ANSI code. This means it is not possible to reset them individually.
Foreground Colors
| Code | ANSI Code | Description |
|---|---|---|
black |
30 |
Sets the text foreground to black |
red |
31 |
Sets the text foreground to red |
green |
32 |
Sets the text foreground to green |
yellow |
33 |
Sets the text foreground to yellow |
blue |
34 |
Sets the text foreground to blue |
magenta |
35 |
Sets the text foreground to magenta |
cyan |
36 |
Sets the text foreground to cyan |
white |
37 |
Sets the text foreground to white |
R,G,B |
38;2;R;G;B |
Sets the text foreground to the given 24-bit (RGB) color |
N |
38;5;N |
Sets the text foreground to the given 8-bit (256) color |
/fg |
39 |
Resets the text foreground to the default color |
Background Colors
| Code | ANSI Code | Description |
|---|---|---|
bg-black |
40 |
Sets the text background to black |
bg-red |
41 |
Sets the text background to red |
bg-green |
42 |
Sets the text background to green |
bg-yellow |
43 |
Sets the text background to yellow |
bg-blue |
44 |
Sets the text background to blue |
bg-magenta |
45 |
Sets the text background to magenta |
bg-cyan |
46 |
Sets the text background to cyan |
bg-white |
47 |
Sets the text background to white |
bg-R,G,B |
48;2;R;G;B |
Sets the text background to the given 24-bit (RGB) color |
bg-N |
48;5;N |
Sets the text background to the given 8-bit (256) color |
/bg |
49 |
Resets the text background to the default color |
Documentation
¶
Index ¶
- Constants
- func Fprint(w io.Writer, a ...any)
- func Fprintf(w io.Writer, format string, a ...any)
- func Fprintln(w io.Writer, a ...any)
- func Parse[T StringOrBytes](input T) T
- func Print(a ...any)
- func Printf(format string, a ...any)
- func Println(a ...any)
- func Strip[T StringOrBytes](input T) T
- type StringOrBytes
Constants ¶
const ( RESET = 0 BOLD = 1 FAINT = 2 ITALIC = 3 UNDERLINE = 4 BLINK = 5 INVERT = 7 HIDDEN = 8 STRIKE = 9 BOLD_FAINT_RESET = 22 ITALIC_RESET = 23 UNDER_RESET = 24 BLINK_RESET = 25 INVERT_RESET = 27 HIDDEN_RESET = 28 STRIKE_RESET = 29 FG_BLACK = 30 FG_RED = 31 FG_GREEN = 32 FG_YELLOW = 33 FG_BLUE = 34 FG_MAGENTA = 35 FG_CYAN = 36 FG_WHITE = 37 FG_CUSTOM = 38 FG_DEFAULT = 39 BG_BLACK = 40 BG_RED = 41 BG_GREEN = 42 BG_YELLOW = 43 BG_BLUE = 44 BG_MAGENTA = 45 BG_CYAN = 46 BG_WHITE = 47 BG_CUSTOM = 48 BG_DEFAULT = 49 )
ANSI escape codes
Variables ¶
This section is empty.
Functions ¶
func Fprint ¶
Fprint is a wrapper around fmt.Fprint. It will call the standard library's Sprint function with the given arguments and then pass the result to ansi.Parse. The result of this is then sent to the given writer.
func Fprintf ¶
Fprintf is a wrapper around fmt.Fprintf. It will call the standard library's Sprintf function with the given arguments and then pass the result to ansi.Parse. The result of this is then sent to the given writer.
func Fprintln ¶
Fprintln is a wrapper around fmt.Fprintln. It will call the standard library's Sprintln function with the given arguments and then pass the result to ansi.Parse. The result of this is then sent to the given writer.
func Parse ¶
func Parse[T StringOrBytes](input T) T
Parse will search the given input for codes given in the [code] format and replace them with the equivalent ANSI escape sequence. For example, if the input string is "[red]hello[/]" the output will be "\x1b[31mhello\x1b[0m". When output to a terminal this would print the string "hello" in red. See the list of constants in this package for available codes. Multiple codes can be specified at once by using the [code1:code2] syntax. If any code in the set is not recognized, the entire set is returned as-is. If you want the literal string [red], you can escape the parsing by using \[red].
func Print ¶
func Print(a ...any)
Print is a wrapper around fmt.Print. It will call the standard library's Sprint function with the given arguments and then pass the result to ansi.Parse. The result of this is then printed to stdout.
func Printf ¶
Printf is a wrapper around fmt.Printf. It will call the standard library's Sprintf function with the given arguments and then pass the result to ansi.Parse. The result of this is then printed to stdout.
func Println ¶
func Println(a ...any)
Println is a wrapper around fmt.Println. It will call the standard library's Sprintln function with the given arguments and then pass the result to ansi.Parse. The result of this is then printed to stdout.
func Strip ¶
func Strip[T StringOrBytes](input T) T
Strip will search the given input for codes given in the [code] format and delete them. For example, if the input string is "[red]hello[/]" the output will be "hello". See the list of constants in this package for available codes. Multiple codes can be specified at once by using the [code1:code2] syntax. If any code in the set is not recognized, the entire set is returned as-is. If you want the literal string [red], you can escape the parsing by using \[red].
Source Files
Directories