README.md
1# Spinner
2
3[![GoDoc](https://godoc.org/github.com/briandowns/spinner?status.svg)](https://godoc.org/github.com/briandowns/spinner) [![Build Status](https://travis-ci.org/briandowns/spinner.svg?branch=master)](https://travis-ci.org/briandowns/spinner)
4
5spinner is a simple package to add a spinner / progress indicator to any terminal application. Examples can be found below as well as full examples in the examples directory.
6
7For more detail about the library and its features, reference your local godoc once installed.
8
9Contributions welcome!
10
11## Installation
12
13```bash
14go get github.com/briandowns/spinner
15```
16
17## Available Character Sets
18(Numbered by their slice index)
19
20index | character set
21------|---------------
220 | ```←↖↑↗→↘↓↙```
231 | ```▁▃▄▅▆▇█▇▆▅▄▃▁```
242 | ```▖▘▝▗```
253 | ```┤┘┴└├┌┬┐```
264 | ```◢◣◤◥```
275 | ```◰◳◲◱```
286 | ```◴◷◶◵```
297 | ```◐◓◑◒```
308 | ```.oO@*```
319 | ```|/-\```
3210 | ```◡◡⊙⊙◠◠```
3311 | ```⣾⣽⣻⢿⡿⣟⣯⣷```
3412 | ```>))'> >))'> >))'> >))'> >))'> <'((< <'((< <'((<```
3513 | ```⠁⠂⠄⡀⢀⠠⠐⠈```
3614 | ```⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏```
3715 | ```abcdefghijklmnopqrstuvwxyz```
3816 | ```▉▊▋▌▍▎▏▎▍▌▋▊▉```
3917 | ```■□▪▫```
4018 | ```←↑→↓```
4119 | ```╫╪```
4220 | ```⇐⇖⇑⇗⇒⇘⇓⇙```
4321 | ```⠁⠁⠉⠙⠚⠒⠂⠂⠒⠲⠴⠤⠄⠄⠤⠠⠠⠤⠦⠖⠒⠐⠐⠒⠓⠋⠉⠈⠈```
4422 | ```⠈⠉⠋⠓⠒⠐⠐⠒⠖⠦⠤⠠⠠⠤⠦⠖⠒⠐⠐⠒⠓⠋⠉⠈```
4523 | ```⠁⠉⠙⠚⠒⠂⠂⠒⠲⠴⠤⠄⠄⠤⠴⠲⠒⠂⠂⠒⠚⠙⠉⠁```
4624 | ```⠋⠙⠚⠒⠂⠂⠒⠲⠴⠦⠖⠒⠐⠐⠒⠓⠋```
4725 | ```ヲァィゥェォャュョッアイウエオカキクケコサシスセソタチツテトナニヌネノハヒフヘホマミムメモヤユヨラリルレロワン```
4826 | ```. .. ...```
4927 | ```▁▂▃▄▅▆▇█▉▊▋▌▍▎▏▏▎▍▌▋▊▉█▇▆▅▄▃▂▁```
5028 | ```.oO°Oo.```
5129 | ```+x```
5230 | ```v<^>```
5331 | ```>>---> >>---> >>---> >>---> >>---> <---<< <---<< <---<< <---<< <---<<```
5432 | ```| || ||| |||| ||||| |||||| ||||| |||| ||| || |```
5533 | ```[] [=] [==] [===] [====] [=====] [======] [=======] [========] [=========] [==========]```
5634 | ```(*---------) (-*--------) (--*-------) (---*------) (----*-----) (-----*----) (------*---) (-------*--) (--------*-) (---------*)```
5735 | ```█▒▒▒▒▒▒▒▒▒ ███▒▒▒▒▒▒▒ █████▒▒▒▒▒ ███████▒▒▒ ██████████```
5836 | ```[ ] [=> ] [===> ] [=====> ] [======> ] [========> ] [==========> ] [============> ] [==============> ] [================> ] [==================> ] [===================>]```
5937 | ``` ```
6038 | ``` ```
6139 | ``` ```
6240 | ```◜ ◝ ◞ ◟```
6341 | ```⬒ ⬔ ⬓ ⬕```
6442 | ```⬖ ⬘ ⬗ ⬙```
6543 | ```[>>> >] []>>>> [] [] >>>> [] [] >>>> [] [] >>>> [] [] >>>>[] [>> >>]```
66
67## Features
68
69* Start
70* Stop
71* Restart
72* Reverse direction
73* Update the spinner character set
74* Update the spinner speed
75* Prefix or append text
76* Change spinner color
77* Get spinner status
78* Chain, pipe, redirect output
79* Output final string on spinner/indicator completion
80
81## Examples
82
83```Go
84package main
85
86import (
87 "github.com/briandowns/spinner"
88 "time"
89)
90
91func main() {
92 s := spinner.New(spinner.CharSets[9], 100*time.Millisecond) // Build our new spinner
93 s.Start() // Start the spinner
94 time.Sleep(4 * time.Second) // Run for some time to simulate work
95 s.Stop()
96}
97```
98
99## Update the character set and restart the spinner
100
101```Go
102s.UpdateCharSet(spinner.CharSets[1]) // Update spinner to use a different character set
103s.Restart() // Restart the spinner
104time.Sleep(4 * time.Second)
105s.Stop()
106```
107
108## Update spin speed and restart the spinner
109
110```Go
111s.UpdateSpeed(200 * time.Millisecond) // Update the speed the spinner spins at
112s.Restart()
113time.Sleep(4 * time.Second)
114s.Stop()
115```
116
117## Reverse the direction of the spinner
118
119```Go
120s.Reverse() // Reverse the direction the spinner is spinning
121s.Restart()
122time.Sleep(4 * time.Second)
123s.Stop()
124```
125
126## Provide your own spinner
127
128(or send me an issue or pull request to add to the project)
129
130```Go
131someSet := []string{"+", "-"}
132s := spinner.New(someSet, 100*time.Millisecond)
133```
134
135## Prefix or append text to the spinner
136
137```Go
138s.Prefix = "prefixed text: " // Prefix text before the spinner
139s.Suffix = " :appended text" // Append text after the spinner
140```
141
142## Set or change the color of the spinner. Default color is white. This will restart the spinner with the new color.
143
144```Go
145s.Color("red") // Set the spinner color to red
146```
147
148## Generate a sequence of numbers
149
150```Go
151setOfDigits := spinner.GenerateNumberSequence(25) // Generate a 25 digit string of numbers
152s := spinner.New(setOfDigits, 100*time.Millisecond)
153```
154
155## Get spinner status
156
157```Go
158fmt.Println(s.ST)
159```
160
161## Unix pipe and redirect
162
163Feature suggested and write up by [dekz](https://github.com/dekz)
164
165Setting the Spinner Writer to Stderr helps show progress to the user, with the enhancement to chain, pipe or redirect the output.
166
167```go
168s := spinner.New(spinner.CharSets[11], 100*time.Millisecond)
169s.Suffix = " Encrypting data..."
170s.Writer = os.Stderr
171s.Start()
172// Encrypt the data into ciphertext
173fmt.Println(os.Stdout, ciphertext)
174```
175
176```sh
177> myprog encrypt "Secret text" > encrypted.txt
178⣯ Encrypting data...
179```
180
181```sh
182> cat encrypted.txt
1831243hjkbas23i9ah27sj39jghv237n2oa93hg83
184```
185
186## Final String Output
187
188Add additional output when the spinner/indicator has completed. The "final" output string can be multi-lined and will be written to wherever the `io.Writer` has been configured for.
189
190```Go
191s := spinner.New(spinner.CharSets[9], 100*time.Millisecond)
192s.FinalMSG = "Complete!\nNew line!\nAnother one!\n"
193s.Start()
194time.Sleep(4 * time.Second)
195s.Stop()
196```
197
198Output
199```sh
200Complete!
201New line!
202Another one!
203```
204