Refactor OutputWriterSpinner component and Add SetText and `Start…

…Spinner` APIs (vmware-tanzu#157)

* Eliminate the use of parameters and use options to create a spinner
* Implements SetText, StartSpinner APIs
* Update docs

component/README.md

@@ -179,51 +179,88 @@ This will output:
 
 ## OutputWriterSpinner Component
 
-`OutputWriterSpinner` provides an interface to `OutputWriter` augmented with a spinner. It allows for rendering output with a spinner while also providing the ability to stop the spinner and render the final output.
+`OutputWriterSpinner` provides an interface to `OutputWriter` augmented with a spinner. It allows for displaying output of multiple types (Text, Table, Yaml, Json) with a spinner while also providing the ability to stop the spinner, display the final text and render the output.
 
 ### Usage
 
-To use `OutputWriterSpinner`, you can import the package in your Go code and create an instance of the `OutputWriterSpinner` interface using the `NewOutputWriterSpinnerWithOptions` function.
+To use `OutputWriterSpinner`, you can import the package in your Go code and create an instance of the `OutputWriterSpinner` interface using the `NewOutputWriterSpinner` function.
 
-Note that NewOutputWriterWithSpinner has been deprecated in favor of NewOutputWriterSpinnerWithOptions
-One difference in the default rendering behavior for YAML/JSON output between
-the writer created with NewOutputWriterWithSpinner vs that created with NewOutputWriterSpinnerWithOptions
-is that row fields no longer gets auto stringified in the latter.
+Note that `NewOutputWriterWithSpinner` and `NewOutputWriterSpinnerWithOptions` has been deprecated in favor of `NewOutputWriterSpinner`.
+The main difference is how the parameters are provided when creating a `OutputWriterSpinner` component.
 
-To retain the stringify behavior (unlikely what if needed except for backward compatibility
-reasons), create the output writer by including WithAutoStringify() in the
-options list .
+#### Using Spinner to display Table/JSON/YAML output
 
 ``` go
 import "github.com/vmware-tanzu/tanzu-plugin-runtime/component"
 
-
-// create new OutputWriterSpinner
-outputWriterSpinner, err := component.NewOutputWriterSpinnerWithOptions(os.Stdout, "json", "Loading...", true, []OutputWriterOption{})
+// Create new OutputWriterSpinner component. If `WithOutputStream` option is not provided, it will use os.Stdout as default output stream
+owSpinner, err := component.NewOutputWriterSpinner(
+        component.WithOutputFormat(component.TableOutputType), // For JSON use JSONOutputType and for YAML use YAMLOutputType
+        component.WithSpinnerText("Fetching data..."),
+        component.WithSpinnerStarted(),
+        component.WithHeaders("Namespace", "Name", "Ready"))
 if err != nil {
     fmt.Println("Error creating OutputWriterSpinner:", err)
     return
 }
 
-// Render output with spinner
-outputWriterSpinner.RenderWithSpinner()
+// Do some processing to fetch the data from server and fill rows for table
+owSpinner.AddRow("default", "pod1", "False")
+owSpinner.AddRow("default", "pod2", "True")
+
+// Stop the running spinner instance, displays FinalText if set, then renders the tabular output
+owSpinner.Render()
 
-// Stop spinner and render final output
-outputWriterSpinner.StopSpinner()
 ```
 
-The `NewOutputWriterWithSpinner` function takes in the following parameters:
+#### Using Spinner to display plain text
+
+``` go
+import "github.com/vmware-tanzu/tanzu-plugin-runtime/component"
+
+// Create new OutputWriterSpinner component
+spinner, err := component.NewOutputWriterSpinner(component.WithOutputStream(os.Stderr))
+if err != nil {
+    fmt.Println("Error creating spinner:", err)
+    return
+}
 
-- `output io.Writer`: The output writer for the spinner and final output.
-- `outputFormat string`: The output format for the final output. It can be either "json" or "yaml".
-- `spinnerText string`: The text to display next to the spinner.
-- `startSpinner bool`: Whether to start the spinner immediately or not.
-- `headers ...string`: Optional headers for the final output.
+spinner.SetText("Installing plugin 'apps'")
+spinner.StartSpinner()
 
-The created `OutputWriterSpinner` instance provides two methods:
+// Do some processing to fetch and install the required plugin
+err := InstallPlugin("apps")
+
+if err != nil {
+    spinner.SetFinalText("Error while installing the plugin 'apps'", log.LogTypeERROR)
+} else {
+    spinner.SetFinalText("Successfully installed the plugin 'apps'", log.LogTypeSuccess)
+}
+
+// Stop the spinner and displays FinalText
+spinner.StopSpinner()
+
+```
 
-- `RenderWithSpinner()`: Renders the output with a spinner.
-- `StopSpinner()`: Stops the spinner and renders the final output.
+The `NewOutputWriterSpinner` function takes in the following optional options:
+
+- `WithOutputStream(writer io.Writer)`: sets the output stream for the OutputWriterSpinner component.
+- `WithOutputFormat(outputFormat OutputType)`: sets output format for the OutputWriterSpinner component.
+- `WithOutputWriterOptions(opts ...OutputWriterOption)`: configures OutputWriterOptions to the OutputWriterSpinner component.
+- `WithSpinnerText(text string)`: sets the spinner text
+- `WithSpinnerFinalText(finalText string, prefix log.LogType)`: sets the spinner final text and prefix log indicator
+- `WithSpinnerStarted()`: starts the spinner when the OutputWriterSpinner component gets created
+- `WithHeaders(headers ...string)`: Sets the headers for the OutputWriterOptions component
+
+The created `OutputWriterSpinner` instance provides following methods:
+
+- `SetKeys(headerKeys ...string)`: sets the headers for the OutputWriter component
+- `AddRow(items ...interface{})`: adds rows to the OutputWriter component
+- `SetText(text string)`: sets the spinner text
+- `SetFinalText(finalText string, prefix log.LogType)`: sets the spinner final text and prefix log indicator
+- `StartSpinner()`: starts the spinner instance, showing the spinnerText
+- `StopSpinner()`: stops the running spinner instance, displays FinalText if set
+- `Render()`: stops the running spinner instance, displays FinalText if set, then renders the output
 
 ## Prompt Component
 

component/output_spinner.go

@@ -18,8 +18,15 @@ import (
 // OutputWriterSpinner is OutputWriter augmented with a spinner.
 type OutputWriterSpinner interface {
 	OutputWriter
+	// RenderWithSpinner will stop spinner and render the output
+	// Deprecated: RenderWithSpinner is being deprecated in favor of Render.
 	RenderWithSpinner()
+	// StartSpinner starts the spinner instance, showing the spinnerText
+	StartSpinner()
+	// StopSpinner stops the running spinner instance, displays FinalText if set
 	StopSpinner()
+	// SetText sets the spinner text
+	SetText(text string)
 	// SetFinalText sets the spinner final text and prefix
 	// log indicator (log.LogTypeOUTPUT can be used for no prefix)
 	SetFinalText(finalText string, prefix log.LogType)
@@ -28,32 +35,69 @@ type OutputWriterSpinner interface {
 // outputwriterspinner is our internal implementation.
 type outputwriterspinner struct {
 	outputwriter
-	spinnerText      string
-	spinnerFinalText string
-	spinner          *spinner.Spinner
+	spinnerText        string
+	spinnerFinalText   string
+	startSpinnerOnInit bool
+	spinner            *spinner.Spinner
 }
 
-type OutputWriterSpinnerOptions struct {
-	OutputWriterOptions []OutputWriterOption
-	SpinnerOptions      []OutputWriterSpinnerOption
-}
-
-// OutputWriterSpinnerOption is an option for outputwriterspinner
+// OutputWriterSpinnerOption is an option to configure outputwriterspinner
 type OutputWriterSpinnerOption func(*outputwriterspinner)
 
 // WithSpinnerFinalText sets the spinner final text and prefix log indicator
 // (log.LogTypeOUTPUT can be used for no prefix)
 func WithSpinnerFinalText(finalText string, prefix log.LogType) OutputWriterSpinnerOption {
-	finalText = fmt.Sprintf("%s%s", log.GetLogTypeIndicator(prefix), finalText)
 	return func(ows *outputwriterspinner) {
-		ows.spinnerFinalText = finalText
+		ows.spinnerFinalText = fmt.Sprintf("%s%s", log.GetLogTypeIndicator(prefix), finalText)
+	}
+}
+
+// WithOutputWriterOptions configures OutputWriterOptions to the spinner
+func WithOutputWriterOptions(opts ...OutputWriterOption) OutputWriterSpinnerOption {
+	return func(ow *outputwriterspinner) {
+		ow.applyOptions(opts)
+	}
+}
+
+// WithSpinnerText sets the spinner text
+func WithSpinnerText(text string) OutputWriterSpinnerOption {
+	return func(ows *outputwriterspinner) {
+		ows.spinnerText = text
+	}
+}
+
+// WithSpinnerStarted starts the spinner
+func WithSpinnerStarted() OutputWriterSpinnerOption {
+	return func(ows *outputwriterspinner) {
+		ows.startSpinnerOnInit = true
+	}
+}
+
+// WithHeaders sets key headers
+func WithHeaders(headers ...string) OutputWriterSpinnerOption {
+	return func(ows *outputwriterspinner) {
+		ows.keys = headers
+	}
+}
+
+// WithOutputFormat sets output format for the OutputWriterSpinner component
+func WithOutputFormat(outputFormat OutputType) OutputWriterSpinnerOption {
+	return func(ows *outputwriterspinner) {
+		ows.outputFormat = outputFormat
+	}
+}
+
+// WithOutputStream sets the output stream for the OutputWriterSpinner component
+func WithOutputStream(writer io.Writer) OutputWriterSpinnerOption {
+	return func(ows *outputwriterspinner) {
+		ows.out = writer
 	}
 }
 
 // NewOutputWriterWithSpinner returns implementation of OutputWriterSpinner.
 //
 // Deprecated: NewOutputWriterWithSpinner is being deprecated in favor of
-// NewOutputWriterSpinnerWithSpinnerOptions.
+// NewOutputWriterSpinner.
 // Until it is removed, it will retain the existing behavior of converting
 // incoming row values to their golang string representation for backward
 // compatibility reasons
@@ -65,60 +109,69 @@ func NewOutputWriterWithSpinner(output io.Writer, outputFormat, spinnerText stri
 // NewOutputWriterSpinnerWithOptions returns implementation of OutputWriterSpinner.
 //
 // Deprecated: NewOutputWriterSpinnerWithOptions is being deprecated in favor of
-// NewOutputWriterSpinnerWithSpinnerOptions.
+// NewOutputWriterSpinner.
 func NewOutputWriterSpinnerWithOptions(output io.Writer, outputFormat, spinnerText string, startSpinner bool, opts []OutputWriterOption, headers ...string) (OutputWriterSpinner, error) {
 	ows := &outputwriterspinner{}
 	ows.out = output
 	ows.outputFormat = OutputType(outputFormat)
 	ows.keys = headers
 	ows.applyOptions(opts)
-
-	return setAndInitializeSpinner(ows, spinnerText, startSpinner)
+	ows.spinnerText = spinnerText
+	ows.startSpinnerOnInit = startSpinner
+	return initializeSpinner(ows), nil
 }
 
-// NewOutputWriterSpinnerWithSpinnerOptions returns implementation of OutputWriterSpinner.
-func NewOutputWriterSpinnerWithSpinnerOptions(output io.Writer, outputFormat OutputType, spinnerText string, startSpinner bool, opts OutputWriterSpinnerOptions, headers ...string) (OutputWriterSpinner, error) {
+// NewOutputWriterSpinner returns implementation of OutputWriterSpinner
+func NewOutputWriterSpinner(opts ...OutputWriterSpinnerOption) (OutputWriterSpinner, error) {
 	ows := &outputwriterspinner{}
-	ows.out = output
-	ows.outputFormat = outputFormat
-	ows.keys = headers
-	ows.applyOptions(opts.OutputWriterOptions)
-	ows.applyOutputWriterSpinnerOptions(opts.SpinnerOptions)
-	return setAndInitializeSpinner(ows, spinnerText, startSpinner)
+	ows.out = os.Stdout
+	ows.applySpinnerOptions(opts)
+	// Note: We are returning the 'nil' error always to protect against the possible API
+	// enhancement which might require throwing an error in future
+	return initializeSpinner(ows), nil
 }
 
-// setAndInitializeSpinner sets the spinner text and initializes the spinner
-func setAndInitializeSpinner(ows *outputwriterspinner, spinnerText string, startSpinner bool) (OutputWriterSpinner, error) {
+// initializeSpinner initializes the spinner
+func initializeSpinner(ows *outputwriterspinner) OutputWriterSpinner {
 	if ows.outputFormat != JSONOutputType && ows.outputFormat != YAMLOutputType {
-		ows.spinnerText = spinnerText
-		ows.spinner = spinner.New(spinner.CharSets[9], 100*time.Millisecond)
-		if err := ows.spinner.Color("bgBlack", "bold", "fgWhite"); err != nil {
-			return nil, err
-		}
-		ows.spinner.Suffix = fmt.Sprintf(" %s", spinnerText)
-		if ows.spinnerFinalText != "" {
-			spinner.WithFinalMSG(ows.spinnerFinalText)(ows.spinner)
-		}
+		ows.spinner = spinner.New(spinner.CharSets[9], 100*time.Millisecond,
+			spinner.WithWriter(ows.out),
+			spinner.WithFinalMSG(ows.spinnerFinalText),
+			spinner.WithSuffix(fmt.Sprintf(" %s", ows.spinnerText)),
+			spinner.WithColor("bold"),
+		)
 
 		// Start the spinner only if attached to terminal
 		attachedToTerminal := isatty.IsTerminal(os.Stdout.Fd()) || isatty.IsCygwinTerminal(os.Stdout.Fd())
-		if startSpinner && attachedToTerminal {
+		if ows.startSpinnerOnInit && attachedToTerminal {
 			ows.spinner.Start()
 		}
 	}
-	return ows, nil
+	return ows
 }
 
-// RenderWithSpinner will stop spinner and render the output
+// RenderWithSpinner stops the running spinner instance, displays FinalText if set, then renders the output
+//
+// Deprecated: RenderWithSpinner is being deprecated in favor of Render.
 func (ows *outputwriterspinner) RenderWithSpinner() {
-	if ows.spinner != nil && ows.spinner.Active() {
-		ows.spinner.Stop()
-		fmt.Fprintln(ows.out)
-	}
 	ows.Render()
 }
 
-// stop spinner
+// Render stops the running spinner instance, displays FinalText if set, then renders the output
+func (ows *outputwriterspinner) Render() {
+	ows.StopSpinner()
+	ows.outputwriter.Render()
+}
+
+// StartSpinner starts the spinner instance, showing the spinnerText
+func (ows *outputwriterspinner) StartSpinner() {
+	attachedToTerminal := isatty.IsTerminal(os.Stdout.Fd()) || isatty.IsCygwinTerminal(os.Stdout.Fd())
+	if ows.spinner != nil && !ows.spinner.Active() && attachedToTerminal {
+		ows.spinner.Start()
+	}
+}
+
+// StopSpinner stops the running spinner instance, displays FinalText if set
 func (ows *outputwriterspinner) StopSpinner() {
 	if ows.spinner != nil && ows.spinner.Active() {
 		ows.spinner.Stop()
@@ -135,8 +188,16 @@ func (ows *outputwriterspinner) SetFinalText(finalText string, prefix log.LogTyp
 	}
 }
 
-// applyOutputWriterSpinnerOptions applies the options to the outputwriterspinner
-func (ows *outputwriterspinner) applyOutputWriterSpinnerOptions(spinnerOpts []OutputWriterSpinnerOption) {
+// SetText sets the spinner text
+func (ows *outputwriterspinner) SetText(text string) {
+	if ows.spinner != nil {
+		ows.spinnerText = text
+		ows.spinner.Suffix = fmt.Sprintf(" %s", text)
+	}
+}
+
+// applySpinnerOptions applies the options to the outputwriterspinner
+func (ows *outputwriterspinner) applySpinnerOptions(spinnerOpts []OutputWriterSpinnerOption) {
 	for i := range spinnerOpts {
 		spinnerOpts[i](ows)
 	}

component/output_spinner_test.go

@@ -59,31 +59,34 @@ func TestNewOutputWriterSpinnerWithOptions(t *testing.T) {
 	assert.NotNil(t, ows)
 }
 
-func TestNewOutputWriterSpinnerWithSpinnerOptions(t *testing.T) {
+func TestNewOutputWriterSpinner(t *testing.T) {
 	output := bytes.Buffer{}
 	spinnerText := loading
 	headers := []string{"Name", "Age"}
 
-	// Test creating an OutputWriterSpinner with spinner options and a spinner
-	opts := OutputWriterSpinnerOptions{
-		OutputWriterOptions: []OutputWriterOption{WithAutoStringify()},
-		SpinnerOptions:      []OutputWriterSpinnerOption{WithSpinnerFinalText("Done!", log.LogTypeSUCCESS)},
-	}
-	ows, err := NewOutputWriterSpinnerWithSpinnerOptions(&output, "table", spinnerText, true, opts, headers...)
+	ows, err := NewOutputWriterSpinner(WithOutputStream(&output),
+		WithOutputFormat(TableOutputType),
+		WithSpinnerText(spinnerText),
+		WithSpinnerStarted(),
+		WithOutputWriterOptions(WithAutoStringify()),
+		WithHeaders(headers...),
+		WithSpinnerFinalText("Done!", log.LogTypeSUCCESS))
 	assert.NoError(t, err)
 	assert.NotNil(t, ows)
 
-	// Test creating an OutputWriterSpinner with spinner options without a spinner
-	opts = OutputWriterSpinnerOptions{
-		SpinnerOptions: []OutputWriterSpinnerOption{WithSpinnerFinalText("Done!", log.LogTypeSUCCESS)},
-	}
-	ows, err = NewOutputWriterSpinnerWithSpinnerOptions(&output, "table", spinnerText, false, opts, headers...)
+	ows, err = NewOutputWriterSpinner(WithOutputStream(&output),
+		WithOutputFormat(TableOutputType),
+		WithSpinnerText(spinnerText),
+		WithHeaders(headers...),
+		WithSpinnerFinalText("Done!", log.LogTypeSUCCESS))
 	assert.NoError(t, err)
 	assert.NotNil(t, ows)
 
-	// Test creating an OutputWriterSpinner with unsupported output format
-	opts = OutputWriterSpinnerOptions{}
-	ows, err = NewOutputWriterSpinnerWithSpinnerOptions(&output, "unsupported", spinnerText, true, opts, headers...)
+	ows, err = NewOutputWriterSpinner(WithOutputStream(&output),
+		WithOutputFormat("unsupported"),
+		WithSpinnerText(spinnerText),
+		WithSpinnerStarted(),
+		WithHeaders(headers...))
 	assert.NoError(t, err)
 	assert.NotNil(t, ows)
 }