chalk

README

chalk

Chalk is a go package for styling console/terminal output.

Check out godoc for some example usage: http://godoc.org/github.com/ttacon/chalk

The api is pretty clean, there are default Colors and TextStyles which can be mixed to create more intense Styles. Styles and Colors can be printed in normal strings (i.e. fmt.Sprintf(chalk.Red)), but Styles, Colors and TextStyles are more meant to be used to style specific text segments (i.e. fmt.Println(chalk.Red.Color("this is red")) or fmt.Println(myStyle.Style("this is blue text that is underlined"))).

Examples

There are a few examples in the examples directory if you want to see a very simplified version of what you can do with chalk.

The following code:

package main

import (
	"fmt"

	"github.com/ttacon/chalk"
)

func main() {
	// You can just use colors
	fmt.Println(chalk.Red, "Writing in colors", chalk.Cyan, "is so much fun", chalk.Reset)
	fmt.Println(chalk.Magenta.Color("You can use colors to color specific phrases"))

	// You can just use text styles
	fmt.Println(chalk.Bold.TextStyle("We can have bold text"))
	fmt.Println(chalk.Underline.TextStyle("We can have underlined text"))
	fmt.Println(chalk.Bold, "But text styles don't work quite like colors :(")

	// Or you can use styles
	blueOnWhite := chalk.Blue.NewStyle().WithBackground(chalk.White)
	fmt.Printf("%s%s%s\n", blueOnWhite, "And they also have backgrounds!", chalk.Reset)
	fmt.Println(
		blueOnWhite.Style("You can style strings the same way you can color them!"))
	fmt.Println(
		blueOnWhite.WithTextStyle(chalk.Bold).
			Style("You can mix text styles with colors, too!"))

	// You can also easily make styling functions thanks to go's functional side
	lime := chalk.Green.NewStyle().
		WithBackground(chalk.Black).
		WithTextStyle(chalk.Bold).
		Style
	fmt.Println(lime("look at this cool lime text!"))
}

Outputs

WARNING

This package should be pretty stable (I don't forsee backwards incompatible changes), but I'm not making any promises :)

Documentation

Overview

Package chalk is a package for styling terminal/console output. There are three main components:

Colors

There are eight default colors: black, red, green, yellow, blue, magenta, cyan and white. You can use them in two main ways (note the need for the reset color if you don't use Color()):

fmt.Println(chalk.Red, "this is red text", chalk.ResetColor)
fmt.Println(chalk.Red.Color("this is red text")

TextStyles

There are seven default text styles: bold, dim, italic, underline, inverse, hidden and strikethrough. Unlike colors, you should only really use TextStyles in the following manner:

fmt.Println(chalk.Bold.TextStyle("this is bold text"))

Styles

Styles are where all the business really is. Styles can have a foreground color, a background color and a text style (sweet!). They're also pretty simply to make, you just need a starting point:

blue := chalk.Blue.NewStyle()
bold := chalk.Bold.NewStyle()

When a color is your starting point for a style, it will be the foreground color, when a style is your starting point, well, yeah, it's your style's text style. You can also alter a style's foreground, background or text style in a builder-esque pattern.

blueOnWhite := blue.WithBackground(chalk.White)
awesomeness := blueOnWhite.WithTextStyle(chalk.Underline).WithForeground(chalk.Green)

Like both Colors and TextStyles you can style specific segments of text with:

fmt.Println(awesomeness.Style("this is so pretty!"))

Like Colors, you can also print styles explicitly, but you'll need to reset your console's colors with chalk.Reset if you use them this way:

fmt.Println(awesomeness, "this is so pretty", chalk.Reset)

Be aware though, that this (second) way of using styles will not add the text style (as text styles require more specific end codes). So if you want to fully utilize styles, use myStyle.Style() (unless you only care about print your text with a specific foreground and background, then printing the style is awesome too!).

Have fun!

Index

• Variables
• type Color
  • func (c Color) Color(val string) string
  • func (c Color) NewStyle() Style
  • func (c Color) String() string
  • func (c Color) Value() int
• type Style
• type TextStyle
  • func (t TextStyle) NewStyle() Style
  • func (t TextStyle) String() string
  • func (t TextStyle) TextStyle(val string) string

Variables

var (
	// Colors
	Black      = Color{0}
	Red        = Color{1}
	Green      = Color{2}
	Yellow     = Color{3}
	Blue       = Color{4}
	Magenta    = Color{5}
	Cyan       = Color{6}
	White      = Color{7}
	ResetColor = Color{9}

	// Text Styles
	Bold          = TextStyle{1, 22}
	Dim           = TextStyle{2, 22}
	Italic        = TextStyle{3, 23}
	Underline     = TextStyle{4, 24}
	Inverse       = TextStyle{7, 27}
	Hidden        = TextStyle{8, 28}
	Strikethrough = TextStyle{9, 29}

	Reset = &style{
		foreground: ResetColor,
		background: ResetColor,
	}
)

Types

type Color

type Color struct {
	// contains filtered or unexported fields
}

Color represents one of the ANSI color escape codes. http://en.wikipedia.org/wiki/ANSI_escape_code#Colors

func (Color) Color

func (c Color) Color(val string) string

Color colors the foreground of the given string (whatever the previous background color was, it is left alone).

func (Color) NewStyle

func (c Color) NewStyle() Style

NewStyle creates a style with a foreground of the color we're creating the style from.

func (Color) String

func (c Color) String() string

func (Color) Value

func (c Color) Value() int

Value returns the individual value for this color (Actually it's really just its index in the list of color escape codes with the list being [black, red, green, yellow, blue, magenta, cyan, white].

type Style

type Style interface {
	// Foreground sets the foreground of the style to the specific color.
	Foreground(Color)
	// Background sets the background of the style to the specific color.
	Background(Color)
	// Style styles the given string with the current style.
	Style(string) string
	// WithBackground allows us to set the background in a builder
	// pattern style.
	WithBackground(Color) Style
	// WithForeground allows us to set the foreground in a builder
	// pattern style.
	WithForeground(Color) Style
	// WithStyle allows us to set the text style in a builder pattern
	// style.
	WithTextStyle(TextStyle) Style
	String() string
}

A Style is how we want our text to look in the console. Consequently, we can set the foreground and background to specific colors, we can style specific strings and can also use this style in a builder pattern should we wish (these will be more useful once styles such as italics are supported).

type TextStyle

type TextStyle struct {
	// contains filtered or unexported fields
}

A TextStyle represents the ways we can style the text: bold, dim, italic, underline, inverse, hidden or strikethrough.

func (TextStyle) NewStyle

func (t TextStyle) NewStyle() Style

NewStyle creates a style starting with the current TextStyle as its text style.

func (TextStyle) String

func (t TextStyle) String() string

NOTE: this function specifically does not work as desired because text styles must be wrapped around the text they are meant to style. As such, use TextStyle() or Style.Style() instead.

func (TextStyle) TextStyle

func (t TextStyle) TextStyle(val string) string

TexStyle styles the given string using the desired text style.