termite

package module
v0.0.23 Latest Latest
Warning

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

 Go to latest Published: Sep 22, 2023 License: MIT Imports: 13 Imported by: 0

README

Go GitHub go.mod Go version Go Report Card Coverage Status Release Go report card Release Drafter

TERMite

Termite is my playground for terminal app utilities and visual elements such as progress bars and indicators, cursor control and screen updates.

Install

go get github.com/sha1n/termite

Examples

Spinner
refreshInterval := time.Millisecond * 100
spinner := termite.NewSpinner(termite.StdoutWriter, "Processing...", refreshInterval, termite.DefaultSpinnerFormatter())

if _, e := spinner.Start(); e == nil {
  doWork()
  
  _ = spinner.Stop("Done!")
}
Progress Bar
termWidth, _, _ := termite.GetTerminalDimensions()
progressBar := termite.NewProgressBar(termite.StdoutWriter, tickCount, width, termWidth, termite.DefaultProgressBarFormatter())

if tick, cancel, err := progressBar.Start(); err == nil {
  defer cancel()
  
  doWork(tick)
}

Showcase

The code for this demo can be found in internal/main.go (go run internal/main.go).

Documentation

Index

Constants

View Source 
const (
	// DefaultProgressBarLeftBorder default progress bar left border character
	DefaultProgressBarLeftBorder = '\u258F'

	// DefaultProgressBarRightBorder default progress bar right border character
	DefaultProgressBarRightBorder = '\u2595'

	// DefaultProgressBarFill default progress bar fill character
	DefaultProgressBarFill = '\u2587'

	// DefaultProgressBarBlank default progress bar fill character
	DefaultProgressBarBlank = '\u2591'
)
View Source 
const (
	// TermControlEraseLine clears the current line and positions the cursor at the beginning
	TermControlEraseLine = "\r\033[K"

	// TermControlClearScreen emulates the bash/sh clear command
	TermControlClearScreen = "\033[H\033[2J"

	// TermControlCRLF line feed
	TermControlCRLF = "\r\n"
)

Variables

View Source 
var (
	// Tty whether or not we have a terminal
	Tty bool
)

Functions

func AllocateNewLines added in v0.0.6 

func AllocateNewLines(count int)

AllocateNewLines utility function for starting a number of new empty lines on StdoutWriter

func DefaultSpinnerCharSeq added in v0.0.9 

func DefaultSpinnerCharSeq() []string

DefaultSpinnerCharSeq returns the default character sequence of a spinner.

func GetTerminalDimensions added in v0.0.6 

func GetTerminalDimensions() (width int, height int, err error)

GetTerminalDimensions attempts to get the current terminal dimensions If no TTY returns 0, 0 and an error

func Print added in v0.0.6 

func Print(e interface{})

Print utility function for printing an object into StdoutWritter

func Println added in v0.0.6 

func Println(e interface{})

Println utility function for printing a new line into StdoutWritter

func TruncateString added in v0.0.16 

func TruncateString(s string, maxLen int) string

TruncateString returns a string that is at most maxLen long. If s is longer than maxLen, it is trimmed to (maxLen - 2) and three dots are appended.

Types

type AutoFlushingWriter added in v0.0.6 

type AutoFlushingWriter struct {
	Writer *bufio.Writer
}

AutoFlushingWriter an implementation of an io.Writer and io.StringWriter with auto-flush semantics. 

var (
	// StdoutWriter to be used as standard out
	StdoutWriter *AutoFlushingWriter

	// StderrWriter to be used as standard err
	StderrWriter *AutoFlushingWriter

	// StdinReader to be used as standard in
	StdinReader io.Reader
)

func NewAutoFlushingWriter added in v0.0.6 

func NewAutoFlushingWriter(w io.Writer) *AutoFlushingWriter

NewAutoFlushingWriter creates a new io.Writer that uses a buffer internally and flushes after every write. This writer should be used on top of Stdout and Stderr for components that require frequent screen updates.

func (*AutoFlushingWriter) Write added in v0.0.6 

func (sw *AutoFlushingWriter) Write(b []byte) (int, error)

func (*AutoFlushingWriter) WriteString added in v0.0.6 

func (sw *AutoFlushingWriter) WriteString(s string) (int, error)

