Skip to content

Commit 27f4ef0

Browse files
pd93pd93
committed
feat: initial commit
0 parents  commit 27f4ef0

File tree

8 files changed

+819
-0
lines changed

8 files changed

+819
-0
lines changed

‎LICENSE

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
The MIT License (MIT)
2+
3+
Copyright (c) 2024 Pete Davison
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
<p style="width:100%;text-align:center;font-size:40px;margin-bottom:30px;letter-spacing:5px;font-family:consolas;">
2+
<span style="color:#ad7fa8;">\x1b</span><span style="color:#729fcf;">[</span><span style="color:#8ae234;">1;43</span><span style="color:#ef2929;">m</span><span style="font-weight:bold;background-color:#fce94f;color:#555753;">ANSI</span><span style="color:#ad7fa8;">\x1b</span><span style="color:#729fcf;">[</span><span style="color:#8ae234;">0</span><span style="color:#ef2929;">m</span>
3+
</p>
4+
5+
<p style="width:100%;text-align:center;margin-bottom:30px;font-style:italic;">
6+
A simple, lightweight Golang package for working with ANSI escape codes.
7+
</p>
8+
9+
If you've ever worked on a CLI application before, you probably know the
10+
struggle of working with ANSI escape codes. Often, you just want to quickly
11+
apply a style to a string, but you either have to interrupt your workflow to
12+
look up the escape sequence and codes, or you have to import a large package
13+
that does more than you need.
14+
15+
The `ansi` package is extremely lightweight :feather: and has no external
16+
dependencies :package: It allows you to quickly apply styles to strings using
17+
**human-readable** style blocks. Because the styles are defined **inline**, there is no
18+
need to call a function for each style, making it easy to apply/reset multiple
19+
styles to a single string.
20+
21+
With `ansi`, the mess at the top of this page becomes: <span style="font-size:20px;letter-spacing:2px;font-family:consolas;">
22+
<span style="color:#ad7fa8;">[</span><span style="color:#8ae234;">bold:bg-yellow</span><span style="color:#ad7fa8;">]</span><span style="font-weight:bold;background-color:#fce94f;color:#555753;">ANSI</span><span style="color:#ad7fa8;">[</span><span style="color:#ef2929;">/</span><span style="color:#ad7fa8;">]</span>
23+
</span>
24+
25+
## Usage
26+
27+
Strings are formatted using "style blocks". A style block is delimited by square
28+
brackets (`[]`) and contains a list of styles separated by colons. For
29+
example, the style block `[red:bold]` applies the red and bold styles to any
30+
text following the block.
31+
32+
Styles can be reset by using the corresponding reset code or by using the global
33+
reset (`[/]`) to reset all styles.
34+
35+
```go
36+
import "github.com/pd93/ansi"
37+
38+
str := ansi.Parse("This is a [red:bold]red and bold[/] string")
39+
fmt.Println(str)
40+
41+
// Or use the provided fmt package function wrappers
42+
ansi.Println("This is a [red:bold]red and bold[/] string")
43+
```
44+
45+
If you need to print a literal string that conflicts with a valid style block,
46+
you can escape the block by prepending it with a backslash (`\`). For example,
47+
`\[red]` will print `[red]` instead of applying the red style.
48+
49+
```go
50+
// Note that we need to escape the escaping backslash otherwise it will be removed.
51+
ansi.Println("This is \\[red:bold]a normally formatted string because the style block is escaped\\[/]")
52+
53+
// We can avoid this in most situations by using a raw string (backticks) instead:
54+
ansi.Println(`This is \[red:bold]a normally formatted string because the style block is escaped\[/]`)
55+
```
56+
57+
For more info, check out the [style reference](#style-reference) below or take a look at our [examples](./examples/main.go).
58+
59+
## Style Reference
60+
61+
### Reset
62+
63+
| Code | ANSI Code | Description |
64+
| ---- | --------: | ----------------- |
65+
| `/` | `0` | Resets all styles |
66+
67+
### Formatting
68+
69+
| Code | ANSI Code | Example |
70+
| -------------- | --------: | ------------------------------------------------------------------------------------------------------------- |
71+
| `bold` | `1` | <span style="font-weight:bold;">Sets the font weight to bold</span> |
72+
| `faint`, `dim` | `2` | <span style="color:#d3d7cf;">Sets the text brightness to its faint/dim variant</span> \* |
73+
| `italic` | `3` | <span style="font-style:italic;">Sets the font style to italic</span> |
74+
| `underline` | `4` | <span style="text-decoration:underline;">Sets the text decoration to underline</span> |
75+
| `blink` | `5` | <span style="text-decoration:blink;">Sets the text to blink in and out</span> |
76+
| `invert` | `7` | <span style="backdrop-filter:invert(1);filter:invert(1);">Inverts the foreground and background colors</span> |
77+
| `hidden` | `8` | <span style="opacity:0;">Sets the text to be hidden</span> |
78+
| `strike` | `9` | <span style="text-decoration:line-through;">Sets the text decoration to line-through</span> |
79+
80+
> \* `faint` and `dim` do not work when using 8-bit (256) or 24-bit (RGB) color modes.
81+
82+
| Code | ANSI Code | Example |
83+
| ---------------- | --------: | --------------------------------------- |
84+
| `/bold` | `22` | Resets the font weight \*\* |
85+
| `/faint`, `/dim` | `22` | Resets the text brightness \*\* |
86+
| `/italic` | `23` | Resets the font style |
87+
| `/underline` | `24` | Resets the underline text decoration |
88+
| `/blink` | `25` | Stops the text from blinking |
89+
| `/invert` | `27` | Resets the text inversion |
90+
| `/hidden` | `28` | Resets the text visibility |
91+
| `/strike` | `29` | Resets the line-through text decoration |
92+
93+
> \*\* The `/bold`, `/faint`, and `/dim` codes all equal because they share an
94+
> ANSI code. This means it is not possible to reset them individually.
95+
96+
### Foreground Colors
97+
98+
| Code | ANSI Code | Reset Code |
99+
| --------- | -----------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
100+
| `black` | `30` | <span style="color:#555753;">Sets the text foreground to black</span> |
101+
| `red` | `31` | <span style="color:#ef2929;">Sets the text foreground to red</span> |
102+
| `green` | `32` | <span style="color:#8ae234;">Sets the text foreground to green</span> |
103+
| `yellow` | `33` | <span style="color:#fce94f;">Sets the text foreground to yellow</span> |
104+
| `blue` | `34` | <span style="color:#729fcf;">Sets the text foreground to blue</span> |
105+
| `magenta` | `35` | <span style="color:#ad7fa8;">Sets the text foreground to magenta</span> |
106+
| `cyan` | `36` | <span style="color:#34e2e2;">Sets the text foreground to cyan</span> |
107+
| `white` | `37` | <span style="color:#eeeeec;">Sets the text foreground to white</span> |
108+
| `R,G,B` | `38;2;R;G;B` | Sets the text foreground to the given [24-bit (<span style="color:#ef2929;">R</span><span style="color:#8ae234;">G</span><span style="color:#729fcf;">B</span>) color][24-bit] |
109+
| `N` | `38;5;N` | Sets the text foreground to the given [8-bit (256) color][8-bit] |
110+
| `/fg` | `39` | <span style="color:auto;">Resets the text foreground to the default color</span> |
111+
112+
### Background Colors
113+
114+
| Code | ANSI Code | Reset Code |
115+
| ------------ | -----------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
116+
| `bg-black` | `40` | <span style="background-color:#555753;">Sets the text background to black</span> |
117+
| `bg-red` | `41` | <span style="background-color:#ef2929;">Sets the text background to red</span> |
118+
| `bg-green` | `42` | <span style="background-color:#8ae234;color:#555753;">Sets the text background to green</span> |
119+
| `bg-yellow` | `43` | <span style="background-color:#fce94f;color:#555753;">Sets the text background to yellow</span> |
120+
| `bg-blue` | `44` | <span style="background-color:#729fcf;">Sets the text background to blue</span> |
121+
| `bg-magenta` | `45` | <span style="background-color:#ad7fa8;">Sets the text background to magenta</span> |
122+
| `bg-cyan` | `46` | <span style="background-color:#34e2e2;color:#555753;">Sets the text background to cyan</span> |
123+
| `bg-white` | `47` | <span style="background-color:#eeeeec;color:#555753;">Sets the text background to white</span> |
124+
| `bg-R,G,B` | `48;2;R;G;B` | Sets the text background to the given [24-bit (<span style="color:#ef2929;">R</span><span style="color:#8ae234;">G</span><span style="color:#729fcf;">B</span>) color][24-bit] |
125+
| `bg-N` | `48;5;N` | Sets the text background to the given [8-bit (256) color][8-bit] |
126+
| `/bg` | `49` | <span style="background-color:auto;">Resets the text background to the default color</span> |
127+
128+
[8-bit]: https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit
129+
[24-bit]: https://en.wikipedia.org/wiki/ANSI_escape_code#24-bit

0 commit comments

Comments
 (0)