spinner

Spinner: A Simple Terminal Progress Indicator

Introduction

The Spinner project is a straightforward library designed to add a visual spinning indicator to terminal applications. It's particularly useful for representing progress in applications where processes might take some time to complete. The library is built to be flexible and easy to use, offering various customization features to fit different needs. It is continually updated and open for contributions from the developer community.

Installation

To install the Spinner package, users can run the following command in their terminal:

go get github.com/briandowns/spinner

Available Character Sets

Spinner provides a wide array of character sets, allowing developers to choose from 90 different animations to best suit their application's needs. Each character set offers a unique animation pattern, and a few examples include:

• Index 0: ←↖↑↗→↘↓↙
• Index 1: ▁▃▄▅▆▇█▇▆▅▄▃▁
• Index 9: \|/-\

Each character set is illustrated with a sample gif in the documentation to provide a visual representation of how they'd appear in a terminal.

Features

Spinner offers a range of features that enhance its flexibility and usability:

• Start, Stop, Restart: Control when the spinner is active.
• Direction and Speed: Reverse the direction or change the spin speed.
• Customization: Update character sets, prefix/append text, change colors and attributes like bold or italics.
• Output Management: Enable piping, redirecting, and handling final strings on completion.

Usage Examples

A typical usage scenario involves creating a spinner instance, starting it, and stopping it after a certain operation completes. Here's a basic example:

package main

import (
	"github.com/briandowns/spinner"
	"time"
)

func main() {
	s := spinner.New(spinner.CharSets[9], 100*time.Millisecond) // Initialize spinner
	s.Start()                                                    // Begin spinner
	time.Sleep(4 * time.Second)                                  // Simulate work
	s.Stop()                                                     // End spinner
}

Developers can also update the character set dynamically, adjust the spinning speed, or create entirely custom spinners using their character sets. Additionally, text can be prefixed or suffixed to the spinner, adding context to the progress indicator for the end-users.

Customization Options

• Color and Attributes: Users can set both foreground and background colors, and apply attributes like bold or underline to make the text visually distinctive.

  s.Color("red", "bold", "bgBlack") // Sets bold red text with a black background
  

• Final Output Message: After the spinner completes, a custom message can be displayed to summarize the operation.

  s.FinalMSG = "Complete! Task finished successfully.\n"
  s.Start()
  time.Sleep(4 * time.Second)
  s.Stop()
  

This message can be multi-lined and will be printed based on the configured output writer.

Conclusion

Spinner is an invaluable tool for developers needing a simple yet customizable progress indicator for command-line interfaces. By providing a wide range of features and personalization options, it ensures applications are both informative and visually engaging. Whether it’s a small personal project or a large-scale application, Spinner can enhance user experience effectively. Its ease of installation and simple API make it accessible to developers at any level of expertise.