README
¶
Yet Another CLi Spinner (for Go)
Package yacspin provides yet another CLi spinner for Go, taking inspiration
(and some utility code) from the https://github.com/briandowns/spinner project.
Specifically yacspin borrows the default character sets, and color mappings to
github.com/fatih/color colors, from that project.
License
Because this package adopts the spinner character sets from https://github.com/briandowns/spinner, this package is released under the Apache 2.0 License.
Yet Another CLi Spinner?
The other Go spinner ties the ability to show updated information to the spinner's animation, meaning you can't always show all the information you want to the end user without changing the animation speed. In addition there were also some API design choices that have made it unsafe for concurrent use (while it's running), which presents challenges when trying to update the text in the spinner while it's animating in the first place
There was also an interest in the spinner being able to represent a task, and to indicate whether it failed or was successful. This would have further compounded the API issues mentioned above.
This project takes inspiration from that other project, and takes a new approach to address the challenges above.
Features
Provided Spinners
There are over 30 spinners available in the CharSets package variable. They
were borrowed from github.com/briandowns/spinner.
There is a table with all of the spinners at the bottom of this README.
Dynamic Width of Animation
Because of how some spinners are animated, they may have different widths are different times in the animation. The spinner calculates the maximum width, and pads the animation to ensure the text's position on the screen doesn't change. This results in a smoother looking animation.
Success and Failure Results
The spinner has both a Stop() and StopFail() method, which allows the
spinner to result in a success message or a failure message. The messages,
colors, and even the character used to denote success or failure are
customizable in either the initial config or via the methods.
By doing this you can use the spinner to display the satus of a list of tasks being executed serially.
Concurrency
The spinner is safe for concurrent use, so you can update any of its settings via methods whether the spinner is stopped or is currently running.
Live Updates
Most spinners tie the ability to show new messages with the animation of the spinner. So if the spinner animates every 200ms, you can only show updated information every 200ms. If you wanted more frequent updates, you'd need to tradeoff the asthetics of the animation to display more data.
This spinner updates the printed information of the spinner immediately on change, without the animation updating. This allows you to use an animation speed that looks astheticaly pleasing, while also knowing the data presented to the user will be updated live.
You can see this in action in the following gif, where the filenames being uploaded are rendered independent of the spinner being animated:
Pausing for Updates
Sometimes you want to change a few settings, and don't want the spinner to
render your partially applied configuration. If your spinner is running, and you
want to change a few configuration items via method calls, you can Pause() the
spinner first. After making the changes you can call Unpause(), and it will
continue rendering like normal with the newly applied configuration.
Usage
go get github.com/theckman/yacspin
Within the yacspin package there are some default spinners stored in the
yacspin.CharSets variable, and you can also provide your own. There is also a
list of known colors in the yacspin.ValidColors variable.
cfg := yacspin.Config{
Frequency: 100 * time.Millisecond,
CharSet: yacspin.CharSets[59],
Suffix: " backing up database to S3",
SuffixAutoColon: true,
Message: "exporting data",
StopCharacter: "✓",
StopColors: []string{"fgGreen"},
}
spinner, err := yacspin.New(cfg)
// handle the error
spinner.Start()
// doing some work
time.Sleep(2 * time.Second)
spinner.Message("uploading data")
// upload...
time.Sleep(2 * time.Second)
spinner.Stop()
Spinners
| yacspin.CharSets index | sample gif |
|---|---|
| 0 |  |
| 1 |  |
| 2 |  |
| 3 |  |
| 4 |  |
| 5 |  |
| 6 |  |
| 7 |  |
| 8 |  |
| 9 |  |
| 10 |  |
| 11 |  |
| 12 |  |
| 13 |  |
| 14 |  |
| 15 |  |
| 16 |  |
| 17 |  |
| 18 |  |
| 19 |  |
| 20 |  |
| 21 |  |
| 22 |  |
| 23 |  |
| 24 |  |
| 25 |  |
| 26 |  |
| 27 |  |
| 28 |  |
| 29 |  |
| 30 |  |
| 31 |  |
| 32 |  |
| 33 |  |
| 34 |  |
| 35 |  |
| 36 |  |
| 37 |  |
| 38 |  |
| 39 |  |
| 40 |  |
| 41 |  |
| 42 |  |
| 43 |  |
| 44 |  |
| 45 |  |
| 46 |  |
| 47 |  |
| 48 |  |
| 49 |  |
| 50 |  |
| 51 |  |
| 52 |  |
| 53 |  |
| 54 |  |
| 55 |  |
| 56 |  |
| 57 |  |
| 58 |  |
| 59 |  |
| 60 |  |
| 61 |  |
| 62 |  |
| 63 |  |
| 64 |  |
| 65 |  |
| 66 |  |
| 67 |  |
| 68 |  |
| 69 |  |
| 70 |  |
| 71 |  |
| 72 |  |
| 73 |  |
| 74 |  |
| 75 |  |
| 76 |  |
| 77 |  |
Documentation
¶
Overview ¶
Package yacspin provides Yet Another CLi Spinner for Go, taking inspiration (and some utility code) from the https://github.com/briandowns/spinner project. Specifically this project borrows the default character sets, and color mappings to github.com/fatih/color colors, from that project.
This also supports an alternate mode of operation for Winodws OS and dumb terminals. This is discovered automatically when creating the spinner.
Within the yacspin package there are some default spinners stored in the yacspin.CharSets variable, but you can also provide your own. There is also a list of known colors in the yacspin.ValidColors variable.
cfg := yacspin.Config{
Frequency: 100 * time.Millisecond,
CharSet: yacspin.CharSets[59],
Suffix: " backing up database to S3",
Message: "exporting data",
StopCharacter: "✓",
StopColors: []string{"fgGreen"},
}
spinner, err := yacspin.New(cfg)
// handle the error
spinner.Start()
// doing some work
time.Sleep(2 * time.Second)
spinner.Message("uploading data")
// upload...
time.Sleep(2 * time.Second)
spinner.Stop()
Index ¶
- Variables
- type Config
- type Spinner
- func (s *Spinner) Active() bool
- func (s *Spinner) CharSet(cs []string) error
- func (s *Spinner) Colors(colors ...string) error
- func (s *Spinner) Delay(d time.Duration) error
- func (s *Spinner) Frequency(d time.Duration) error
- func (s *Spinner) Message(message string)
- func (s *Spinner) Pause() error
- func (s *Spinner) Prefix(prefix string)
- func (s *Spinner) Reverse()
- func (s *Spinner) Start() error
- func (s *Spinner) Status() SpinnerStatus
- func (s *Spinner) Stop() error
- func (s *Spinner) StopCharacter(char string)
- func (s *Spinner) StopColors(colors ...string) error
- func (s *Spinner) StopFail() error
- func (s *Spinner) StopFailCharacter(char string)
- func (s *Spinner) StopFailColors(colors ...string) error
- func (s *Spinner) StopFailMessage(message string)
- func (s *Spinner) StopMessage(message string)
- func (s *Spinner) Suffix(suffix string)
- func (s *Spinner) Unpause() error
- type SpinnerStatus
Constants ¶
This section is empty.
Variables ¶
var CharSets = map[int][]string{
0: {"←", "↖", "↑", "↗", "→", "↘", "↓", "↙"},
1: {"▁", "▃", "▄", "▅", "▆", "▇", "█", "▇", "▆", "▅", "▄", "▃", "▁"},
2: {"▖", "▘", "▝", "▗"},
3: {"┤", "┘", "┴", "└", "├", "┌", "┬", "┐"},
4: {"◢", "◣", "◤", "◥"},
5: {"◰", "◳", "◲", "◱"},
6: {"◴", "◷", "◶", "◵"},
7: {"◐", "◓", "◑", "◒"},
8: {".", "o", "O", "@", "*"},
9: {"|", "/", "-", "\\"},
10: {"◡◡", "⊙⊙", "◠◠"},
11: {"⣾", "⣽", "⣻", "⢿", "⡿", "⣟", "⣯", "⣷"},
12: {">))'>", " >))'>", " >))'>", " >))'>", " >))'>", " <'((<", " <'((<", " <'((<"},
13: {"⠁", "⠂", "⠄", "⡀", "⢀", "⠠", "⠐", "⠈"},
14: {"⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"},
15: {"a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z"},
16: {"▉", "▊", "▋", "▌", "▍", "▎", "▏", "▎", "▍", "▌", "▋", "▊", "▉"},
17: {"■", "□", "▪", "▫"},
18: {"←", "↑", "→", "↓"},
19: {"╫", "╪"},
20: {"⇐", "⇖", "⇑", "⇗", "⇒", "⇘", "⇓", "⇙"},
21: {"⠁", "⠁", "⠉", "⠙", "⠚", "⠒", "⠂", "⠂", "⠒", "⠲", "⠴", "⠤", "⠄", "⠄", "⠤", "⠠", "⠠", "⠤", "⠦", "⠖", "⠒", "⠐", "⠐", "⠒", "⠓", "⠋", "⠉", "⠈", "⠈"},
22: {"⠈", "⠉", "⠋", "⠓", "⠒", "⠐", "⠐", "⠒", "⠖", "⠦", "⠤", "⠠", "⠠", "⠤", "⠦", "⠖", "⠒", "⠐", "⠐", "⠒", "⠓", "⠋", "⠉", "⠈"},
23: {"⠁", "⠉", "⠙", "⠚", "⠒", "⠂", "⠂", "⠒", "⠲", "⠴", "⠤", "⠄", "⠄", "⠤", "⠴", "⠲", "⠒", "⠂", "⠂", "⠒", "⠚", "⠙", "⠉", "⠁"},
24: {"⠋", "⠙", "⠚", "⠒", "⠂", "⠂", "⠒", "⠲", "⠴", "⠦", "⠖", "⠒", "⠐", "⠐", "⠒", "⠓", "⠋"},
25: {"ｦ", "ｧ", "ｨ", "ｩ", "ｪ", "ｫ", "ｬ", "ｭ", "ｮ", "ｯ", "ｱ", "ｲ", "ｳ", "ｴ", "ｵ", "ｶ", "ｷ", "ｸ", "ｹ", "ｺ", "ｻ", "ｼ", "ｽ", "ｾ", "ｿ", "ﾀ", "ﾁ", "ﾂ", "ﾃ", "ﾄ", "ﾅ", "ﾆ", "ﾇ", "ﾈ", "ﾉ", "ﾊ", "ﾋ", "ﾌ", "ﾍ", "ﾎ", "ﾏ", "ﾐ", "ﾑ", "ﾒ", "ﾓ", "ﾔ", "ﾕ", "ﾖ", "ﾗ", "ﾘ", "ﾙ", "ﾚ", "ﾛ", "ﾜ", "ﾝ"},
26: {".", "..", "..."},
27: {"▁", "▂", "▃", "▄", "▅", "▆", "▇", "█", "▉", "▊", "▋", "▌", "▍", "▎", "▏", "▏", "▎", "▍", "▌", "▋", "▊", "▉", "█", "▇", "▆", "▅", "▄", "▃", "▂", "▁"},
28: {".", "o", "O", "°", "O", "o", "."},
29: {"+", "x"},
30: {"v", "<", "^", ">"},
31: {">>--->", " >>--->", " >>--->", " >>--->", " >>--->", " <---<<", " <---<<", " <---<<", " <---<<", "<---<<"},
32: {"|", "||", "|||", "||||", "|||||", "||||||", "|||||||", "||||||||", "|||||||", "||||||", "|||||", "||||", "|||", "||", "|"},
33: {"[ ]", "[= ]", "[== ]", "[=== ]", "[==== ]", "[===== ]", "[====== ]", "[======= ]", "[======== ]", "[========= ]", "[==========]"},
34: {"(*---------)", "(-*--------)", "(--*-------)", "(---*------)", "(----*-----)", "(-----*----)", "(------*---)", "(-------*--)", "(--------*-)", "(---------*)"},
35: {"█▒▒▒▒▒▒▒▒▒", "███▒▒▒▒▒▒▒", "█████▒▒▒▒▒", "███████▒▒▒", "██████████"},
36: {"[ ]", "[=> ]", "[===> ]", "[=====> ]", "[======> ]", "[========> ]", "[==========> ]", "[============> ]", "[==============> ]", "[================> ]", "[==================> ]", "[===================>]"},
37: {"🕐", "🕑", "🕒", "🕓", "🕔", "🕕", "🕖", "🕗", "🕘", "🕙", "🕚", "🕛"},
38: {"🕐", "🕜", "🕑", "🕝", "🕒", "🕞", "🕓", "🕟", "🕔", "🕠", "🕕", "🕡", "🕖", "🕢", "🕗", "🕣", "🕘", "🕤", "🕙", "🕥", "🕚", "🕦", "🕛", "🕧"},
39: {"🌍", "🌎", "🌏"},
40: {"◜", "◝", "◞", "◟"},
41: {"⬒", "⬔", "⬓", "⬕"},
42: {"⬖", "⬘", "⬗", "⬙"},
43: {"[>>> >]", "[]>>>> []", "[] >>>> []", "[] >>>> []", "[] >>>> []", "[] >>>>[]", "[>> >>]"},
44: {"♠", "♣", "♥", "♦"},
45: {"➞", "➟", "➠", "➡", "➠", "➟"},
46: {" | ", ` \ `, "_ ", ` \ `, " | ", " / ", " _", " / "},
47: {" . . . .", ". . . .", ". . . .", ". . . .", ". . . . ", ". . . . ."},
48: {" | ", " / ", " _ ", ` \ `, " | ", ` \ `, " _ ", " / "},
49: {"⎺", "⎻", "⎼", "⎽", "⎼", "⎻"},
50: {"▹▹▹▹▹", "▸▹▹▹▹", "▹▸▹▹▹", "▹▹▸▹▹", "▹▹▹▸▹", "▹▹▹▹▸"},
51: {"[ ]", "[ =]", "[ ==]", "[ ===]", "[====]", "[=== ]", "[== ]", "[= ]"},
52: {"( ● )", "( ● )", "( ● )", "( ● )", "( ●)", "( ● )", "( ● )", "( ● )", "( ● )"},
53: {"✶", "✸", "✹", "✺", "✹", "✷"},
54: {"▐|\\____________▌", "▐_|\\___________▌", "▐__|\\__________▌", "▐___|\\_________▌", "▐____|\\________▌", "▐_____|\\_______▌", "▐______|\\______▌", "▐_______|\\_____▌", "▐________|\\____▌", "▐_________|\\___▌", "▐__________|\\__▌", "▐___________|\\_▌", "▐____________|\\▌", "▐____________/|▌", "▐___________/|_▌", "▐__________/|__▌", "▐_________/|___▌", "▐________/|____▌", "▐_______/|_____▌", "▐______/|______▌", "▐_____/|_______▌", "▐____/|________▌", "▐___/|_________▌", "▐__/|__________▌", "▐_/|___________▌", "▐/|____________▌"},
55: {"▐⠂ ▌", "▐⠈ ▌", "▐ ⠂ ▌", "▐ ⠠ ▌", "▐ ⡀ ▌", "▐ ⠠ ▌", "▐ ⠂ ▌", "▐ ⠈ ▌", "▐ ⠂ ▌", "▐ ⠠ ▌", "▐ ⡀ ▌", "▐ ⠠ ▌", "▐ ⠂ ▌", "▐ ⠈ ▌", "▐ ⠂▌", "▐ ⠠▌", "▐ ⡀▌", "▐ ⠠ ▌", "▐ ⠂ ▌", "▐ ⠈ ▌", "▐ ⠂ ▌", "▐ ⠠ ▌", "▐ ⡀ ▌", "▐ ⠠ ▌", "▐ ⠂ ▌", "▐ ⠈ ▌", "▐ ⠂ ▌", "▐ ⠠ ▌", "▐ ⡀ ▌", "▐⠠ ▌"},
56: {"¿", "?"},
57: {"⢹", "⢺", "⢼", "⣸", "⣇", "⡧", "⡗", "⡏"},
58: {"⢄", "⢂", "⢁", "⡁", "⡈", "⡐", "⡠"},
59: {". ", ".. ", "...", " ..", " .", " "},
60: {".", "o", "O", "°", "O", "o", "."},
61: {"▓", "▒", "░"},
62: {"▌", "▀", "▐", "▄"},
63: {"⊶", "⊷"},
64: {"▪", "▫"},
65: {"□", "■"},
66: {"▮", "▯"},
67: {"-", "=", "≡"},
68: {"d", "q", "p", "b"},
69: {"∙∙∙", "●∙∙", "∙●∙", "∙∙●", "∙∙∙"},
70: {"🌑 ", "🌒 ", "🌓 ", "🌔 ", "🌕 ", "🌖 ", "🌗 ", "🌘 "},
71: {"☗", "☖"},
72: {"⧇", "⧆"},
73: {"◉", "◎"},
74: {"㊂", "㊀", "㊁"},
75: {"⦾", "⦿"},
76: {"ဝ", "၀"},
77: {"▌", "▀", "▐▄"},
}
CharSets contains the default character sets from https://github.com/briandowns/spinner.
var ValidColors = map[string]struct{}{
"black": {},
"red": {},
"green": {},
"yellow": {},
"blue": {},
"magenta": {},
"cyan": {},
"white": {},
"reset": {},
"bold": {},
"faint": {},
"italic": {},
"underline": {},
"blinkslow": {},
"blinkrapid": {},
"reversevideo": {},
"concealed": {},
"crossedout": {},
"fgBlack": {},
"fgRed": {},
"fgGreen": {},
"fgYellow": {},
"fgBlue": {},
"fgMagenta": {},
"fgCyan": {},
"fgWhite": {},
"fgHiBlack": {},
"fgHiRed": {},
"fgHiGreen": {},
"fgHiYellow": {},
"fgHiBlue": {},
"fgHiMagenta": {},
"fgHiCyan": {},
"fgHiWhite": {},
"bgBlack": {},
"bgRed": {},
"bgGreen": {},
"bgYellow": {},
"bgBlue": {},
"bgMagenta": {},
"bgCyan": {},
"bgWhite": {},
"bgHiBlack": {},
"bgHiRed": {},
"bgHiGreen": {},
"bgHiYellow": {},
"bgHiBlue": {},
"bgHiMagenta": {},
"bgHiCyan": {},
"bgHiWhite": {},
}
ValidColors holds the list of the strings that are mapped to github.com/fatih/color color attributes. Any of these colors / attributes can be used with the *Spinner type.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Frequency specifies how often to animate the spinner. Optimal value
// depends on the character set you use.
//
// Note: This is a required value (cannot be 0)
Frequency time.Duration
// Delay is deprecated by the Frequency configuration field, with Frequency
// taking precedent if both are present.
Delay time.Duration
// Writer is the place where we are outputting the spinner, and can't be
// changed on the fly. If omitted, this defaults to os.Stdout.
Writer io.Writer
// HideCursor describes whether the cursor should be hidden by the spinner.
// If it is hidden, it will be restored when the spinner stops. This can't
// be changed on the fly.
HideCursor bool
// ColorAll describes whether to color everything (all) or just the spinner
// character(s). This cannot be changed.
ColorAll bool
// Colors are the colors used for the different printed messages. This
// respects the ColorAll field.
Colors []string
// CharSet is the list of characters to iterate through to draw the spinner.
CharSet []string
// Prefix is the string printed immediately before the spinner.
Prefix string
// Suffix is the string printed immediately after the spinner. It's
// recommended that this string starts with an space ` ` character.
Suffix string
// SuffixAutoColon configures whether the spinner adds a colon after the
// suffix automatically. If there is a message, a colon followed by a space
// is added to the suffix. Otherwise, if there is no message the colon is
// omitted.
SuffixAutoColon bool
// Message is the string printed after the suffix. If a suffix is present,
// `: ` is appended to the suffix before printing the message. It results in
// a message like:
//
// <prefix><spinner><suffix>: <message>
Message string
// StopMessage is the message used when Stop() is called.
StopMessage string
// StopCharacter is spinner character used when Stop() is called.
// Recommended character is ✓.
StopCharacter string
// StopColors are the colors used for the Stop() printed line. This respects
// the ColorAll field.
StopColors []string
// StopFailMessage is the message used when StopFail() is called.
StopFailMessage string
// StopFailCharacter is the spinner character used when StopFail() is called.
// Recommended character is ✗.
StopFailCharacter string
// StopFailColors are the colors used for the StopFail() printed line. This
// respects the ColorAll field.
StopFailColors []string
}
Config is the configuration structure for the Spinner.
type Spinner ¶
type Spinner struct {
// contains filtered or unexported fields
}
Spinner is the struct type representing a spinner. It's configured via the Config type, and controlled via its methods. Some configuration can also be updated via methods.
Note: You need to use New() to construct a *Spinner.
func (*Spinner) Active ¶
Active is deprecated and will be removed in a future release. It was replaced by the Status() method.
Active returns whether the spinner is active. Active means the spinner is either starting or running.
func (*Spinner) CharSet ¶
CharSet updates the set of characters (strings) to use for the spinner. You can provide your own, or use one from the CharSets variable.
The character sets available in the CharSets variable are from the https://github.com/briandowns/spinner project.
func (*Spinner) Colors ¶
Colors updates the github.com/fatih/colors for printing the spinner line. ColorAll config parameter controls whether only the spinner character is printed with these colors, or the whole line.
StopColors() is the method to control the colors in the stop message.
func (*Spinner) Frequency ¶ added in v0.8.0
Frequency updates the frequency of the spinner being animated.
func (*Spinner) Pause ¶ added in v0.8.0
Pause puts the spinner in a state where it no longer animates or renders updates to data. This function blocks until the spinner's internal goroutine enters a paused state.
If you want to make a few configuration changes and have them to appear at the same time, like changing the suffix, message, and color, you can Pause() the spinner first and then Unpause() after making the changes.
If the spinner is not running (stopped, paused, or in transition to another state) this returns an error.
func (*Spinner) Reverse ¶
func (s *Spinner) Reverse()
Reverse flips the character set order of the spinner characters.
func (*Spinner) Start ¶
Start begins the spinner on the Writer in the Config provided to New(). Onnly possible error is if the spinner is already runninng.
func (*Spinner) Status ¶ added in v0.8.0
func (s *Spinner) Status() SpinnerStatus
Status returns the current status of the internal state machine. Returned value is of type SpinnerStatus which has package constants available.
func (*Spinner) Stop ¶
Stop disables the spinner, and prints the StopCharacter with the StopMessage using the StopColors. This blocks until the stopped message is printed. Only possible error is if the spinner is not running.
func (*Spinner) StopCharacter ¶
StopCharacter sets the single "character" to use for the spinner. Recommended character is ✓.
func (*Spinner) StopColors ¶
StopColors updates the colors used for the stop message. See Colors() method documentation for more context.
func (*Spinner) StopFail ¶ added in v0.2.0
StopFail disables the spinner, and prints the StopFailCharacter with the StopFailMessage using the StopFailColors. This blocks until the stopped message is printed. Only possible error is if the spinner is not running.
func (*Spinner) StopFailCharacter ¶ added in v0.2.0
StopFailCharacter sets the single "character" to use for the spinner. Recommended character is ✗.
func (*Spinner) StopFailColors ¶ added in v0.2.0
StopFailColors updates the colors used for the StopFail message. See Colors() method documentation for more context.
func (*Spinner) StopFailMessage ¶ added in v0.2.0
StopFailMessage updates the Message used when StopFail() is called.
func (*Spinner) StopMessage ¶
StopMessage updates the Message used when Stop() is called.
func (*Spinner) Suffix ¶
Suffix updates the Suffix after the spinner character. It's recommended that this start with an empty space.
func (*Spinner) Unpause ¶ added in v0.8.0
Unpause returns the spinner back to a running state after pausing. See Pause() documentation for more detail. This function blocks until the spinner's internal goroutine acknowledges the request to unpause.
If the spinner is not paused this returns an error.
type SpinnerStatus ¶ added in v0.8.0
type SpinnerStatus uint32
SpinnerStatus describes the status of the spinner. See the possible constant values.
const ( // SpinnerStopped is a stopped spinner SpinnerStopped SpinnerStatus = iota // SpinnerStarting is a starting spinner SpinnerStarting // SpinnerRunning is a running spinner SpinnerRunning // SpinnerStopping is a stopping spinner SpinnerStopping // SpinnerPausing is a pausing spinner SpinnerPausing // SpinnerPaused is a paused spinner SpinnerPaused // SpinnerUnpausing is a unpausing spinner SpinnerUnpausing )
func (SpinnerStatus) String ¶ added in v0.8.0
func (s SpinnerStatus) String() string
Source Files