ysmrr

README

You spin me right round

You Spin Me Right Round (ysmrr) is a package that provides simple multi-line compatible spinners for Go applications.

Installing

go get -u github.com/chelnak/ysmrr

Usage

SpinnerManager

A SpinnerManager is a collection of spinners that share a common configuration.

They can be created as follows:

sm := ysmrr.NewSpinnerManager()

The NewSpinnerManager method also accepts multiple options. For example, you can change the animation and the color of the spinner:

sm := ysmrr.NewSpinnerManager(
    ysmrr.WithAnimation(animations.Pipe),
    ysmrr.WithSpinnerColor(colors.FgHiBlue),
)

A SpinnerManager is also responsible for starting and stopping a group of spinners.

Starting a spinner group

sm.Start()

Stopping a spinner group

sm.Stop()

Running Stop() on a stopped spinner group is a noop operation.

Checking if a spinner group is running

sm := ysmrr.NewSpinnerManager()
sm.Start()
isRunning := sm.Running() // true
sm.Stop()
isRunning = sm.Running() // false

Spinners

SpinnerManagers are great but pretty useless on their own. You need to add at least one spinner.

Adding a new spinner is as simple as using the AddSpinner method on a SpinnerManager instance.

It expects a string that will be displayed as the initial message of a spinner.

spinner := sm.AddSpinner("Downloading...")

AddSpinner will return a spinner instance that you can use to control the spinner.

Updating the message

Thoughout the lifecycle of a spinner, you can update the message of the spinner.

spinner.UpdateMessage("Downloading...")

Spinner state

A spinner can be set to either Complete or Error to indicate the current state of a task.

spinner.Complete()

spinner.Error()

Example

To tie everything together, here is an example that shows how to build a basic spinner app.

// Create a new spinner manager
sm := ysmrr.NewSpinnerManager()

// Add a spinner
mySpinner := sm.AddSpinner("Spinny things...")

// Start the spinners that have been added to the group
sm.Start()

// Set the spinner to complete
time.Sleep(2 * time.Second)
mySpinner.Complete()

// Stop the spinners in the group
time.Sleep(2 * time.Second)
sm.Stop()

For more usage examples, check out the examples directory.

Inspiration

Ysmrr was inspired by the following projects:

• github.com/briandowns/spinner
• github.com/theckman/yacspin

It also uses github.com/fatih/color for the underlying color system and github.com/mattn/go-colorable for Windows support.

Documentation

Overview

Package ysmrr provides a simple interface for creating and managing multiple spinners.

Index

• func WithAnimation(a animations.Animation) managerOption
• func WithCompleteColor(c colors.Color) managerOption
• func WithErrorColor(c colors.Color) managerOption
• func WithFrameDuration(d time.Duration) managerOption
• func WithMessageColor(c colors.Color) managerOption
• func WithSpinnerColor(c colors.Color) managerOption
• func WithWriter(w io.Writer) managerOption
• type Spinner
  • func NewSpinner(options SpinnerOptions) *Spinner
  • func (s *Spinner) Complete()
  • func (s *Spinner) CompleteWithMessage(message string)
  • func (s *Spinner) CompleteWithMessagef(format string, a ...interface{})
  • func (s *Spinner) Error()
  • func (s *Spinner) ErrorWithMessage(message string)
  • func (s *Spinner) ErrorWithMessagef(format string, a ...interface{})
  • func (s *Spinner) GetMessage() string
  • func (s *Spinner) GetPrefix() string
  • func (s *Spinner) IsComplete() bool
  • func (s *Spinner) IsError() bool
  • func (s *Spinner) Print(w io.Writer, char string)
  • func (s *Spinner) UpdateMessage(message string)
  • func (s *Spinner) UpdateMessagef(format string, a ...interface{})
  • func (s *Spinner) UpdatePrefix(Prefix string)
  • func (s *Spinner) UpdatePrefixf(format string, a ...interface{})
• type SpinnerManager
  • func NewSpinnerManager(options ...managerOption) SpinnerManager
• type SpinnerOptions

Functions

func WithAnimation

func WithAnimation(a animations.Animation) managerOption

WithAnimation sets the animation used for the spinners. Available spinner types can be found in the package github.com/chelnak/ysmrr/pkg/animations. The default spinner animation is the Dots.

func WithCompleteColor

func WithCompleteColor(c colors.Color) managerOption

WithCompleteColor sets the color of the complete icon. Available colors can be found in the package github.com/chelnak/ysmrr/pkg/colors. The default color is FgHiGreen.

func WithErrorColor

func WithErrorColor(c colors.Color) managerOption

