yacspin

package module

v0.13.12 Latest Latest Go to latest Published: Dec 31, 2021 License: Apache-2.0 Imports: 14 Imported by: 108

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/theckman/yacspin

Links

Open Source Insights

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?

This project was created after it was realized that the most popular spinner library for Go had some limitations, that couldn't be fixed without a massive overhaul of the API.

The other spinner ties the ability to show updated messages 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. This means you need to trade off animation aesthetics to show "realtime" information. It was a goal to avoid this problem.

In addition, there were also some API design choices that have made it unsafe for concurrent use, which presents challenges when trying to update the text in the spinner while it's animating. This could result in undefined behavior due to data races.

There were also some variable-width spinners in that other project that did not render correctly. Because the width of the spinner animation would change, so would the position of the message on the screen. yacspin uses a dynamic width when animating, so your message should appear static relative to the animating spinner.

Finally, there was 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 changes needed above to support in an intuitive way.

This project takes inspiration from that other project, and takes a new approach to address the challenges above.

Features

Provided Spinners

There are over 90 spinners available in the CharSets package variable. They were borrowed from github.com/briandowns/spinner. There is a table with most 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. yacspin 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.

yacspin

yacspin animation with dynamic width

other spinners

other spinners' animation with dynamic width

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 spinner's methods.

By doing this you can use a single yacspin spinner to display the status of a list of tasks being executed serially.

Stop

Animation with Success

StopFail

Animation with Failure

Animation At End of Line

The SpinnerAtEnd field of the Config struct allows you to specify whether the spinner is rendered at the end of the line instead of the beginning. The default value (false) results in the spinner being rendered at the beginning of the line.

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 animating.

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:

Animation with Success

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.

Supporting Non-Interactive (TTY) Output Targets

yacspin also has native support for non-interactive (TTY) output targets. By default this is detected in the constructor, or can be overriden via the TerminalMode Config struct field. When detecting the application is not running withn a TTY session, the behavior of the spinner is different.

Specifically, when this is automatically detected the spinner no longer uses colors, disables the automatic spinner animation, and instead only animates the spinner when updating the message. In addition, each animation is rendered on a new line instead of overwriting the current line.

This should result in human-readable output without any changes needed by consumers, even when the system is writing to a non-TTY destination.

Manually Stepping Animation

If you'd like to manually animate the spinner, you can do so by setting the TerminalMode to ForceNoTTYMode | ForceSmartTerminalMode. In this mode the spinner will still use colors and other text stylings, but the animation only happens when data is updated and on individual lines. You can accomplish this by calling the Message() method with the same used previously.

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.

Example

There are runnable examples in the examples/ directory, with one simple example and one more advanced one. Here is a quick snippet showing usage from a very high level, with error handling omitted:

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

err = spinner.Start()

// doing some work
time.Sleep(2 * time.Second)

spinner.Message("uploading data")

// upload...
time.Sleep(2 * time.Second)

err = spinner.Stop()

Spinners

The spinner animations below are recorded at a refresh frequency of 200ms. Some animations may look better at a different speed, so play around with the frequency until you find a value you find aesthetically pleasing.

yacspin.CharSets index	sample gif (Frequency: 200ms)
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
78
79
80
81
82
83
84
85
86
87
88
89
90

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 spinner should support all major operating systems, and is tested against Linux, MacOS, and Windows.

This spinner also supports an alternate mode of operation when the TERM environment variable is set to "dumb". This is discovered automatically when constructing the spinner.

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, if you'd like to see what's supported. If you've used github.com/fatih/color before, they should look familiar.

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()

Check out the Config struct to see all of the possible configuration options supported by the Spinner.

Constants ¶

This section is empty.

Variables ¶

View Source

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: {"▌", "▀", "▐▄"},
	78: {"⠈⠁", "⠈⠑", "⠈⠱", "⠈⡱", "⢀⡱", "⢄⡱", "⢄⡱", "⢆⡱", "⢎⡱", "⢎⡰", "⢎⡠", "⢎⡀", "⢎⠁", "⠎⠁", "⠊⠁"},
	79: {"________", "-_______", "_-______", "__-_____", "___-____", "____-___", "_____-__", "______-_", "_______-", "________", "_______-", "______-_", "_____-__", "____-___", "___-____", "__-_____", "_-______", "-_______", "________"},
	80: {"|_______", "_/______", "__-_____", "___\\____", "____|___", "_____/__", "______-_", "_______\\", "_______|", "______\\_", "_____-__", "____/___", "___|____", "__\\_____", "_-______"},
	81: {"□", "◱", "◧", "▣", "■"},
	82: {"□", "◱", "▨", "▩", "■"},
	83: {"░", "▒", "▓", "█"},
	84: {"░", "█"},
	85: {"⚪", "⚫"},
	86: {"◯", "⬤"},
	87: {"▱", "▰"},
	88: {"➊", "➋", "➌", "➍", "➎", "➏", "➐", "➑", "➒", "➓"},
	89: {"½", "⅓", "⅔", "¼", "¾", "⅛", "⅜", "⅝", "⅞"},
	90: {"↞", "↟", "↠", "↡"},
}

