term

README

term

Simple helpers for formatting terminal output

Usage

w := term.New()
w.Set(term.Yellow)
link := w.With(term.Blue, term.Underline)
fmt.Fprintf(w, "The url %s is used for examples\n", link.Render("https://example.com/"))

Installation

$ go get github.com/madss/term

License

MIT

Author

Mads Sejersen (a.k.a madss on github)

Documentation

Overview

The term package provides useful tooling for working with formatting and colors in a terminal.

The following formatting options are available:

• Bold
• Faint
• Italic
• Underline
• Blink
• Negative
• Invisible
• StrikeThrough

The following colors are available for both text and background:

• Black and BlackBackground
• Red and RedBackground
• Green and GreenBackground
• Yellow and YellowBackground
• Blue and BlueBackground
• Magenta and MagentaBackground
• Cyan and CyanBackground
• White and WhiteBackground

The colors also exist in a bright variant:

• BrightBlack and BrightBlackBackground
• BrightRed and BrightRedBackground
• BrightGreen and BrightGreenBackground
• BrightYellow and BrightYellowBackground
• BrightBlue and BrightBlueBackground
• BrightMagenta and BrightMagentaBackground
• BrightCyan and BrightCyanBackground
• BrightWhite and BrightWhiteBackground

Index

• func Black(ctx *Context)
• func BlackBackground(ctx *Context)
• func Blink(ctx *Context)
• func Blue(ctx *Context)
• func BlueBackground(ctx *Context)
• func Bold(ctx *Context)
• func BrightBlack(ctx *Context)
• func BrightBlackBackground(ctx *Context)
• func BrightBlue(ctx *Context)
• func BrightBlueBackground(ctx *Context)
• func BrightCyan(ctx *Context)
• func BrightCyanBackground(ctx *Context)
• func BrightGreen(ctx *Context)
• func BrightGreenBackground(ctx *Context)
• func BrightMagenta(ctx *Context)
• func BrightMagentaBackground(ctx *Context)
• func BrightRed(ctx *Context)
• func BrightRedBackground(ctx *Context)
• func BrightWhite(ctx *Context)
• func BrightWhiteBackground(ctx *Context)
• func BrightYellow(ctx *Context)
• func BrightYellowBackground(ctx *Context)
• func Cyan(ctx *Context)
• func CyanBackground(ctx *Context)
• func Default(ctx *Context)
• func DefaultBackground(ctx *Context)
• func Faint(ctx *Context)
• func Green(ctx *Context)
• func GreenBackground(ctx *Context)
• func Invisible(ctx *Context)
• func Italic(ctx *Context)
• func Magenta(ctx *Context)
• func MagentaBackground(ctx *Context)
• func Negative(ctx *Context)
• func NoBlink(ctx *Context)
• func NoBold(ctx *Context)
• func NoFaint(ctx *Context)
• func NoInvisible(ctx *Context)
• func NoItalic(ctx *Context)
• func NoNegative(ctx *Context)
• func NoStrikeThrough(ctx *Context)
• func NoUnderline(ctx *Context)
• func Red(ctx *Context)
• func RedBackground(ctx *Context)
• func StrikeThrough(ctx *Context)
• func Underline(ctx *Context)
• func White(ctx *Context)
• func WhiteBackground(ctx *Context)
• func Yellow(ctx *Context)
• func YellowBackground(ctx *Context)
• type Context
  • func (ctx *Context) Apply(opts ...Option)
  • func (ctx *Context) Format(format string, a ...interface{}) string
  • func (ctx *Context) Render(s string) string
  • func (ctx *Context) Reset()
  • func (ctx *Context) Set(opts ...Option)
  • func (ctx *Context) With(opts ...Option) *Context
  • func (ctx *Context) Write(w io.Writer, data []byte) (int, error)
• type Option
• type Writer
  • func New() *Writer
  • func NewWriter(w io.Writer) *Writer
  • func (w Writer) With(opts ...Option) *Writer
  • func (w Writer) Write(b []byte) (n int, err error)

Examples

• New
• NewWriter
• Writer.With

Functions

func Black

func Black(ctx *Context)

func BlackBackground

func BlackBackground(ctx *Context)

func Blink

func Blink(ctx *Context)

func Blue

func Blue(ctx *Context)

func BlueBackground

func BlueBackground(ctx *Context)

func Bold

func Bold(ctx *Context)

func BrightBlack

func BrightBlack(ctx *Context)

func BrightBlackBackground

func BrightBlackBackground(ctx *Context)

func BrightBlue

func BrightBlue(ctx *Context)

func BrightBlueBackground

func BrightBlueBackground(ctx *Context)

func BrightCyan

func BrightCyan(ctx *Context)

func BrightCyanBackground

func BrightCyanBackground(ctx *Context)

func BrightGreen

