spinner

Documentation

Overview

Package spinner provides a spinner that can be used to display progress to a user in a command line application.

Index

• func NewTracker(opts TrackerOptions) progress.Tracker
• type Option
  • func WithCount(c int) Option
  • func WithInterval(d time.Duration) Option
  • func WithMaxMessageLength(l int) Option
  • func WithPersistMessages(b bool) Option
  • func WithStartMessage(m string) Option
  • func WithStopMessage(m string) Option
  • func WithWriter(w io.Writer) Option
• type Spinner
  • func New(opts ...Option) *Spinner
  • func (s *Spinner) Inc()
  • func (s *Spinner) IncWithMessage(m string)
  • func (s *Spinner) IncWithMessagef(format string, args ...any)
  • func (s *Spinner) Start()
  • func (s *Spinner) Stop()
  • func (s *Spinner) UpdateMessage(m string)
  • func (s *Spinner) Write(p []byte) (int, error)
• type TrackerOptions

Functions

func NewTracker

func NewTracker(opts TrackerOptions) progress.Tracker

NewTracker creates a progress.Tracker that uses a Spinner to display progress.

Types

type Option

type Option func(*Spinner)

Option is a function that takes a spinner and applies a configuration to it.

func WithCount

func WithCount(c int) Option

WithCount sets the total number of items to track the progress of.

func WithInterval

func WithInterval(d time.Duration) Option

WithInterval sets how often the spinner updates. This controls the speed of the spinner. By default the interval is 100ms.

func WithMaxMessageLength

func WithMaxMessageLength(l int) Option

WithMaxMessageLength sets the maximum length of the message that is written by the spinner. If the message is longer then this length it will be truncated. The default max length is 80.

func WithPersistMessages

func WithPersistMessages(b bool) Option

WithPersistMessages sets whether or not messages should be persisted to the writter when the message is updated. By default messages are not persisted and are replaced.

func WithStartMessage

func WithStartMessage(m string) Option

WithStartMessage sets a string that should be written after the spinner when the spinnner is started.

func WithStopMessage

func WithStopMessage(m string) Option

WithStopMessage sets a string that should be written when the spinner is stopped. This message will replace the spinner.

func WithWriter

func WithWriter(w io.Writer) Option

WithWriter sets the writer that should be used for writing the spinner to.

type Spinner

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

Spinner represents the state of the spinner. A spinner can be created using the spinner.New function.

Spinner can keep track of and display progress through a list of items that need to be completed.

It is safe to use a Spinner across multiple goroutines. The spinner will ensure only one goroutine at a time can modify it.

The Spinner runs on a separate goroutine so that blocking operations can be run on the current goroutine and the Spinner will continue displaying progress.

Spinner implements the io.Writer interface. It can be written to in order to print messages while the spinner is running. It is not recommended to write directly to the writer the spinner is writing to (by default stderr), as it can cause issues with the spinner animation. Writing to the spinner directly provides a way to get around this limitation, as the spinner will ensure that the text will be written properly without interfering with the animation.

func New

func New(opts ...Option) *Spinner

New creates a new spinner instance using the given options.

func (*Spinner) Inc

func (s *Spinner) Inc()

Inc increments the progress of the spinner. If the spinner has already reached full progress, Inc does nothing.

func (*Spinner) IncWithMessage

func (s *Spinner) IncWithMessage(m string)

IncWithMessage increments the progress of the spinner and updates the spinner message to m. If the spinner has already reached full progress, IncWithMessage does nothing.

func (*Spinner) IncWithMessagef

func (s *Spinner) IncWithMessagef(format string, args ...any)

IncWithMessagef increments the progress of the spinner and updates the spinner message to the format specifier. If the spinner has already reached full progress, IncWithMessagef does nothing.

func (*Spinner) Start

func (s *Spinner) Start()

Start starts the spinner. If the spinner is already running, Start does nothing.

func (*Spinner) Stop

func (s *Spinner) Stop()

Stop stops the spinner if it is currently running. If the spinner is not running, Stop does nothing.

func (*Spinner) UpdateMessage

func (s *Spinner) UpdateMessage(m string)

UpdateMessage changes the current message being shown by the spinner.

func (*Spinner) Write

func (s *Spinner) Write(p []byte) (int, error)

Write writes p to the spinner's writer after the current frame has been erased. Write will always immediately return successfully as p is first written to an internal buffer. The actual writing of the data to the spinner's writer will not occur until the appropriate time during the spinner animation.

Write will add a newline to the end of p in order to ensure that it does not interfere with the spinner animation.

type TrackerOptions

type TrackerOptions struct {
	// Writer is where logs and spinner output is written.
	// If nil it defaults to os.Stderr.
	Writer io.Writer
	// Interval is how often the spinner updates. See spinner.WithInterval.
	Interval time.Duration
	// MaxMessageLength is the max length a message can be. See spinner.WithMaxMessageLength.
	MaxMessageLength int
	// PersistMessages controls whether or not messages are persisted by the spinner.
	// See spinner.WithPersistMessages.
	PersistMessages bool
	// NewHandler is a function that creates a new slog.Handler to use for logging.
	// If nil a slog.TextHandler will be created with default options.
	NewHandler func(w io.Writer) slog.Handler
	// DisableSpinner disables usage of a spinner and simply logs spinner messages.
	// This is useful if you wish to dynamically control spinner behaviour based on
	// an environment variable or command line flag.
	DisableSpinner bool
}

TrackerOptions allows for customizing a Tracker created with NewTracker. See each field for more details.