color

package module
v0.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 29, 2024 License: BSD-3-Clause Imports: 8 Imported by: 2

README

color - ANSI Terminal Color(s)

The color package provides terminal escape sequences for giving life to console output.

terminal-output-example

Overview

ANSI escape sequence processing allows capable output device(s) to display color.

While there exists other packages, github.com/x-ethr/color dynamically determines if the given output device is capable of escaping. For usage with CI and production systems, color will automatically disable adding color to user-provided value(s).

Additionally, users can optionally force color for their own testing purposes if necessary (for users implementing custom loggers, for example).

Documentation

Official godoc documentation (with examples) can be found at the Package Registry.

Usage

Add Package Dependency
go get -u github.com/x-ethr/color
Import & Implement

main.go

package main

import (
    "fmt"

    "github.com/x-ethr/color"
)

func main() {
    // --> Write the content "Default" out to stdout without color
    color.Color().Default("Default").Print() // Output: Default

    // --> Write the content "Red", "Blue", "Green" out to stdout with color escapes
    color.Color().Red("Red").Print() // Output: Red
    color.Color().Blue("Blue").Print() // Output: Blue
    color.Color().Green("Green").Print() // Output: Green

    // --> Wrap color(s) with bold color escapes and write to stdout
    color.Color().Bold(color.Color().Cyan("Cyan")).Print() // Output: Cyan

    // --> Customize how newlines and spaces are added to the formatted output
    color.Color().Red("Color-1").Print(func(o *color.Options) { o.Line = false; o.Space = true })
    color.Color().Red("Color-2").Print(func(o *color.Options) { o.Line = false; o.Space = true })
    color.Color().Red("Color-3").Print()

    // Output: Color-1 Color-2 Color-3

    // --> Store the ANSI-modified string to a variable and then format, write the value to stdout
    v := color.Color().Italic(color.Color().Magenta("Magenta")).String()

    fmt.Printf("Example Magenta Color Output: %s\n", v)
    // Output: Example Magenta Color Output: Magenta
}

Contributions

See the Contributing Guide for additional details on getting started.

Documentation

Overview

Package color provides ANSI color codes for output formatting.

Example 
package main

import (
	"fmt"

	"github.com/x-ethr/color"
)

func main() {
	color.Unset() // forcefully unset the package [atomic.Value] so example tests can pass

	// --> Write the content "Default" out to stdout without color
	color.Color().Default("Default").Print()

	// --> Write the content "red", "blue", "green" out to stdout with color escapes
	color.Color().Red("Red").Print()
	color.Color().Blue("Blue").Print()
	color.Color().Green("Green").Print()

	// --> Wrap color(s) with bold color escapes and write to stdout
	color.Color().Bold(color.Color().Cyan("Cyan")).Print()

	// --> Customize how newlines and spaces are added to the formatted output
	color.Color().Red("Color-1").Print(func(o *color.Options) { o.Line = false; o.Space = true })
	color.Color().Red("Color-2").Print(func(o *color.Options) { o.Line = false; o.Space = true })
	color.Color().Red("Color-3").Print()

	// --> Store the ANSI-modified string to a variable and then format, write the value to stdout
	v := color.Color().Italic(color.Color().Magenta("Magenta")).String()

	fmt.Printf("Example Magenta Color Output: %s\n", v)

}

Output:

Default
Red
Blue
Green
Cyan
Color-1 Color-2 Color-3
Example Magenta Color Output: Magenta

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Available 

func Available() bool

Available checks if the terminal has a TTY (teletypewriter) available and returns a boolean value indicating if the system's output buffer is capable of color output.

func CI 

func CI() bool

CI checks if the terminal supports color output by checking the value of the "CI" environment variable.

  • If the "CI" environment variable is set to "true", "yes", "on", or "1", CI returns true.
  • If the "CI" environment variable is set to "false", "no", "off", or "0", CI returns false.
  • If the "CI" environment variable is not set and terminal is not a TTY, CI returns true.

Default return value is true.

func Force 

func Force()

Force will force the runtime to color its output.

func Forcing 

func Forcing() bool

Forcing provides a sanity-check of the current, global atomic.Value assignment.

func Overload 

func Overload(ansi []byte, input string) string

Overload constructs an ANSI string with the provided ANSI Escape characters and the input string.

func Unset 

func Unset()

Unset provides the ability to globally, explicitly set the force atomic.Value value to false.

Types

type ANSI 

type ANSI string

ANSI represents a string that contains ANSI escape codes for terminal colors.

ANSI provides methods for applying different colors to the input string(s) and returning it as an ANSI string. It uses functions from the ANSI package to convert the input to the desired color. If the current operating system is not Windows and the CI variable is false, it adds the color code before and the reset code after each input string.

func Color 

func Color() *ANSI

Color initializes and returns a new ANSI string.

func (*ANSI) Black 

func (c *ANSI) Black(input ...any) *ANSI

Black applies the black color to the input string(s) and returns it as an ANSI string. It uses the Black() function from the ANSI package to convert the input to black color. If the current operating system is not Windows and CI is false, it adds the color code before and the reset code after each input string.

func (*ANSI) Blue 

func (c *ANSI) Blue(input ...any) *ANSI