func BrightGreen(ctx *Context)

func BrightGreenBackground

func BrightGreenBackground(ctx *Context)

func BrightMagenta

func BrightMagenta(ctx *Context)

func BrightMagentaBackground

func BrightMagentaBackground(ctx *Context)

func BrightRed

func BrightRed(ctx *Context)

func BrightRedBackground

func BrightRedBackground(ctx *Context)

func BrightWhite

func BrightWhite(ctx *Context)

func BrightWhiteBackground

func BrightWhiteBackground(ctx *Context)

func BrightYellow

func BrightYellow(ctx *Context)

func BrightYellowBackground

func BrightYellowBackground(ctx *Context)

func Cyan

func Cyan(ctx *Context)

func CyanBackground

func CyanBackground(ctx *Context)

func Default

func Default(ctx *Context)

func DefaultBackground

func DefaultBackground(ctx *Context)

func Faint

func Faint(ctx *Context)

func Green

func Green(ctx *Context)

func GreenBackground

func GreenBackground(ctx *Context)

func Invisible

func Invisible(ctx *Context)

func Italic

func Italic(ctx *Context)

func Magenta

func Magenta(ctx *Context)

func MagentaBackground

func MagentaBackground(ctx *Context)

func Negative

func Negative(ctx *Context)

func NoBlink

func NoBlink(ctx *Context)

func NoBold

func NoBold(ctx *Context)

func NoFaint

func NoFaint(ctx *Context)

func NoInvisible

func NoInvisible(ctx *Context)

func NoItalic

func NoItalic(ctx *Context)

func NoNegative

func NoNegative(ctx *Context)

func NoStrikeThrough

func NoStrikeThrough(ctx *Context)

func NoUnderline

func NoUnderline(ctx *Context)

func Red

func Red(ctx *Context)

func RedBackground

func RedBackground(ctx *Context)

func StrikeThrough

func StrikeThrough(ctx *Context)

func Underline

func Underline(ctx *Context)

func White

func White(ctx *Context)

func WhiteBackground

func WhiteBackground(ctx *Context)

func Yellow

func Yellow(ctx *Context)

func YellowBackground

func YellowBackground(ctx *Context)

Types

type Context

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

A Context keeps track of the current state of the terminal.

func (*Context) Apply

func (ctx *Context) Apply(opts ...Option)

Apply updates the state of the context with the additional options.

func (*Context) Format

func (ctx *Context) Format(format string, a ...interface{}) string

Format formats a string as with fmt.Sprintf but with formatting applied.

func (*Context) Render

func (ctx *Context) Render(s string) string

Render returns s with with formatting applied.

func (*Context) Reset

func (ctx *Context) Reset()

Reset resets the context to the default state.

func (*Context) Set

func (ctx *Context) Set(opts ...Option)

Set sets the state of the context to the provided options.

func (*Context) With

func (ctx *Context) With(opts ...Option) *Context

With creates a new child context.

The new context overrides the attributes of the parent context.

func (*Context) Write

func (ctx *Context) Write(w io.Writer, data []byte) (int, error)

Write writes data to w with formatting applied.

Note: The number of bytes written excludes the escape codes, to comply with constumers that expect the number of bytes written to be less than or equal to then length of data.

type Option

type Option func(*Context)

An Option is a function that modifies a Context.

type Writer

type Writer struct {
	Context
	// contains filtered or unexported fields
}

A Writer is a implements the io.Writer interface.

The embedded Context can be used for formatting the output.

func New

func New() *Writer

New returns a new Writer.

This is similar to NewWriter(os.Stdout), except that formatting will only be applied if os.Stdout is a real tty.

Example

t := New()
for _, opt := range []Option{Red, Green, Blue} {
	t.Set(opt)
	fmt.Fprintln(t, "Hello, world!")
}

Output:

�[31mHello, world!
�[39m�[32mHello, world!
�[39m�[34mHello, world!
�[39m

func NewWriter

func NewWriter(w io.Writer) *Writer

NewWriter returns a new Writer that writes to w.

Example

w := NewWriter(os.Stdout)
w.Set(Red)
fmt.Fprint(w, "Hello, world!")

Output:

�[31mHello, world!�[39m

func (Writer) With

func (w Writer) With(opts ...Option) *Writer

With creates a new child Writer.

The child Writer will inherit the parameters of the parent, only overriding the parameters provided. This is useful for temporarily changing the formatting.

Example

t := New()
t.Set(Yellow)
fmt.Fprintf(
	t,
	"The url %s is used for examples",
	t.With(Blue, Underline).Render("https://example.com/"),
)

Output:

�[33mThe url �[4;34mhttps://example.com/�[24;33m is used for examples�[39m

func (Writer) Write

func (w Writer) Write(b []byte) (n int, err error)

Write implements the io.Writer interface.