WriteString uses io.WriteString to write the specified string to the underlying writer.

type Cursor 

type Cursor interface {
	Position(row, col int)
	Up(l int)
	Down(l int)
	Forward(cols int)
	Backward(cols int)
	SavePosition()
	RestorePosition()
	Hide()
	Show()
}

Cursor represents a terminal cursor

func NewCursor 

func NewCursor(writer io.Writer) Cursor

NewCursor returns a new cursor for the specified terminal

type Matrix added in v0.0.3 

type Matrix interface {
	// Start starts to update this matrix in the background
	Start() context.CancelFunc

	// NewRow allocates and returns a MatrixRow
	NewRow() MatrixRow

	// NewRange allocates and returns the specified n umber of rows
	NewRange(int) []MatrixRow

	// RefreshInterval returns the refresh interval of this matrix
	RefreshInterval() time.Duration

	// GetRow looks up a row by index. Returns an error if none exists
	GetRow(int) (MatrixRow, error)

	// GetRowByID looks up a row an ID. Returns an error if none exists
	GetRowByID(MatrixCellID) (MatrixRow, error)

	// UpdateTerminal updates the terminal immediately.
	//
	// This function can be used as a manual alternative to Start(), which updates the terminal
	// in the background based on the interval specified in the constructor. Combining Start with
	// manual updates can yield unwanted results though.
	UpdateTerminal(resetCursorPosition bool)
}

Matrix is a multiline structure that reflects its state on screen

func NewMatrix added in v0.0.3 

func NewMatrix(writer io.Writer, refreshInterval time.Duration) Matrix

NewMatrix creates a new matrix that writes to the specified writer and refreshes every refreshInterval.

type MatrixCellID added in v0.0.5 

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

MatrixCellID used to identify a Matrix cell internally

type MatrixRow added in v0.0.5 

type MatrixRow interface {
	io.StringWriter
	io.Writer
	ID() MatrixCellID
	Update(string)
}

MatrixRow an accessor to a line in a Matrix structure Line feed and return characters are trimmed from written strings to prevent breaking the layout of the matrix.

type ProgressBar 

type ProgressBar interface {
	Tick() bool
	TickMessage(message string) bool
	IsDone() bool
	Start() (TickMessageFn, context.CancelFunc, error)
}

ProgressBar a progress bar interface

func NewDefaultProgressBar 

func NewDefaultProgressBar(writer io.Writer, maxTicks int, terminalWidthFn func() int) ProgressBar

NewDefaultProgressBar creates a progress bar with styling

func NewProgressBar 

func NewProgressBar(writer io.Writer, maxTicks int, terminalWidthFn func() int, width int, formatter ProgressBarFormatter) ProgressBar

NewProgressBar creates a new progress bar writer - the writer to use for output maxTicks - how many ticks are to be considered 100% of the progress terminalWidthFn - a funcrtion that returns the current terminal width width - bar width in characters formatter - a formatter for this progress bar

type ProgressBarFormatter added in v0.0.9 

type ProgressBarFormatter interface {
	// FormatLeftBorder returns a string that contains one visible character and optionally
	// additional styling charatcers such as color codes, background and other effects.
	FormatLeftBorder() string

	// FormatRightBorder returns a string that contains one visible character and optionally
	// additional styling charatcers such as color codes, background and other effects.
	FormatRightBorder() string

	// FormatFill returns a string that contains one visible character and optionally
	// additional styling charatcers such as color codes, background and other effects.
	FormatFill() string

	// FormatBlank returns a string that contains one visible character and optionally
	// additional styling charatcers such as color codes, background and other effects.
	FormatBlank() string

	// MessageAreaWidth return the number of character used for the message area.
	MessageAreaWidth() int
}

ProgressBarFormatter a formatter to control the style of a ProgressBar.

type SimpleProgressBarFormatter added in v0.0.9 

type SimpleProgressBarFormatter struct {
	LeftBorderChar  rune
	RightBorderChar rune
	FillChar        rune
	BlankChar       rune
	MessageWidth    int
}

SimpleProgressBarFormatter a simple ProgressBarFormatter implementation which is based on constructor values.

func DefaultProgressBarFormatter added in v0.0.9 

func DefaultProgressBarFormatter() *SimpleProgressBarFormatter

