komando

README

komando

Build beautiful CLI experiences out of the box in Go.

Komando provides simple terminal UI components like Header, StepGroup, NamedValue and more to help you craft great informative CLI experiences quickly.

Stop wasting time customising lower level components to build what you need.

All components are easily testable with a Fake UI implementation and customisable using intuitive overrides.

Quickstart

package main

import (
	"fmt"
	"time"

	komando "github.com/appvia/komando"
)

func main() {
	ui := komando.ConsoleUI()
	ui.Header("Initialising project...")
	ui.Output("Running init framework using available steps")

	sg := ui.StepGroup()
	defer sg.Done()

	step1 := sg.Add("Step 1 - validate")
	step2 := sg.Add("Step 2 - execute")

	step1.Success()
	step2.Warning()

	for i := 0; i < 5; i++ {
		ui.Output(
			fmt.Sprintf("Step [2] substep [%v] - sleep 0.5s", i),
			komando.WithStyle(komando.LogStyle),
			komando.WithIndentChar(komando.LogIndentChar),
			komando.WithIndent(3),
		)
		time.Sleep(500 * time.Millisecond)
	}

	step3 := sg.Add("Step 3 - finalize")
	step3.Error()

	ui.Output("")
	ui.Output("Initialisation has failed!\nhere's what to do next...", komando.WithErrorBoldStyle())
}

Output:

Documentation

Index

• Constants
• func FakeUIAndLog() (UI, UILog)
• type NamedValue
• type Option
  • func WithErrorBoldStyle() Option
  • func WithErrorStyle() Option
  • func WithIndent(i int) Option
  • func WithIndentChar(char string) Option
  • func WithStyle(style string) Option
  • func WithWriter(w io.Writer) Option
• type Step
• type StepGroup
• type UI
  • func ConsoleUI() UI
  • func NoOpUI() UI
  • func PTermUI() UI
• type UILog

Constants

const (
	LogStepSuccess = "Success"
	LogStepWarning = "Warning"
	LogStepError   = "Error"
)

const (
	HeaderStyle              = "header"
	ErrorStyle               = "error"
	ErrorBoldStyle           = "error-bold"
	WarningStyle             = "warning"
	LogStyle                 = "log"
	WarningBoldStyle         = "warning-bold"
	SuccessStyle             = "success"
	SuccessBoldStyle         = "success-bold"
	ErrorIndentChar          = "✕"
	WarningIndentChar        = "!"
	SuccessIndentChar        = "✓"
	HeaderIndentChar         = "»"
	LogIndentChar            = "|"
	RecommendedWordWrapLimit = 80
)

Functions

func FakeUIAndLog

func FakeUIAndLog() (UI, UILog)

FakeUIAndLog returns a fake UI implementation and a log to help tracking of UI ops in tests.

Types

type NamedValue

type NamedValue struct {
	Name  string
	Value interface{}
}

NamedValue outputs content in the format: key: value

type Option

type Option func(*config)

Option controls output styling.

func WithErrorBoldStyle

func WithErrorBoldStyle() Option

WithErrorBoldStyle configures output using the ErrorBoldStyle

func WithErrorStyle

func WithErrorStyle() Option

WithErrorStyle configures output using the ErrorStyle

func WithIndent

func WithIndent(i int) Option

WithIndent configures output to be indented

func WithIndentChar

func WithIndentChar(char string) Option

WithIndentChar configures output with an indent character

func WithStyle

func WithStyle(style string) Option

WithStyle configures output using a style

func WithWriter

func WithWriter(w io.Writer) Option

WithWriter specifies the writer for the output.

type Step

type Step interface {
	// Success completes a step marking it as successful, and starts the next step if there are any more steps.
	Success(a ...interface{})

	// Warning completes a step marking it as a warning, and starts the next step if there are any more steps.
	Warning(a ...interface{})

	// Error completes a step marking it as an error, stops execution of an next steps.
	Error(a ...interface{})
}

type StepGroup

type StepGroup interface {
	// Add starts a step in the output with the arguments making up the initial message
	Add(string) Step
	// Done marks the StepGroup as done
	Done()
}

type UI

type UI interface {
	// Output outputs a message directly to the terminal. The remaining
	// arguments should be interpolations for the format string. After the
	// interpolations you may add Options.
	Output(msg string, opts ...Option)

	// OutputWriters returns stdout and stderr writers. These are usually
	// but not always TTYs. This is useful for subprocesses, network requests,
	// etc. Note that writing to these is not thread-safe by default so
	// you must take care that there is only ever one writer.
	OutputWriters() (stdout, stderr io.Writer, err error)

	// Header outputs a header style value to the screen
	Header(msg string, opts ...Option)

	NamedValues(rows []NamedValue, opts ...Option)

	// StepGroup returns a value that can be used to output individual steps
	// that have their own message, status indicator, spinner, and
	// body. No other output mechanism (Output, Input, Status, etc.) may be
	// called until the StepGroup is complete.
	StepGroup() StepGroup
}

UI is the primary interface for interacting with a user via the CLI.

Some of the methods on this interface return values that have a lifetime such as StepGroup. While these are still active (haven't called the Done or equivalent method on these values), no other method on the UI should be called.

func ConsoleUI

func ConsoleUI() UI

Returns a UI which will write to the current processes stdout/stderr.

func NoOpUI

func NoOpUI() UI

NoOpUI returns a no op implementation of UI

func PTermUI

func PTermUI() UI

PTermUI returns a PTerm.sh implementation of UI

type UILog

type UILog interface {
	NextHeader() map[string][]string
	NextOutput() map[string][]string
	NextStep() map[string][]string
	LastHeader() map[string][]string
	LastOutput() map[string][]string
	LastStep() map[string][]string
	Reset()
}