blue applies the blue color to the input string(s) and returns it as an ANSI string. It uses the blue() function from the ANSI package to convert the input to blue color. If the current operating system is not Windows and CI is false, it adds the color code before and the reset code after each input string.

func (*ANSI) Bold 

func (c *ANSI) Bold(input ...any) *ANSI

bold applies the bold style to the input string(s) and returns it as an ANSI string. It uses the bold() function from the ANSI package to convert the input to bold style. If the current operating system is not Windows and CI is false, it adds the style code before and the reset code after each input string.

func (*ANSI) Cyan 

func (c *ANSI) Cyan(input ...any) *ANSI

cyan applies the cyan color to the input string(s) and returns it as an ANSI string. It uses the cyan() function from the ANSI package to convert the input to cyan color. If the current operating system is not Windows and CI is false, it adds the color code before and the reset code after each input string.

func (*ANSI) Default 

func (c *ANSI) Default(input ...any) *ANSI

Default applies the default color to the input string(s) and returns it as an ANSI string. It uses the Default() function from the ANSI package to convert the input to default color. If the current operating system is not Windows and CI is false, it adds the color code before and the reset code after each input string.

func (*ANSI) Dim 

func (c *ANSI) Dim(input ...any) *ANSI

dim applies a dimmed style to the input string(s) and returns it as an ANSI string. If the current operating system is not Windows and CI is false, it adds the style code before and the reset code after each input string.

func (*ANSI) Gray 

func (c *ANSI) Gray(input ...any) *ANSI

gray applies the gray color to the input string(s) and returns it as an ANSI string. It uses the gray() function from the ANSI package to convert the input to gray color. If the current operating system is not Windows and CI is false, it adds the color code before and the reset code after each input string.

func (*ANSI) Green 

func (c *ANSI) Green(input ...any) *ANSI

green applies the green color to the input string(s) and returns it as an ANSI string. It uses the green() function from the ANSI package to convert the input to green color. If the current operating system is not Windows and CI is false, it adds the color code before and the reset code after each input string.

func (*ANSI) Italic 

func (c *ANSI) Italic(input ...any) *ANSI

italic applies the italic style to the input string(s) and returns it as an ANSI string. It uses the italic() function from the ANSI package to convert the input to italic style. If the current operating system is not Windows and CI is false, it adds the style code before and the reset code after each input string.

func (*ANSI) Magenta 

func (c *ANSI) Magenta(input ...any) *ANSI

magenta applies the purple color to the input string(s) and returns it as an ANSI string. It uses the magenta() function from the ANSI package to convert the input to purple color. If the current operating system is not Windows and CI is false, it adds the color code before and the reset code after each input string.

func (*ANSI) Overload 

func (c *ANSI) Overload(ansi []byte, input string) *ANSI

Overload allows passing ANSI Escape characters directly. It constructs an ANSI string with the provided ANSI Escape characters and the input string.

func (*ANSI) Print 

func (c *ANSI) Print(settings ...Variadic)

Print outputs the ANSI string to the standard output based on the specified configuration settings.

By default, it does not add any extra characters at the end.

  • If the Line option is enabled, it adds a newline character after the ANSI string.
  • If the Space option is enabled, it adds a space character after the ANSI string.
  • It uses the os.Stdout and fmt.Fprintf methods to write the ANSI string to the standard output with the specified format.

For customizing the io.Writer, instead of using os.Stdout, see ANSI.Write.

func (*ANSI) Red 

func (c *ANSI) Red(input ...any) *ANSI

red applies the red color to the input string(s) and returns it as an ANSI string. It uses the red() function from the ANSI package to convert the input to red color. If the current operating system is not Windows and CI is false, it adds the color code before and the reset code after each input string.

func (*ANSI) String 

func (c *ANSI) String() string

String returns the ANSI string as a raw string.

func (*ANSI) White 

func (c *ANSI) White(input ...any) *ANSI

white applies the white color to the input string(s) and returns it as an ANSI string. It uses the white() function from the ANSI package to convert the input to white color. If the current operating system is not Windows and CI is false, it adds the color code before and the reset code after each input string.

func (*ANSI) Write 

func (c *ANSI) Write(w io.Writer, settings ...Variadic)

Write writes the ANSI string to the provided io.Writer. If c is not nil, it converts c to a string and trims any leading/trailing spaces. It then formats the string with a newline character and writes it to the io.Writer using fmt.Fprintf.

func (*ANSI) Yellow 

func (c *ANSI) Yellow(input ...any) *ANSI

yellow applies the yellow color to the input string(s) and returns it as an ANSI string. It uses the yellow() function from the ANSI package to convert the input to yellow color. If the current operating system is not Windows and the CI variable is false, it adds the color code before and the reset code after each input string.

type Options 

type Options struct {
	Line  bool // Line represents the option to add a newline character to the end of format calls such as [ANSI.Print] and [ANSI.Write]. Defaults to true.
	Space bool // Space represents the option to add a trailing space character to the end of format calls such as [ANSI.Print] and [ANSI.Write]. Defaults to false.
}

Options is the configuration structure optionally mutated via the Variadic constructor used throughout the package.

type Variadic 

type Variadic func(o *Options)

Variadic represents a functional constructor for the Options type. Typical callers of Variadic won't need to perform nil checks as all implementations first construct an Options reference using packaged default(s).

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.
JackTT - Gopher 🇻🇳