CharSets contains the default character sets from https://github.com/briandowns/spinner.

View Source

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, and it should be reflected in the output.

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.
	Frequency time.Duration

	// Writer is the place where we are outputting the spinner, and can't be
	// changed after the *Spinner has been constructed. If omitted (nil), this
	// defaults to os.Stdout.
	Writer io.Writer

	// ShowCursor specifies that the cursor should be shown by the spinner while
	// animating. If it is not shown, the cursor will be restored when the
	// spinner stops. This can't be changed after the *Spinner has been
	// constructed.
	//
	// Please note, if you do not set this to true and the program crashes or is
	// killed, you may need to reset your terminal for the cursor to appear
	// again.
	ShowCursor bool

	// HideCursor describes whether the cursor should be hidden by the spinner
	// while animating. If it is hidden, it will be restored when the spinner
	// stops. This can't be changed after the *Spinner has been constructed.
	//
	// Please note, if the program crashes or is killed you may need to reset
	// your terminal for the cursor to appear again.
	//
	// Deprecated: use ShowCursor instead.
	HideCursor bool

	// SpinnerAtEnd configures the spinner to render the animation at the end of
	// the line instead of the beginning. The default behavior is to render the
	// animated spinner at the beginning of the line.
	SpinnerAtEnd bool

	// ColorAll describes whether to color everything (all) or just the spinner
	// character(s). This cannot be changed after the *Spinner has been
	// constructed.
	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.
	//
	// If SpinnerAtEnd is set to true, it's recommended that this string start
	// with a space character (` `).
	Prefix string

	// Suffix is the string printed immediately after the spinner and before the
	// message.
	//
	// If SpinnerAtEnd is set to false, 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, or the suffix
	// is only space characters, the colon is omitted.
	//
	// If SpinnerAtEnd is set to true, this option is ignored.
	SuffixAutoColon bool

	// Message is the message string printed by the spinner. If SpinnerAtEnd is
	// set to false and SuffixAutoColon is set to true, the printed line will
	// look like:
	//
	//    <prefix><spinner><suffix>: <message>
	//
	// If SpinnerAtEnd is set to true, the printed line will instead look like
	// this:
	//
	//    <message><prefix><spinner><suffix>
	//
	// In this case, it may be preferred to set the Prefix to empty space (` `).
	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 ✓, and can be more than just one character.
	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 ✗, and can be more than just one
	// character.
	StopFailCharacter string

	// StopFailColors are the colors used for the StopFail() printed line. This
	// respects the ColorAll field.
	StopFailColors []string

	// TerminalMode is a bitflag field to control how the internal TTY / "dumb
	// terminal" detection works, to allow consumers to override the internal
	// behaviors. To set this value, it's recommended to use the TerminalMode
	// constants exported by this package.
	//
	// If not set, the New() function implicitly sets it to AutomaticMode. The
	// New() function also returns an error if you have conflicting flags, such
	// as setting ForceTTYMode and ForceNoTTYMode, or if you set AutomaticMode
	// and any other flags set.
	//
	// When in AutomaticMode, the New() function attempts to determine if the
	// current application is running within an interactive (teletype [TTY])
	// session. If it does not appear to be within a TTY, it sets this field
	// value to ForceNoTTYMode | ForceDumbTerminalMode.
	//
	// If this does appear to be a TTY, the ForceTTYMode bitflag will bet set.
	// Similarly, if it's a TTY and the TERM environment variable isn't set to
	// "dumb" the ForceSmartTerminalMode bitflag will also be set.
	//
	// If the deprecated NoTTY Config struct field is set to true, and this
	// field is AutomaticMode, the New() function sets field to the value of
	// ForceNoTTYMode | ForceDumbTerminalMode.
	TerminalMode TerminalMode

	// NotTTY tells the spinner that the Writer should not be treated as a TTY.
	// This results in the animation being disabled, with the animation only
	// happening whenever the data is updated. This mode also renders each
	// update on new line, versus reusing the current line.
	//
	// Deprecated: use TerminalMode field instead by setting it to:
	// ForceNoTTYMode | ForceDumbTerminalMode. This will be removed in a future
	// release.
	NotTTY bool
}

Config is the configuration structure for the Spinner type, which you provide to the New() function. Some of the fields can be updated after the *Spinner is constructed, others can only be set when calling the constructor. Please read the comments for those details.

type Spinner ¶

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

Spinner is a type representing an animated CLi terminal spinner. The Spinner is constructed by the New() function of this package, which accepts a Config struct as the only argument. Some of the configuration values cannot be changed after the spinner is constructed, so be sure to read the comments within the Config type.

Please note, by default the spinner will hide the terminal cursor when animating the spinner. If you do not set Config.ShowCursor to true, you need to make sure to call the Stop() or StopFail() method to reset the cursor in the terminal. Otherwise, after the program exits the cursor will be hidden and the user will need to `reset` their terminal.

func New ¶

func New(cfg Config) (*Spinner, error)

