iostreams

Documentation

Overview

Package iostreams provides access to the terminal outputs and inputs in a centralized and mockable fashion. All terminal access should happen using this package.

Example

Example_output shows how text can be outputted with color and style

package main

import (
	"fmt"

	"github.com/hashicorp/hcp/internal/pkg/iostreams"
)

func main() {
	// Use iostreams.System for real usage.
	io := iostreams.Test()

	cs := io.ColorScheme()
	fmt.Fprintln(io.Out(), cs.String("Applying Style").Bold())
	fmt.Fprintln(io.Out(), cs.String("Chaining Styles").Bold().Italic())

	fmt.Fprintln(io.Out(), cs.String("Applying Color").Color(cs.Orange()))
	fmt.Fprintln(io.Out(), cs.String("Applying Color and Style").Bold().Color(cs.Orange()))

	// Changing the background
	fmt.Fprintln(io.Out(), cs.String("WARNING").Bold().Background(cs.Orange()).Color(cs.Black()))

	// Print the test output
	fmt.Print(io.Output.String())

}

Output:

Applying Style
Chaining Styles
Applying Color
Applying Color and Style
WARNING

Index

• Constants
• func NopWriteCloser(w io.Writer) io.WriteCloser
• type Color
• type ColorScheme
  • func (cs *ColorScheme) Black() Color
  • func (cs *ColorScheme) ErrorLabel() String
  • func (cs *ColorScheme) FailureIcon() String
  • func (cs *ColorScheme) Gray() Color
  • func (cs *ColorScheme) Green() Color
  • func (cs *ColorScheme) Orange() Color
  • func (cs *ColorScheme) RGB(hex string) Color
  • func (cs *ColorScheme) Red() Color
  • func (cs *ColorScheme) String(s string) String
  • func (cs *ColorScheme) SuccessIcon() String
  • func (cs *ColorScheme) WarningLabel() String
  • func (cs *ColorScheme) White() Color
  • func (cs *ColorScheme) Yellow() Color
• type Emphasis
• type IOStreams
  • func MD() IOStreams
  • func System(ctx context.Context) (IOStreams, error)
  • func UseLoud(io IOStreams) IOStreams
• type IsMarkdownOutput
• type Loud
• type String
  • func (s String) Background(c Color) String
  • func (s String) Blink() String
  • func (s String) Bold() String
  • func (s String) Code() String
  • func (s String) CodeBlock(extension string) String
  • func (s String) Color(c Color) String
  • func (s String) CrossOut() String
  • func (s String) Faint() String
  • func (s String) Italic() String
  • func (s String) String() string
  • func (s String) Underline() String
• type Testing
  • func Test() *Testing
  • func (t *Testing) CanPrompt() bool
  • func (t *Testing) ColorEnabled() bool
  • func (t *Testing) ColorScheme() *ColorScheme
  • func (t *Testing) Err() io.Writer
  • func (t *Testing) ForceNoColor()
  • func (t *Testing) ForcedColorProfile(profile termenv.Profile)
  • func (t *Testing) In() io.Reader
  • func (t *Testing) IsErrorTTY() bool
  • func (t *Testing) IsInputTTY() bool
  • func (t *Testing) IsOutputTTY() bool
  • func (t *Testing) LoudErr() io.Writer
  • func (t *Testing) Out() io.Writer
  • func (t *Testing) PromptConfirm(prompt string) (bool, error)
  • func (t *Testing) ReadSecret() ([]byte, error)
  • func (t *Testing) RestoreConsole() error
  • func (t *Testing) SetQuiet(quiet bool)
  • func (t *Testing) TerminalWidth() int

Examples

• Package

Constants

const (
	// TerminalDefaultWidth is the default width of the terminal if the width
	// cannot be determined.
	TerminalDefaultWidth = 80
)

Functions

func NopWriteCloser

func NopWriteCloser(w io.Writer) io.WriteCloser

NopWriteCloser wraps an io.Writer with a Close method

Types

type Color

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

Color is represents a color.

type ColorScheme

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

