{"id":13670152,"url":"https://github.com/jwalton/gchalk","last_synced_at":"2025-05-16T13:07:45.695Z","repository":{"id":53565621,"uuid":"343923436","full_name":"jwalton/gchalk","owner":"jwalton","description":"Terminal string styling for go done right, with full and painless Windows 10 support.","archived":false,"fork":false,"pushed_at":"2022-03-22T17:39:59.000Z","size":339,"stargazers_count":339,"open_issues_count":0,"forks_count":7,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-12T10:57:54.227Z","etag":null,"topics":["ansi","chalk","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jwalton.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-02T21:56:11.000Z","updated_at":"2025-03-27T21:29:29.000Z","dependencies_parsed_at":"2022-09-18T10:30:34.954Z","dependency_job_id":null,"html_url":"https://github.com/jwalton/gchalk","commit_stats":null,"previous_names":["jwalton/gawk"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwalton%2Fgchalk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwalton%2Fgchalk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwalton%2Fgchalk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwalton%2Fgchalk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jwalton","download_url":"https://codeload.github.com/jwalton/gchalk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254535829,"owners_count":22087399,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansi","chalk","golang"],"created_at":"2024-08-02T09:00:34.038Z","updated_at":"2025-05-16T13:07:45.676Z","avatar_url":"https://github.com/jwalton.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# GChalk\n\n[![PkgGoDev](https://pkg.go.dev/badge/github.com/jwalton/gchalk)](https://pkg.go.dev/github.com/jwalton/gchalk?readme=expanded#section-readme)\n[![Build Status](https://github.com/jwalton/gchalk/workflows/Build/badge.svg)](https://github.com/jwalton/gchalk/actions)\n[![Go Report Card](https://goreportcard.com/badge/github.com/jwalton/gchalk)](https://goreportcard.com/report/github.com/jwalton/gchalk)\n[![Release](https://img.shields.io/github/release/jwalton/gchalk.svg?style=flat-square)](https://github.com/jwalton/gchalk/releases/latest)\n\nGChalk is a library heavily inspired by [chalk](https://github.com/chalk/chalk), the popular Node.js terminal color library, and using go ports of [supports-color](https://github.com/jwalton/go-supportscolor) and [ansi-styles](https://github.com/jwalton/gchalk/tree/master/pkg/ansistyles).\n\n\u003cimg src=\"screenshot.png\" width=\"900\"\u003e\n\n## Features\n\n- Expressive API\n- Highly performant\n- Ability to nest styles\n- [256/Truecolor color support](https://github.com/jwalton/gchalk#256-and-truecolor-color-support) with automatic conversion if not supported\n- [Auto-detects color support](https://github.com/jwalton/gchalk#color-detection)\n- Painless [Windows 10 support](https://github.com/jwalton/gchalk#windows-10-support)\n\n## Feature Comparison\n\n|                                  Feature                                  | gchalk | [termenv](https://github.com/muesli/termenv) | [aurora](https://github.com/logrusorgru/aurora) | [fatih/color](https://github.com/fatih/color) | [mgutz/ansi](https://github.com/mgutz/ansi) |\n| :-----------------------------------------------------------------------: | :----: | :------------------------------------------: | :---------------------------------------------: | :-------------------------------------------: | :-----------------------------------------: |\n|                               TTY Detection                               |   ✅   |                    ✅ (1)                    |                       ❌                        |                    ✅ (1)                     |                     ❌                      |\n|                              Color Detection                              |   ✅   |                      ✅                      |                       ❌                        |                      ❌                       |                     ❌                      |\n|                                Windows 10                                 |   ✅   |                    ✅ (5)                    |                       ❌                        |                    ✅ (2)                     |                     ❌                      |\n|                               Nested Styles                               |   ✅   |                    ? (6)                     |                     ✅ (3)                      |                      ❌                       |                     ❌                      |\n|                             256 Color Support                             |   ✅   |                      ✅                      |                     ✅ (4)                      |                      ❌                       |                   ✅ (4)                    |\n|                            16.7m Color Support                            |   ✅   |                      ✅                      |                       ❌                        |                      ❌                       |                     ❌                      |\n| [Speed](https://gist.github.com/jwalton/2394e848be3070c6667220baa70cdeda) |  70ns  |                    330ns                     |                      196ns                      |                     420ns                     |                    40ns                     |\n\n1. fatih/color and termenv support automatic TTY detection, but assume that if stdout is not a TTY, then stderr is also not a TTY, which may not be true.\n2. fatih/color supports Windows 10, but you need to write to a special stream.\n3. aurora supports nested styles via its custom `Sprintf()`, but you can't convert things to a string first - need to keep everything as aurora `Value`s.\n4. aurora and mgutz/ansi both support 256 color output, but they don't detect whether the terminal supports it or not, and won't automatically convert 256 color output to 16 color output if it doesn't.\n5. termenv assumes Windows always supports 16.7m colors, which might cause problems on really old Windows 10 builds. termenv also does not enable ANSI support on Windows 10, so users not using Windows Terminal may have to take extra steps to enable ANSI support (although this is done for you if you are using the related library [LipGloss](https://github.com/charmbracelet/lipgloss/blob/master/ansi_windows.go)).\n6. termenv claims to support nested styles, but I couldn't figure out how to make them work.\n\n## Install\n\n```sh\ngo get github.com/jwalton/gchalk\n```\n\n## Usage\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"github.com/jwalton/gchalk\"\n)\n\nfunc main() {\n    fmt.Println(gchalk.Blue(\"This line is blue\"))\n}\n```\n\nNote that this works on all platforms - there's no need to write to a special stream or use a special print function to get color on Windows 10.\n\nGChalk uses a chainable syntax for composing styles together, which should be instantly familiar if you've ever used chalk or similar libraries. To style a string blue, for example, you\"d call `gchalk.Blue(\"hello\")`. To style it blue with a red background, you can use `gchalk.WithBgRed().Blue(\"hello\")`.\n\n```go\n// Combine styled and normal strings\nfmt.Println(gchalk.Blue(\"Hello\") + \" World\" + gchalk.Red(\"!\"))\n\n// Compose multiple styles using the chainable API\nfmt.Println(gchalk.WithBlue().WithBgRed().Bold(\"Hello world!\"))\n\n// Pass in multiple arguments\nfmt.Println(gchalk.Blue(\"Hello\", \"World!\", \"Foo\", \"bar\", \"biz\", \"baz\"))\n\n// Nest styles\nfmt.Println(gchalk.Green(\n    \"I am a green line \" +\n    gchalk.WithBlue().WithUnderline().Bold(\"with a blue substring\") +\n    \" that becomes green again!\"\n))\n\n// Use RGB colors in terminal emulators that support it.\nfmt.Println(gchalk.WithRGB(123, 45, 67).Underline(\"Underlined reddish color\"))\nfmt.Println(gchalk.WithHex(\"#DEADED\").Bold(\"Bold gray!\"))\n\n// Use color name strings\nfmt.Println(gchalk.StyleMust(\"blue\")(\"Hello World!\"))\n\n\n// Write to stderr:\nos.Stderr.WriteString(gchalk.Stderr.Red(\"Ohs noes!\\n\"))\n```\n\nYou can easily define your own themes:\n\n```go\nvar error = gchalk.WithBold().Red\nvar warning = gchalk.Yellow\n\nfmt.Println(error(\"Error!\"))\nfmt.Println(warning(\"Warning!\"))\n```\n\n## API\n\n### gchalk[.With\u0026lt;style\u003e][.with\u0026lt;style\u003e...].\u0026lt;style\u003e(string [, string...])\n\nExample:\n\n```go\nfmt.Println(gchalk.WithRed().WithBold().Underline(\"Hello\", \"world\"))\n```\n\nChain styles and call the last one as a method with a string argument. Order doesn't matter, and later styles take precedent in case of a conflict. Multiple arguments will be separated by a space.\n\nYou can also obtain a `Builder` instance and then use the `Paint()` function, similar to Rust's `ansi_term` crate, or use the `Sprintf()` convenience function:\n\n```go\nfmt.Println(gchalk.WithRed().Paint(\"Hello\", \"world\"))\nfmt.Println(gchalk.WithRed().Sprintf(\"Hello %v\", \"world\"))\n```\n\n### gchalk.Style(style [, style...])(string [, string...])\n\nExample:\n\n```go\nstyler, err := gchalk.Style(\"bold\", \"red\")\nif err == nil {\n    fmt.Println(styler(\"This is bold and red\"))\n}\n\nfmt.Println(gchalk.StyleMust(\"bold\", \"red\")(\"This is also bold and red.\"))\n```\n\n`Style` and `StyleMust` allow styling a string based on the case-insensitive names of colors and modifiers. There's also a `WithStyle` and `WithStyleMust` for chaining named styles with other styles.  These funcions can also accept hex codes or `bg#000000` hex codes for background colors.\n\n### gchalk.SetLevel(level) and gchalk.GetLevel()\n\nSpecifies the level of color support. See [the section on color detection](https://github.com/jwalton/gchalk#color-detection) for details about how gchalk auto-detects color support. You can override the detected level by calling `SetLevel()`. You should however only do this in your own application, as it applies globally to all gchalk consumers. If you need to change this in a library, create a new instance:\n\n```go\nvar myGChalk = gchalk.New(gchalk.ForceLevel(gchalk.LevelNone))\n```\n\n|       Level        | Description                           |\n| :----------------: | :------------------------------------ |\n|  `LevelNone = 0`   | All colors disabled                   |\n|  `LevelBasic = 1`  | Basic color support (16 colors)       |\n| `LevelAnsi256 = 2` | 256 color support                     |\n| `LevelAnsi16m = 3` | Truecolor support (16 million colors) |\n\n### gchalk.Stderr\n\n`gchalk.Stderr` contains a separate instance configured with color support detected for `stderr` stream instead of `stdout`.\n\nStdout and stderr can be different in cases where the user is piping output. For example, if a user runs:\n\n```sh\nmyprogram \u003e out.txt\n```\n\nthen `stdout` will not be a TTY, so by default gchalk will not emit any color, however `stderr` will be a TTY, so `gchalk.Stderr.Red(...)` will still generate colored output.\n\n### gchalk.New(options...)\n\nCreates a new instance of gchalk. Options include:\n\n- `gchalk.ForceLevel(level)` - Force the color level. If not specified, will be autodetected from stdout.\n\n## Styles\n\n### Modifiers\n\n- `Reset` - Resets the current color chain.\n- `Bold` - Make text bold.\n- `Dim` - Emitting only a small amount of light.\n- `Italic` - Make text italic. _(Not widely supported)_\n- `Underline` - Make text underline. _(Not widely supported)_\n- `Inverse`- Inverse background and foreground colors.\n- `Hidden` - Prints the text, but makes it invisible.\n- `Strikethrough` - Puts a horizontal line through the center of the text. _(Not widely supported)_\n- `Visible`- Prints the text only when gchalk has a color level \u003e 0. Can be useful for things that are purely cosmetic.\n\n### Colors\n\n- `Black`\n- `Red`\n- `Green`\n- `Yellow`\n- `Blue`\n- `Magenta`\n- `Cyan`\n- `White`\n- `BrightBlack` (alias: `gray`, `grey`)\n- `BrightRed`\n- `BrightGreen`\n- `BrightYellow`\n- `BrightBlue`\n- `BrightMagenta`\n- `BrightCyan`\n- `BrightWhite`\n\n### Background colors\n\n- `BgBlack`\n- `BgRed`\n- `BgGreen`\n- `BgYellow`\n- `BgBlue`\n- `BgMagenta`\n- `BgCyan`\n- `BgWhite`\n- `BgBrightBlack` (alias: `BgGray`, `BgGrey`)\n- `BgBrightRed`\n- `BgBrightGreen`\n- `BgBrightYellow`\n- `BgBrightBlue`\n- `BgBrightMagenta`\n- `BgBrightCyan`\n- `BgBrightWhite`\n\n## 256 and Truecolor color support\n\nGChalk supports 256 colors and [Truecolor](https://gist.github.com/XVilka/8346728) (16 million colors) on supported terminal apps, including Windows 10.\n\nColors are downsampled from 16 million RGB values to an ANSI color format that is supported by the terminal emulator (or by specifying `{level: n}` as a Chalk option). For example, GChalk configured to run at level 1 (basic color support) will downsample an RGB value of #FF0000 (red) to 91 (ANSI escape for bright-red).\n\nExamples:\n\n- `gchalk.WithHex('#DEADED').Underline('Hello, world!')`\n- `gchalk.WithRGB(15, 100, 204).Inverse('Hello!')`\n\nBackground versions of these models are prefixed with `Bg` and the first level of the module capitalized:\n\n- `gchalk.WithBgHex('#DEADED').Underline('Hello, world!')`\n- `gchalk.WithBgRgb(15, 100, 204).Unverse('Hello!')`\n\nThe following color models can be used:\n\n- [`rgb`](https://en.wikipedia.org/wiki/RGB_color_model) - Example: `gchalk.RGB(255, 136, 0)('Orange!')`\n- [`hex`](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet) - Example: `gchalk.Hex('#FF8800')('Orange!')`\n- [`ansi256`](https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit) - Example: `gchalk.BgAnsi256(194)('Honeydew, more or less')`\n- [`ansi`](https://en.wikipedia.org/wiki/ANSI_escape_code#3/4_bit) - Example: `gchalk.WithAnsi(31).BgAnsi(93)('red on bright yellow')`\n\n## Windows 10 Support\n\nGChalk is cross-platform, and will work on Linux and MacOS systems, but will also work on Windows 10, and without the need for writing to a special stream or using [ansicon](https://github.com/adoxa/ansicon).\n\nMany ANSI color libraries for Go do a poor job of handling colors in Windows. This is because historically, Windows has not supported ANSI color codes, so hacks like ansicon or [go-colorable](https://github.com/mattn/go-colorable) were required. However, Windows 10 has supported ANSI escape codes since 2017 (build 10586 for 256 color support, and build 14931 for 16.7 million true color support). In [Windows Terminal](https://github.com/Microsoft/Terminal) this is enabled by default, but in `CMD.EXE` or PowerShell, ANSI support must be enabled via [`ENABLE_VIRTUAL_TERMINAL_PROCESSING`](https://docs.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences). GChalk, of course, takes care of all of this for you. This functionality is also availabile in the [supportscolor](https://github.com/jwalton/go-supportscolor) library if you're an ANSI library author and you'd like to add this functionality to your own project.\n\n## Color Detection\n\nColor support is automatically detected using [supportscolor](https://github.com/jwalton/go-supportscolor), and [flags and command line arguments](https://github.com/jwalton/go-supportscolor#info) supported by supportscolor are also supported here. GChalk will automatically obey all the recommendations from [Command Line Interface Guidelines](https://clig.dev/#output). The following will disable color:\n\n- stdout is not a TTY. (Or, for `gchalk.Stderr`, stderr is not a TTY.)\n- The `NO_COLOR` environment variable is set.\n- The `TERM` variable has the value `dumb`.\n- The user passes the option `--no-color`, `--no-colors`, `--color=false`, or `--color=never`.\n- The `FORCE_COLOR` environment variable is 0.\n\nColor support will be forcefully enabled if:\n\n- The `FORCE_COLOR` environment variable is set to `1`, `2`, or `3` (for 16 color, 256 color, and 16.7m color support, respectively).\n- The `FORCE_COLOR` environment variable is set with no value, or with `true`.\n- The uses passes the option `--color`, `--colors`, `--color=true`, or `--color=always`.\n\nGChalk will also support colored output when run from popular CI environments, including Travis, CircleCI, Appveyor, GitlabCI, GitHub Actions, Buildkite, Drone, and TeamCity.\n\n## Related\n\n- [ansistyles](https://github.com/jwalton/gchalk/tree/master/pkg/ansistyles) - A low level library for generating ANSI escape codes, ported from Node.js's [ansi-styles](https://github.com/chalk/ansi-styles).\n- [supportscolor](https://github.com/jwalton/go-supportscolor) - Detect whether a terminal supports color, ported from Node.js's [supports-color](https://github.com/chalk/supports-color).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjwalton%2Fgchalk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjwalton%2Fgchalk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjwalton%2Fgchalk/lists"}