New creates a new unstarted spinner. If stdout does not appear to be a TTY, this constructor implicitly sets cfg.NotTTY to true.

func (*Spinner) CharSet ¶

func (s *Spinner) CharSet(cs []string) error

CharSet updates the set of characters (strings) to use for the spinner. You can provide your own, or use one from the yacspin.CharSets variable.

The character sets available in the CharSets variable are from the https://github.com/briandowns/spinner project.

func (*Spinner) Colors ¶

func (s *Spinner) Colors(colors ...string) error

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

func (s *Spinner) Frequency(d time.Duration) error

Frequency updates the frequency of the spinner being animated.

func (*Spinner) Message ¶

func (s *Spinner) Message(message string)

Message updates the Message displayed after the suffix.

func (*Spinner) Pause ¶ added in v0.8.0

func (s *Spinner) Pause() error

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 painting 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) Prefix ¶

func (s *Spinner) Prefix(prefix string)

Prefix updates the Prefix before the spinner character.

func (*Spinner) Reverse ¶

func (s *Spinner) Reverse()

Reverse flips the character set order of the spinner characters.

func (*Spinner) Start ¶

func (s *Spinner) Start() error

Start begins the spinner on the Writer in the Config provided to New(). Only 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 spinner. The returned value is of type SpinnerStatus, which can be compared against the exported Spinner* package-level constants (e.g., SpinnerRunning).

func (*Spinner) Stop ¶

func (s *Spinner) Stop() error

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 ¶

func (s *Spinner) StopCharacter(char string)

StopCharacter sets the single "character" to use for the spinner when stopping. Recommended character is ✓.

func (*Spinner) StopColors ¶

func (s *Spinner) StopColors(colors ...string) error

StopColors updates the colors used for the stop message. See Colors() method documentation for more context.

StopFailColors() is the method to control the colors in the failed stop message.

func (*Spinner) StopFail ¶ added in v0.2.0

func (s *Spinner) StopFail() error

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

func (s *Spinner) StopFailCharacter(char string)

StopFailCharacter sets the single "character" to use for the spinner when stopping for a failure. Recommended character is ✗.

func (*Spinner) StopFailColors ¶ added in v0.2.0

func (s *Spinner) StopFailColors(colors ...string) error

StopFailColors updates the colors used for the StopFail message. See Colors() method documentation for more context.

func (*Spinner) StopFailMessage ¶ added in v0.2.0

func (s *Spinner) StopFailMessage(message string)

StopFailMessage updates the Message used when StopFail() is called.

func (*Spinner) StopMessage ¶

func (s *Spinner) StopMessage(message string)

StopMessage updates the Message used when Stop() is called.

func (*Spinner) Suffix ¶

func (s *Spinner) Suffix(suffix string)

Suffix updates the Suffix printed after the spinner character and before the message. It's recommended that this start with an empty space.

func (*Spinner) Unpause ¶ added in v0.8.0

func (s *Spinner) Unpause() error

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 painting 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 package constants for the list of all possible statuses

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 an unpausing spinner
	SpinnerUnpausing
)

func (SpinnerStatus) String ¶ added in v0.8.0

func (s SpinnerStatus) String() string

type TerminalMode ¶ added in v0.13.12

type TerminalMode uint32

TerminalMode is a type to represent the bit flag controlling the terminal mode of the spinner, accepted as a field on the Config struct. See the comments on the exported constants for more info.

const (
	// AutomaticMode configures the constructor function to try and determine if
	// the application using yacspin is being executed within a interactive
	// (teletype [TTY]) session.
	AutomaticMode TerminalMode = 1 << iota

	// ForceTTYMode configures the spinner to operate as if it's running within
	// a TTY session.
	ForceTTYMode

	// ForceNoTTYMode configures the spinner to operate as if it's not running
	// within a TTY session. This mode causes the spinner to only animate when
	// data is being updated. Each animation is rendered on a new line. You can
	// trigger an animation by calling the Message() method, including with the
	// last value it was called with.
	ForceNoTTYMode

	// ForceDumbTerminalMode configures the spinner to operate as if it's
	// running within a dumb terminal. This means the spinner will not use ANSI
	// escape sequences to print colors or to erase each line. Line erasure to
	// animate the spinner is accomplished by overwriting the line with space
	// characters.
	ForceDumbTerminalMode

	// ForceSmartTerminalMode configures the spinner to operate as if it's
	// running within a terminal that supports ANSI escape sequences (VT100).
	// This includes printing of stylized text, and more better line erasure to
	// animate the spinner.
	ForceSmartTerminalMode
)

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
examples
advanced
demo
demo/scripts
simple

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

yacspin.CharSets index	sample gif (Frequency: 200ms)
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
78
79
80
81
82
83
84
85
86
87
88
89
90

yacspin.CharSets index	sample gif (Frequency: 200ms)
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
78
79
80
81
82
83
84
85
86
87
88
89
90

yacspin.CharSets index	sample gif (Frequency: 200ms)
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
78
79
80
81
82
83
84
85
86
87
88
89
90