termcolor

README

termcolor

termcolor provides a simple and convenient API to output colorized terminal output with support for terminal detection and color supression.

Installation

termcolor uses go modules and requires Go 1.14 or greater.

$ go get -u github.com/halimath/termcolor

Usage

termcolor provides a Printer type which accepts strings and optional style attributes and outputs colorized output to an io.Writer. Factory functions for STDOUT, STDERR and *os.File are included which automatically detect, if the underlying device is a character device.

p := termcolor.Stdout()

p.Printf("Welcome to %s output!", p.Styled("colored", termcolor.ForegroundCyan), termcolor.Bold)

Changelog

0.1.0

• Initial release

License

Copyright 2022 Alexander Metzner.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Documentation

Overview

termcolor defines types and functions to output colorized console output.

termcolor provides a Printer that wraps an io.Writer to print colorized messages. It supports a guard that suppresses all color information if the Printer's underlying io.Writer is no TTY. Thus, applications can use a single, colorized output API but have standard text being printed if outout is redirected.

Example

package main

import (
	"github.com/halimath/termcolor"
)

func main() {
	p := termcolor.Stdout()

	p.Printf("Welcome to %s output!", p.Styled("colored", termcolor.ForegroundCyan), termcolor.Bold)

}

Output:
Welcome to colored output!

Index

• Constants
• func Activate(styles ...style) string
• func ApplyStyles(s string, styles ...style) string
• type Printer
  • func New(w io.Writer, tty bool) *Printer
  • func NewFromFile(f *os.File) *Printer
  • func Stderr() *Printer
  • func Stdout() *Printer
  • func (p *Printer) Print(msg string, styles ...style) error
  • func (p *Printer) Printf(format string, argsAndStyles ...interface{}) error
  • func (p *Printer) Println(msg string, styles ...style) error
  • func (p *Printer) Styled(s string, styles ...style) string

Examples

• Package

Constants

const (

	// Reset rests all styles to their default.
	Reset style = "0"

	// Bold renders text in bold (somewhat brighter).
	Bold style = "1"

	// Default applies the default styles.
	Default style = "22"

	// Foreground color black
	ForegroundBlack style = "30"
	// Foreground color red
	ForegroundRed style = "31"
	// Foreground color green
	ForegroundGreen style = "32"
	// Foreground color yellow
	ForegroundYellow style = "33"
	// Foreground color blue
	ForegroundBlue style = "34"
	// Foreground color magenta
	ForegroundMagenta style = "35"
	// Foreground color cyan
	ForegroundCyan style = "36"
	// Foreground color white
	ForegroundWhite style = "37"

	// Background color back
	BackgroundBlack style = "40"
	// Background color red
	BackgroundRed style = "41"
	// Background color green
	BackgroundGreen style = "42"
	// Background color yellow
	BackgroundYellow style = "43"
	// Background color blue
	BackgroundBlue style = "44"
	// Background color magenta
	BackgroundMagenta style = "45"
	// Background color cyan
	BackgroundCyan style = "46"
	// Background color white
	BackgroundWhite style = "47"
)

Functions

func Activate

func Activate(styles ...style) string

Activate returns a string that activates styles.

func ApplyStyles

func ApplyStyles(s string, styles ...style) string

ApplyStyles applies all styles to s and returns the resulting string.

Types

type Printer

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

Printer defines a type that provides methods to produce colorized output. Output is written to w if isTTY is set to true, otherwise output is written unstyled.

func New

func New(w io.Writer, tty bool) *Printer

New creates a new Printer writing to w and applying coloring if tty is set to true.

func NewFromFile

func NewFromFile(f *os.File) *Printer

NewFromFile creates a new Printer writing to f and applying colors if f is character device.

func Stderr

func Stderr() *Printer

Stderr creates a Printer for os.Stderr applying colors if stout is a console device.

func Stdout

func Stdout() *Printer

Stdout creates a Printer for os.Stdout applying colors if stout is a console device.

func (*Printer) Print

func (p *Printer) Print(msg string, styles ...style) error

Print prints msg with all styles applied. It returns any error returned from writing to p's io.Writer.

func (*Printer) Printf

func (p *Printer) Printf(format string, argsAndStyles ...interface{}) error

Printf prints formatted and styled output to p's underlying io.Writer. It works almost the same as fmt.Printf with the exception that any value given in argsAndStyles that is of type style will be excluded from formatting and will be used to style the overall string in stead. So

p.Printf("hello, %s", "world", termcolor.ForegroundRed)

will print "hello, world" in red color, if p is a TTY.

It returns any error returned from writing to p's io.Writer.

func (*Printer) Println

func (p *Printer) Println(msg string, styles ...style) error

Println prints msg with all styles applied followed by a single newline. It returns any error returned from writing to p's io.Writer.

func (*Printer) Styled

func (p *Printer) Styled(s string, styles ...style) string

Styled applies styles to s and returns that string if p's underlying io.Writer is a TTY. Otherwise s is returned unchanged.