Add TerminalMode config; make Frequency optional when not TTY

This change introduces a substantial change to how we handle the TTY discovery
when constructing the spinner. It adds a new bitflag field to the Config struct,
TerminalMode, that allows consumers to control whether the spinner tries to
automatically disocver if it's within a TTY and/or a dumb terminal. It also
allows you to override the behaviors, if you know the automatic mode won't do
what you want.

A side effect of this change is that you can now manually step the spinner
animation by setting TerminalMode: ForceNoTTYMode, and then starting the spinner
and calling the Message() method when you want to animate the spinner. To permit
this, the Frequency field in the Config struct is now not required when calling
the New() function. An error will be generated on Start() if it's within a TTY
and the Frequency is 0.

This also deprecates the NotTTY field in the Config struct.

README.md

@@ -110,19 +110,27 @@ 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-TTY Output Targets
-`yacspin` also has native support for non-TTY output targets. This is detected
-automatically within the constructor, or can be specified via the `NotTTY`
-`Config` struct field, and results in a different mode of operation.
+#### 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 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.
+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

spinner.go

@@ -89,15 +89,55 @@ func setToCharSlice(ss []string) ([]character, int) {
 	return c, maxWidth
 }
 
+// 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.
+type TerminalMode uint32
+
+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
+)
+
+func termModeAuto(t TerminalMode) bool       { return t&AutomaticMode > 0 }
+func termModeForceTTY(t TerminalMode) bool   { return t&ForceTTYMode > 0 }
+func termModeForceNoTTY(t TerminalMode) bool { return t&ForceNoTTYMode > 0 }
+func termModeForceDumb(t TerminalMode) bool  { return t&ForceDumbTerminalMode > 0 }
+func termModeForceSmart(t TerminalMode) bool { return t&ForceSmartTerminalMode > 0 }
+
 // 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 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
 
 	// Writer is the place where we are outputting the spinner, and can't be
@@ -200,10 +240,38 @@ type Config struct {
 	// 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
 }
 
