Add Tee filter (fixes #145)

Co-authored-by: Hans Raaf <hara@oderwat.de>
Co-authored-by: "Masci, Richard (rx7322)" <rx7322@us.att.com>
Co-authored-by: Ryan <Emailryanmay@gmail.com>
Co-authored-by: Gerard Webb <53147028+gedw99@users.noreply.github.com>

Author: 5 people

README.md

@@ -48,6 +48,7 @@ If you're already familiar with shell scripting and the Unix toolset, here is a
 | `sed`              | [`Replace`](https://pkg.go.dev/github.com/bitfield/script#Pipe.Replace) / [`ReplaceRegexp`](https://pkg.go.dev/github.com/bitfield/script#Pipe.ReplaceRegexp) |
 | `sha256sum`        | [`SHA256Sum`](https://pkg.go.dev/github.com/bitfield/script#Pipe.SHA256Sum) / [`SHA256Sums`](https://pkg.go.dev/github.com/bitfield/script#Pipe.SHA256Sums) |
 | `tail`             | [`Last`](https://pkg.go.dev/github.com/bitfield/script#Pipe.Last) |
+| `tee`              | [`Tee`](https://pkg.go.dev/github.com/bitfield/script#Pipe.Tee) |
 | `uniq -c`          | [`Freq`](https://pkg.go.dev/github.com/bitfield/script#Pipe.Freq) |
 | `wc -l`            | [`CountLines`](https://pkg.go.dev/github.com/bitfield/script#Pipe.CountLines) |
 | `xargs`            | [`ExecForEach`](https://pkg.go.dev/github.com/bitfield/script#Pipe.ExecForEach) |
@@ -102,6 +103,12 @@ What's that? You want to append that output to a file instead of printing it to
 script.Args().Concat().Match("Error").First(10).AppendFile("/var/log/errors.txt")
 ```
 
+And if we'd like to send the output to the terminal *as well as* to the file, we can do that:
+
+```go
+script.Echo("data").Tee().AppendFile("data.txt")
+```
+
 We're not limited to getting data only from files or standard input. We can get it from HTTP requests too:
 
 ```go
@@ -304,6 +311,7 @@ Filters are methods on an existing pipe that also return a pipe, allowing you to
 | [`Replace`](https://pkg.go.dev/github.com/bitfield/script#Pipe.Replace) | matching text replaced with given string |
 | [`ReplaceRegexp`](https://pkg.go.dev/github.com/bitfield/script#Pipe.ReplaceRegexp) | matching text replaced with given string |
 | [`SHA256Sums`](https://pkg.go.dev/github.com/bitfield/script#Pipe.SHA256Sums) | SHA-256 hashes of each listed file |
+| [`Tee`](https://pkg.go.dev/github.com/bitfield/script#Pipe.Tee) | input copied to supplied writers |
 
 Note that filters run concurrently, rather than producing nothing until each stage has fully read its input. This is convenient for executing long-running comands, for example. If you do need to wait for the pipeline to complete, call [`Wait`](https://pkg.go.dev/github.com/bitfield/script#Pipe.Wait).
 
@@ -328,6 +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.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

@@ -834,6 +834,23 @@ func (p *Pipe) String() (string, error) {
 	return string(data), p.Error()
 }
 
+// Tee copies the pipe's contents to each of the supplied writers, like Unix
+// tee(1). If no writers are supplied, the default is the pipe's standard
+// output.
+func (p *Pipe) Tee(writers ...io.Writer) *Pipe {
+	if p.Error() != nil {
+		return p
+	}
+	if len(writers) == 0 {
+		writers = []io.Writer{p.stdout}
+	}
+	teeWriter := io.MultiWriter(writers...)
+	return p.Filter(func(r io.Reader, w io.Writer) error {
+		_, err := io.Copy(w, io.TeeReader(r, teeWriter))
+		return err
+	})
+}
+
 // Wait reads the pipe to completion and discards the result. This is mostly
 // useful for waiting until concurrent filters have completed (see
 // [Pipe.Filter]).

script_test.go

@@ -1104,6 +1104,39 @@ func TestSHA256Sums_OutputsCorrectHashForEachSpecifiedFile(t *testing.T) {
 	}
 }
 
+func TestTeeUsesConfiguredStdoutAsDefault(t *testing.T) {
+	t.Parallel()
+	buf := new(bytes.Buffer)
+	_, err := script.Echo("hello").WithStdout(buf).Tee().String()
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := "hello"
+	got := buf.String()
+	if got != want {
+		t.Errorf("want %q, got %q", want, got)
+	}
+}
+
+func TestTeeWritesDataToSuppliedWritersAsWellAsToPipe(t *testing.T) {
+	t.Parallel()
+	buf1, buf2 := new(bytes.Buffer), new(bytes.Buffer)
+	got, err := script.Echo("hello world").Tee(buf1, buf2).String()
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := "hello world"
+	if want != got {
+		t.Errorf("want %q on pipe, got %q", want, got)
+	}
+	if want != buf1.String() {
+		t.Errorf("want %q on writer 1, got %q", want, buf1.String())
+	}
+	if want != buf2.String() {
+		t.Errorf("want %q on writer 2, got %q", want, buf2.String())
+	}
+}
+
 func TestExecErrorsWhenTheSpecifiedCommandDoesNotExist(t *testing.T) {
 	t.Parallel()
 	p := script.Exec("doesntexist")
@@ -2186,6 +2219,32 @@ func ExamplePipe_String() {
 	// world
 }
 
+func ExamplePipe_Tee_stdout() {
+	s, err := script.Echo("hello\n").Tee().String()
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println(s)
+	// Output:
+	// hello
+	// hello
+}
+
+func ExamplePipe_Tee_writers() {
+	buf1, buf2 := new(bytes.Buffer), new(bytes.Buffer)
+	s, err := script.Echo("hello\n").Tee(buf1, buf2).String()
+	if err != nil {
+		panic(err)
+	}
+	fmt.Print(s)
+	fmt.Print(buf1.String())
+	fmt.Print(buf2.String())
+	// Output:
+	// hello
+	// hello
+	// hello
+}
+
 func ExampleSlice() {
 	input := []string{"1", "2", "3"}
 	script.Slice(input).Stdout()