Add WithStderr (fixes #128, fixes #146)

Co-authored-by: "Masci, Richard (rx7322)" <rx7322@us.att.com>
Co-authored-by: Jesse Lang <jdlang@spscommerce.com>
Co-authored-by: Nithin Chintala <nithin.chintala@schrodinger.com>
Co-authored-by: floydwch <floydwch@gmail.com>

Author: 5 people

README.md

@@ -336,7 +336,7 @@ Sinks are methods that return some data from a pipe, ending the pipeline and ext
 
 | Version | New |
 | ----------- | ------- |
-| v0.22.0 | [`Tee`](https://pkg.go.dev/github.com/bitfield/script#Pipe.Tee) |
+| v0.22.0 | [`Tee`](https://pkg.go.dev/github.com/bitfield/script#Pipe.Tee), [`WithStderr`](https://pkg.go.dev/github.com/bitfield/script#Pipe.WithStderr) |
 | v0.21.0 | HTTP support: [`Do`](https://pkg.go.dev/github.com/bitfield/script#Pipe.Do), [`Get`](https://pkg.go.dev/github.com/bitfield/script#Pipe.Get), [`Post`](https://pkg.go.dev/github.com/bitfield/script#Pipe.Post) |
 | v0.20.0 | [`JQ`](https://pkg.go.dev/github.com/bitfield/script#Pipe.JQ) |
 

script.go

@@ -27,9 +27,9 @@ import (
 // Pipe represents a pipe object with an associated [ReadAutoCloser].
 type Pipe struct {
 	// Reader is the underlying reader.
-	Reader     ReadAutoCloser
-	stdout     io.Writer
-	httpClient *http.Client
+	Reader         ReadAutoCloser
+	stdout, stderr io.Writer
+	httpClient     *http.Client
 
 	// because pipe stages are concurrent, protect 'err'
 	mu  *sync.Mutex
@@ -369,8 +369,9 @@ func (p *Pipe) Error() error {
 }
 
 // Exec runs cmdLine as an external command, sending it the contents of the
-// pipe as input, and produces the command's combined output. The effect of
-// this is to filter the contents of the pipe through the external command.
+// pipe as input, and produces the command's standard output (see below for
+// error output). The effect of this is to filter the contents of the pipe
+// through the external command.
 //
 // # Error handling
 //
@@ -381,6 +382,10 @@ func (p *Pipe) Error() error {
 // because [Pipe.String] is a no-op if the pipe's error status is set, if you
 // want output you will need to reset the error status before calling
 // [Pipe.String].
+//
+// If the command writes to its standard error stream, this will also go to the
+// pipe, along with its standard output. However, the standard error text can
+// instead be redirected to a supplied writer, using [Pipe.WithStderr].
 func (p *Pipe) Exec(cmdLine string) *Pipe {
 	return p.Filter(func(r io.Reader, w io.Writer) error {
 		args, ok := shell.Split(cmdLine) // strings.Fields doesn't handle quotes
@@ -391,9 +396,12 @@ func (p *Pipe) Exec(cmdLine string) *Pipe {
 		cmd.Stdin = r
 		cmd.Stdout = w
 		cmd.Stderr = w
+		if p.stderr != nil {
+			cmd.Stderr = p.stderr
+		}
 		err := cmd.Start()
 		if err != nil {
-			fmt.Fprintln(w, err)
+			fmt.Fprintln(cmd.Stderr, err)
 			return err
 		}
 		return cmd.Wait()
@@ -429,14 +437,17 @@ func (p *Pipe) ExecForEach(cmdLine string) *Pipe {
 			cmd := exec.Command(args[0], args[1:]...)
 			cmd.Stdout = w
 			cmd.Stderr = w
+			if p.stderr != nil {
+				cmd.Stderr = p.stderr
+			}
 			err = cmd.Start()
 			if err != nil {
-				fmt.Fprintln(w, err)
+				fmt.Fprintln(cmd.Stderr, err)
 				continue
 			}
 			err = cmd.Wait()
 			if err != nil {
-				fmt.Fprintln(w, err)
+				fmt.Fprintln(cmd.Stderr, err)
 				continue
 			}
 		}
@@ -886,6 +897,14 @@ func (p *Pipe) WithReader(r io.Reader) *Pipe {
 	return p
 }
 
+// WithStderr redirects the standard error output for commands run via
+// [Pipe.Exec] or [Pipe.ExecForEach] to the writer w, instead of going to the
+// pipe as it normally would.
+func (p *Pipe) WithStderr(w io.Writer) *Pipe {
+	p.stderr = w
+	return p
+}
+
 // WithStdout sets the pipe's standard output to the writer w, instead of the
 // default [os.Stdout].
 func (p *Pipe) WithStdout(w io.Writer) *Pipe {

script_test.go

@@ -343,6 +343,36 @@ func TestExecForEach_ErrorsOnUnbalancedQuotes(t *testing.T) {
 	}
 }
 
+func TestExecForEach_SendsStderrOutputToPipeStderr(t *testing.T) {
+	t.Parallel()
+	buf := new(bytes.Buffer)
+	out, err := script.Echo("go").WithStderr(buf).ExecForEach("{{.}}").String()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if out != "" {
+		t.Fatalf("unexpected output: %q", out)
+	}
+	if !strings.Contains(buf.String(), "Usage") {
+		t.Errorf("want stderr output containing the word 'Usage', got %q", buf.String())
+	}
+}
+
+func TestExecSendsStderrOutputToPipeStderr(t *testing.T) {
+	t.Parallel()
+	buf := new(bytes.Buffer)
+	out, err := script.NewPipe().WithStderr(buf).Exec("go").String()
+	if err == nil {
+		t.Fatal("want error when command returns a non-zero exit status")
+	}
+	if out != "" {
+		t.Fatalf("unexpected output: %q", out)
+	}
+	if !strings.Contains(buf.String(), "Usage") {
+		t.Errorf("want stderr output containing the word 'Usage', got %q", buf.String())
+	}
+}
+
 func TestFilterByCopyPassesInputThroughUnchanged(t *testing.T) {
 	t.Parallel()
 	p := script.Echo("hello").Filter(func(r io.Reader, w io.Writer) error {
@@ -1157,7 +1187,7 @@ func TestExecRunsGoWithNoArgsAndGetsUsageMessagePlusErrorExitStatus2(t *testing.
 		t.Error("want error when command returns a non-zero exit status")
 	}
 	if !strings.Contains(output, "Usage") {
-		t.Errorf("want output containing the word 'usage', got %q", output)
+		t.Errorf("want output containing the word 'Usage', got %q", output)
 	}
 	want := 2
 	got := p.ExitStatus()
@@ -1177,7 +1207,7 @@ func TestExecRunsGoHelpAndGetsUsageMessage(t *testing.T) {
 		t.Fatal(err)
 	}
 	if !strings.Contains(output, "Usage") {
-		t.Fatalf("want output containing the word 'usage', got %q", output)
+		t.Fatalf("want output containing the word 'Usage', got %q", output)
 	}
 }
 
@@ -2245,6 +2275,14 @@ func ExamplePipe_Tee_writers() {
 	// hello
 }
 
+func ExamplePipe_WithStderr() {
+	buf := new(bytes.Buffer)
+	script.NewPipe().WithStderr(buf).Exec("go").Wait()
+	fmt.Println(strings.Contains(buf.String(), "Usage"))
+	// Output:
+	// true
+}
+
 func ExampleSlice() {
 	input := []string{"1", "2", "3"}
 	script.Slice(input).Stdout()