@@ -224,8 +292,7 @@ type Spinner struct {
 	colorAll        bool
 	cursorHidden    bool
 	suffixAutoColon bool
-	isDumbTerm      bool
-	isNotTTY        bool
+	termMode        TerminalMode
 	spinnerAtEnd    bool
 
 	status       *uint32
@@ -269,20 +336,50 @@ const (
 // New creates a new unstarted spinner. If stdout does not appear to be a TTY,
 // this constructor implicitly sets cfg.NotTTY to true.
 func New(cfg Config) (*Spinner, error) {
-	if cfg.Frequency < 1 {
-		return nil, errors.New("cfg.Frequency must be greater than 0")
-	}
-
 	if cfg.ShowCursor && cfg.HideCursor {
 		return nil, errors.New("cfg.ShowCursor and cfg.HideCursor cannot be true")
 	}
 
+	if cfg.TerminalMode == 0 {
+		cfg.TerminalMode = AutomaticMode
+	}
+
+	// AutomaticMode flag has been set, but so have others
+	if termModeAuto(cfg.TerminalMode) && cfg.TerminalMode != AutomaticMode {
+		return nil, errors.New("cfg.TerminalMode cannot have AutomaticMode flag set if others are set")
+	}
+
+	if termModeForceTTY(cfg.TerminalMode) && termModeForceNoTTY(cfg.TerminalMode) {
+		return nil, errors.New("cfg.TerminalMode cannot have both ForceTTYMode and ForceNoTTYMode flags set")
+	}
+
+	if termModeForceDumb(cfg.TerminalMode) && termModeForceSmart(cfg.TerminalMode) {
+		return nil, errors.New("cfg.TerminalMode cannot have both ForceDumbTerminalMode and ForceSmartTerminalMode flags set")
+	}
+
 	if cfg.HideCursor {
 		cfg.ShowCursor = false
 	}
 
-	if !isatty.IsTerminal(os.Stdout.Fd()) && !isatty.IsCygwinTerminal(os.Stdout.Fd()) {
-		cfg.NotTTY = true
+	// cfg.NotTTY compatibility
+	if cfg.TerminalMode == AutomaticMode && cfg.NotTTY {
+		cfg.TerminalMode = ForceNoTTYMode | ForceDumbTerminalMode
+	}
+
+	// is this a dumb terminal / not a TTY?
+	if cfg.TerminalMode == AutomaticMode && !isatty.IsTerminal(os.Stdout.Fd()) && !isatty.IsCygwinTerminal(os.Stdout.Fd()) {
+		cfg.TerminalMode = ForceNoTTYMode | ForceDumbTerminalMode
+	}
+
+	// if cfg.TerminalMode is still equal to AutomaticMode, this is a TTY
+	if cfg.TerminalMode == AutomaticMode {
+		cfg.TerminalMode = ForceTTYMode
+
+		if os.Getenv("TERM") == "dumb" {
+			cfg.TerminalMode |= ForceDumbTerminalMode
+		} else {
+			cfg.TerminalMode |= ForceSmartTerminalMode
+		}
 	}
 
 	buf := bytes.NewBuffer(make([]byte, 2048))
@@ -300,7 +397,7 @@ func New(cfg Config) (*Spinner, error) {
 		cursorHidden:    !cfg.ShowCursor,
 		spinnerAtEnd:    cfg.SpinnerAtEnd,
 		suffixAutoColon: cfg.SuffixAutoColon,
-		isDumbTerm:      os.Getenv("TERM") == "dumb",
+		termMode:        cfg.TerminalMode,
 		colorFn:         fmt.Sprintf,
 		stopColorFn:     fmt.Sprintf,
 		stopFailColorFn: fmt.Sprintf,
@@ -325,9 +422,9 @@ func New(cfg Config) (*Spinner, error) {
 	// can only error if the charset is empty, and we prevent that above
 	_ = s.CharSet(cfg.CharSet)
 
-	if cfg.NotTTY {
-		s.isNotTTY = true
-		s.isDumbTerm = true
+	if termModeForceNoTTY(s.termMode) {
+		// hack to prevent the animation from running if not a TTY
+		s.frequency = time.Duration(math.MaxInt64)
 	}
 
 	if cfg.Writer == nil {
@@ -442,6 +539,10 @@ func (s *Spinner) Start() error {
 
 	s.mu.Lock()
 
+	if s.frequency < 1 && termModeForceTTY(s.termMode) {
+		return errors.New("spinner Frequency duration must be greater than 0 when used within a TTY")
+	}
+
 	if len(s.chars) == 0 {
 		s.mu.Unlock()
 
@@ -456,11 +557,6 @@ func (s *Spinner) Start() error {
 	s.frequencyUpdateCh = make(chan time.Duration, 4)
 	s.dataUpdateCh, s.cancelCh = make(chan struct{}, 1), make(chan struct{}, 1)
 
-	if s.isNotTTY {
-		// hack to prevent the animation from running if not a TTY
-		s.frequency = time.Duration(math.MaxInt64)
-	}
-
 	s.mu.Unlock()
 
 	// because of the atomic swap above, we know it's safe to mutate these
@@ -643,7 +739,7 @@ func (s *Spinner) painter(cancel, dataUpdate, pause <-chan struct{}, done chan<-
 
 		case <-dataUpdate:
 			// if this is not a TTY: animate the spinner on the data update
-			s.paintUpdate(timer, s.isNotTTY)
+			s.paintUpdate(timer, termModeForceNoTTY(s.termMode))
 
 		case frequency := <-frequencyUpdate:
 			handleFrequencyUpdate(frequency, timer, lastTick)
@@ -692,7 +788,7 @@ func (s *Spinner) paintUpdate(timer *time.Timer, animate bool) {
 
 	defer s.buffer.Reset()
 
-	if !s.isDumbTerm {
+	if termModeForceSmart(s.termMode) {
 		if err := erase(s.buffer); err != nil {
 			panic(fmt.Sprintf("failed to erase line: %v", err))
 		}
@@ -703,15 +799,15 @@ func (s *Spinner) paintUpdate(timer *time.Timer, animate bool) {
 			}
 		}
 
-		if _, err := paint(s.buffer, mw, c, p, m, suf, s.suffixAutoColon, s.colorAll, s.spinnerAtEnd, false, s.isNotTTY, cFn); err != nil {
+		if _, err := paint(s.buffer, mw, c, p, m, suf, s.suffixAutoColon, s.colorAll, s.spinnerAtEnd, false, termModeForceNoTTY(s.termMode), cFn); err != nil {
 			panic(fmt.Sprintf("failed to paint line: %v", err))
 		}
 	} else {
 		if err := s.eraseDumbTerm(s.buffer); err != nil {
 			panic(fmt.Sprintf("failed to erase line: %v", err))
 		}
 
-		n, err := paint(s.buffer, mw, c, p, m, suf, s.suffixAutoColon, false, s.spinnerAtEnd, false, s.isNotTTY, fmt.Sprintf)
+		n, err := paint(s.buffer, mw, c, p, m, suf, s.suffixAutoColon, false, s.spinnerAtEnd, false, termModeForceNoTTY(s.termMode), fmt.Sprintf)
 		if err != nil {
 			panic(fmt.Sprintf("failed to paint line: %v", err))
 		}
@@ -755,7 +851,7 @@ func (s *Spinner) paintStop(chanOk bool) {
 
 	defer s.buffer.Reset()
 
-	if !s.isDumbTerm {
+	if termModeForceSmart(s.termMode) {
 		if err := erase(s.buffer); err != nil {
 			panic(fmt.Sprintf("failed to erase line: %v", err))
 		}
@@ -768,7 +864,7 @@ func (s *Spinner) paintStop(chanOk bool) {
 
 		if c.Size > 0 || len(m) > 0 {
 			// paint the line with a newline as it's the final line
-			if _, err := paint(s.buffer, mw, c, p, m, suf, s.suffixAutoColon, s.colorAll, s.spinnerAtEnd, true, s.isNotTTY, cFn); err != nil {
+			if _, err := paint(s.buffer, mw, c, p, m, suf, s.suffixAutoColon, s.colorAll, s.spinnerAtEnd, true, termModeForceNoTTY(s.termMode), cFn); err != nil {
 				panic(fmt.Sprintf("failed to paint line: %v", err))
 			}
 		}
@@ -778,7 +874,7 @@ func (s *Spinner) paintStop(chanOk bool) {
 		}
 
 		if c.Size > 0 || len(m) > 0 {
-			if _, err := paint(s.buffer, mw, c, p, m, suf, s.suffixAutoColon, false, s.spinnerAtEnd, true, s.isNotTTY, fmt.Sprintf); err != nil {
+			if _, err := paint(s.buffer, mw, c, p, m, suf, s.suffixAutoColon, false, s.spinnerAtEnd, true, termModeForceNoTTY(s.termMode), fmt.Sprintf); err != nil {
 				panic(fmt.Sprintf("failed to paint line: %v", err))
 			}
 		}
@@ -801,7 +897,9 @@ func erase(w io.Writer) error {
 
 // eraseDumbTerm clears the line on dumb terminals
 func (s *Spinner) eraseDumbTerm(w io.Writer) error {
-	if s.isNotTTY {
+	if termModeForceNoTTY(s.termMode) {
+		// non-TTY outputs use \n instead of line erasure,
+		// so return early
 		return nil
 	}
 
@@ -882,7 +980,9 @@ func (s *Spinner) Frequency(d time.Duration) error {
 		return errors.New("duration must be greater than 0")
 	}
 
-	if s.isNotTTY {
+	if termModeForceNoTTY(s.termMode) {
+		// when output target is not a TTY, we don't animate spinner
+		// so there is no need to update the frequency
 		return nil
 	}