ColorScheme is used to style and color text according to the capabilities of the current terminal. It will automatically degrade the requested styling to what the system is capable for outputting.

func (*ColorScheme) Black

func (cs *ColorScheme) Black() Color

Black is the color black.

func (*ColorScheme) ErrorLabel

func (cs *ColorScheme) ErrorLabel() String

ErrorLabel returns a colored error label.

func (*ColorScheme) FailureIcon

func (cs *ColorScheme) FailureIcon() String

FailureIcon returns a failure icon.

func (*ColorScheme) Gray

func (cs *ColorScheme) Gray() Color

Gray is the color gray.

func (*ColorScheme) Green

func (cs *ColorScheme) Green() Color

Green is the color green.

func (*ColorScheme) Orange

func (cs *ColorScheme) Orange() Color

Orange is the color orange.

func (*ColorScheme) RGB

func (cs *ColorScheme) RGB(hex string) Color

RGB allows setting an RGB color in the format "#<hex>". If the terminal does not support TrueColor, the nearest approximate and supported color will be used.

func (*ColorScheme) Red

func (cs *ColorScheme) Red() Color

Red is the color red.

func (*ColorScheme) String

func (cs *ColorScheme) String(s string) String

String wraps the given string. The wrapped String can then have style or color applied to it.

func (*ColorScheme) SuccessIcon

func (cs *ColorScheme) SuccessIcon() String

SuccessIcon returns a success icon.

func (*ColorScheme) WarningLabel

func (cs *ColorScheme) WarningLabel() String

WarningLabel returns a colored warning label.

func (*ColorScheme) White

func (cs *ColorScheme) White() Color

White is the color white.

func (*ColorScheme) Yellow

func (cs *ColorScheme) Yellow() Color

Yellow is the color yellow.

type Emphasis

type Emphasis int

Emphasis is used to style text.

const (
	EmphasisBold Emphasis = iota
	EmphasisItalic
	EmphasisUnderline
	EmphasisCrossOut
	EmphasisCode
	EmphasisCodeBlock
)

type IOStreams

type IOStreams interface {
	// In returns an io.Reader for reading input
	In() io.Reader

	// Out returns an io.Writer for outputting non-error output
	Out() io.Writer

	// Err returns an io.Writer for outputting error output
	Err() io.Writer

	// ColorEnabled returns if color is enabled.
	ColorEnabled() bool

	// ForceNoColor forces no color output
	ForceNoColor()

	// ColorScheme returns a ColorScheme for coloring and formatting output.
	ColorScheme() *ColorScheme

	// RestoreConsole should be called the console to its original state. This
	// should be called in a defer method after retrieving an IOStream.
	RestoreConsole() error

	// ReadSecret reads a line of input without local echo. The returned data
	// does not include the \n delimeter.
	ReadSecret() ([]byte, error)

	// PromptConfirm prompts for a confirmation from the user.
	PromptConfirm(prompt string) (bool, error)

	// IsInputTTY returns whether the input is a TTY
	IsInputTTY() bool

	// IsOutputTTY returns whether the output is a TTY
	IsOutputTTY() bool

	// IsErrorTTY returns whether the error output is a TTY
	IsErrorTTY() bool

	// TerminalWidth returns the width of the terminal that controls the process
	TerminalWidth() int

	// CanPrompt returns true if prompting is available. Both the input and
	// error output must be a TTY for this to return true as well as SetQuiet
	// must not be true.
	CanPrompt() bool

	// SetQuiet updates the iostream to disable Err output and prompting.
	SetQuiet(quiet bool)
}

IOStreams is an interface for interacting with IO and general terminal output. Commands should not directly interact with os.Stdout/Stderr/Stdin but utilize the passed IOStreams.

func MD

func MD() IOStreams

MD returns a new IOStreams instance that is configured to output markdown.

func System

func System(ctx context.Context) (IOStreams, error)

System returns an IOStreams meant to interact with the systems terminal.

func UseLoud

func UseLoud(io IOStreams) IOStreams