DefaultProgressBarFormatter returns a new instance of the default ProgressBarFormatter

func DefaultProgressBarFormatterWidth added in v0.0.16 

func DefaultProgressBarFormatterWidth(width int) *SimpleProgressBarFormatter

DefaultProgressBarFormatterWidth returns a default formatter with custom message area width.

func (*SimpleProgressBarFormatter) FormatBlank added in v0.0.16 

func (f *SimpleProgressBarFormatter) FormatBlank() string

FormatBlank returns the blank char

func (*SimpleProgressBarFormatter) FormatFill added in v0.0.9 

func (f *SimpleProgressBarFormatter) FormatFill() string

FormatFill returns the fill char

func (*SimpleProgressBarFormatter) FormatLeftBorder added in v0.0.9 

func (f *SimpleProgressBarFormatter) FormatLeftBorder() string

FormatLeftBorder returns the left border char

func (*SimpleProgressBarFormatter) FormatRightBorder added in v0.0.9 

func (f *SimpleProgressBarFormatter) FormatRightBorder() string

FormatRightBorder returns the right border char

func (*SimpleProgressBarFormatter) MessageAreaWidth added in v0.0.16 

func (f *SimpleProgressBarFormatter) MessageAreaWidth() int

MessageAreaWidth returns zero

type SimpleSpinnerFormatter added in v0.0.9 

type SimpleSpinnerFormatter struct{}

SimpleSpinnerFormatter a simple spinner formatter implementation that uses the default spinner character sequence and passes the title and the indicator setrings unchanged.

func (*SimpleSpinnerFormatter) CharSeq added in v0.0.9 

func (f *SimpleSpinnerFormatter) CharSeq() []string

CharSeq returns the default character sequence.

func (*SimpleSpinnerFormatter) FormatIndicator added in v0.0.9 

func (f *SimpleSpinnerFormatter) FormatIndicator(char string) string

FormatIndicator returns the input char as is

func (*SimpleSpinnerFormatter) FormatTitle added in v0.0.9 

func (f *SimpleSpinnerFormatter) FormatTitle(s string) string

FormatTitle returns the input title as is

type Spinner 

type Spinner interface {
	Start() (context.CancelFunc, error)
	Stop(string) error
	SetTitle(title string) error
}

Spinner a spinning progress indicator

func NewDefaultSpinner 

func NewDefaultSpinner() Spinner

NewDefaultSpinner creates a new Spinner that writes to Stdout with a default update interval

func NewSpinner 

func NewSpinner(writer io.Writer, title string, interval time.Duration, formatter SpinnerFormatter) Spinner

NewSpinner creates a new Spinner with the specified update interval

type SpinnerFormatter added in v0.0.9 

type SpinnerFormatter interface {
	// FormatTitle returns the input string with optional styling codes or anything else.
	FormatTitle(s string) string

	// FormatIndicator returns a string that contains one visible character - the one passed as input -
	// and optionally additional styling charatcers such as color codes, background and other effects.
	FormatIndicator(char string) string

	// CharSeq the character sequence to use as indicators.
	CharSeq() []string
}

SpinnerFormatter a formatter to be used with a Spinner to customize its style.

func DefaultSpinnerFormatter added in v0.0.9 

func DefaultSpinnerFormatter() SpinnerFormatter

DefaultSpinnerFormatter returns a default

type ThreadSafeBufferWriter added in v0.0.23 

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

func NewThreadSafeBuffer added in v0.0.23 

func NewThreadSafeBuffer() *ThreadSafeBufferWriter

func (*ThreadSafeBufferWriter) Len added in v0.0.23 

func (b *ThreadSafeBufferWriter) Len() int

func (*ThreadSafeBufferWriter) Reset added in v0.0.23 

func (b *ThreadSafeBufferWriter) Reset()

func (*ThreadSafeBufferWriter) String added in v0.0.23 

func (b *ThreadSafeBufferWriter) String() string

func (*ThreadSafeBufferWriter) Write added in v0.0.23 

func (b *ThreadSafeBufferWriter) Write(p []byte) (n int, err error)

type TickMessageFn added in v0.0.16 

type TickMessageFn = func(string) bool

TickMessageFn a tick handle

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.