WithErrorColor sets the color of the error icon. Available colors can be found in the package github.com/chelnak/ysmrr/pkg/colors. The default color is FgHiRed.

func WithFrameDuration

func WithFrameDuration(d time.Duration) managerOption

WithFrameDuration sets the duration of each frame. The default duration is 250 milliseconds.

func WithMessageColor

func WithMessageColor(c colors.Color) managerOption

WithMessageColor sets the color of the message. Available colors can be found in the package github.com/chelnak/ysmrr/pkg/colors. The default color is NoColor.

func WithSpinnerColor

func WithSpinnerColor(c colors.Color) managerOption

WithSpinnerColor sets the color of the spinners. Available colors can be found in the package github.com/chelnak/ysmrr/pkg/colors. The default color is FgHiGreen.

func WithWriter

func WithWriter(w io.Writer) managerOption

WithWriter sets the writer used for the spinners. The writer can be anything that implements the io.Writer interface. The default writer is os.Stdout.

Types

type Spinner

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

Spinner manages a single spinner

func NewSpinner

func NewSpinner(options SpinnerOptions) *Spinner

NewSpinner creates a new spinner instance.

func (*Spinner) Complete

func (s *Spinner) Complete()

Complete marks the spinner as complete.

func (*Spinner) CompleteWithMessage

func (s *Spinner) CompleteWithMessage(message string)

CompleteWithMessage marks the spinner as complete with a message.

func (*Spinner) CompleteWithMessagef

func (s *Spinner) CompleteWithMessagef(format string, a ...interface{})

CompleteWithMessagef marks the spinner as complete with a formatted string.

func (*Spinner) Error

func (s *Spinner) Error()

Error marks the spinner as error.

func (*Spinner) ErrorWithMessage

func (s *Spinner) ErrorWithMessage(message string)

ErrorWithMessage marks the spinner as error with a message.

func (*Spinner) ErrorWithMessagef

func (s *Spinner) ErrorWithMessagef(format string, a ...interface{})

ErrorWithMessagef marks the spinner as error with a formatted string.

func (*Spinner) GetMessage

func (s *Spinner) GetMessage() string

GetMessage returns the current spinner message.

func (*Spinner) GetPrefix

func (s *Spinner) GetPrefix() string

GetPrefix returns the current spinner Prefix.

func (*Spinner) IsComplete

func (s *Spinner) IsComplete() bool

IsComplete returns true if the spinner is complete.

func (*Spinner) IsError

func (s *Spinner) IsError() bool

IsError returns true if the spinner is in error state.

func (*Spinner) Print

func (s *Spinner) Print(w io.Writer, char string)

Print prints the spinner at a given position.

func (*Spinner) UpdateMessage

func (s *Spinner) UpdateMessage(message string)

UpdateMessage updates the spinner message.

func (*Spinner) UpdateMessagef

func (s *Spinner) UpdateMessagef(format string, a ...interface{})

UpdateMessagef updates the spinner message with a formatted string.

func (*Spinner) UpdatePrefix

func (s *Spinner) UpdatePrefix(Prefix string)

UpdatePrefix updates the spinner Prefix.

func (*Spinner) UpdatePrefixf

func (s *Spinner) UpdatePrefixf(format string, a ...interface{})

UpdatePrefixf updates the spinner Prefix with a formatted string.

type SpinnerManager

type SpinnerManager interface {
	AddSpinner(msg string) *Spinner
	GetSpinners() []*Spinner
	GetWriter() io.Writer
	GetAnimation() []string
	GetFrameDuration() time.Duration
	GetSpinnerColor() colors.Color
	GetErrorColor() colors.Color
	GetCompleteColor() colors.Color
	GetMessageColor() colors.Color
	Start()
	Stop()
	Running() bool
}

SpinnerManager manages spinners

func NewSpinnerManager

func NewSpinnerManager(options ...managerOption) SpinnerManager

NewSpinnerManager is the constructor for the SpinnerManager. You can create a new manager with sensible defaults or you can pass in your own options using the provided methods.

For example, this will initialize a default manager:

sm := NewSpinnerManager()

Or this will initialize a manager with a custom animation:

sm := NewSpinnerManager(
	WithAnimation(animations.Arrows)
)

You can pass in multiple options to the constructor:

sm := NewSpinnerManager(
	WithAnimation(animations.Arrows),
	WithFrameDuration(time.Millisecond * 100),
	WithSpinnerColor(colors.Red),
)

type SpinnerOptions

type SpinnerOptions struct {
	SpinnerColor  colors.Color
	CompleteColor colors.Color
	ErrorColor    colors.Color
	MessageColor  colors.Color
	Message       string
	HasUpdate     chan bool
}