UseLoud takes an IOStream and if it implements the Load interfaces, it will be used instead of the quiet alternatives.

type IsMarkdownOutput

type IsMarkdownOutput interface {
	IOStreams

	// SetMD sets the IOStreams instance to output markdown or not. This can be
	// useful to temporarily change the output format.
	SetMD(bool)
}

IsMarkdownOutput is an interface that when met, indicates that the IOStreams instance is configured to output markdown.

type Loud

type Loud interface {
	IOStreams

	LoudErr() io.Writer
}

Loud is unimpacted by quiet being set on the iostreams.

type String

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

String is a stylized string.

func (String) Background

func (s String) Background(c Color) String

Background applies the given color to the texts background.

func (String) Blink

func (s String) Blink() String

Blink makes the text blink.

func (String) Bold

func (s String) Bold() String

Bold makes the string bold.

func (String) Code

func (s String) Code() String

Code makes the text output as code. Only applies to markdown output.

func (String) CodeBlock

func (s String) CodeBlock(extension string) String

CodeBlock makes the text output as a code block and sets the extension for highlighting. Only applies to markdown output.

func (String) Color

func (s String) Color(c Color) String

Color applies the given color to the texts foreground.

func (String) CrossOut

func (s String) CrossOut() String

CrossOut makes the text have a cross through it middle height wise.

func (String) Faint

func (s String) Faint() String

Faint makes the text faint.

func (String) Italic

func (s String) Italic() String

Italic makes the text italic.

func (String) String

func (s String) String() string

String implements the fmt.Stringer interface. The wrapped string will be printed with the appropriate control sequences applied to have the string stylized as requested.

func (String) Underline

func (s String) Underline() String

Underline makes the text underlined.

type Testing

type Testing struct {
	// Input should be written to simulate Stdin.
	Input *bytes.Buffer

	// Output contains all data emitted to the Out stream.
	Output *bytes.Buffer

	// Error contains all data emitted to the Err stream.
	Error *bytes.Buffer

	// InputTTY, OutputTTY, and ErrorTTY control whether the testing IOStreams
	// treats each respective FD as a TTY.
	InputTTY  bool
	OutputTTY bool
	ErrorTTY  bool
	// contains filtered or unexported fields
}

Testing implements the IOStreams interface and provides programtic access to both input and output.

func Test

func Test() *Testing

Test returns a new IOStreams for testing.

func (*Testing) CanPrompt

func (t *Testing) CanPrompt() bool

func (*Testing) ColorEnabled

func (t *Testing) ColorEnabled() bool

func (*Testing) ColorScheme

func (t *Testing) ColorScheme() *ColorScheme

func (*Testing) Err

func (t *Testing) Err() io.Writer

func (*Testing) ForceNoColor

func (t *Testing) ForceNoColor()

func (*Testing) ForcedColorProfile

func (t *Testing) ForcedColorProfile(profile termenv.Profile)

ForcedColorProfile allows forcing a specific color profile for testing.

func (*Testing) In

func (t *Testing) In() io.Reader

func (*Testing) IsErrorTTY

func (t *Testing) IsErrorTTY() bool

func (*Testing) IsInputTTY

func (t *Testing) IsInputTTY() bool

func (*Testing) IsOutputTTY

func (t *Testing) IsOutputTTY() bool

func (*Testing) LoudErr

func (t *Testing) LoudErr() io.Writer

func (*Testing) Out

func (t *Testing) Out() io.Writer

func (*Testing) PromptConfirm

func (t *Testing) PromptConfirm(prompt string) (bool, error)

Prompt confirm for testing attempts to read a single byte from stdin. If the byte is y, true is returned, if it is n, false is returned. Any other value is an error

func (*Testing) ReadSecret

func (t *Testing) ReadSecret() ([]byte, error)

func (*Testing) RestoreConsole

func (t *Testing) RestoreConsole() error

func (*Testing) SetQuiet

func (t *Testing) SetQuiet(quiet bool)

func (*Testing) TerminalWidth

func (t *Testing) TerminalWidth() int