clipboard: make Watch variadic and tag values with their format (#89) (#124)

* clipboard: make Watch variadic and tag values with their format (#89)

Watch now accepts zero or more formats and returns <-chan Data, where each
value carries the Format it was detected in. A single call can observe
multiple formats at once; passing no format watches all supported ones
(FmtText, FmtImage). This unifies the requested watch-all ergonomics into
the existing Watch rather than adding a parallel WatchAll, by treating the
single-format watcher as the degenerate case of the general one.

BREAKING CHANGE: the element type changes from []byte to Data. Callers
migrate by reading data.Bytes (and may inspect data.Format). To ship in
v0.8.0.

Closes #89.

* clipboard: fix multi-format watch test on Linux (clear + distinct payload)

The Linux watcher emits only when the polled bytes differ from what it
read at startup (clipboard_linux.go byte-equality check), unlike the
macOS change-counter and Windows sequence-number paths. The test reused
the same text payload that the preceding TestClipboardWatch leaves on the
clipboard, so the text watcher initialized last to those bytes and never
saw a change (text=false image=true on ubuntu CI). Clear the clipboard
before watching and use a distinct payload.

Author: changkun

README.md

@@ -69,7 +69,23 @@ clipboard data is changed, use the watcher API:
 ch := clipboard.Watch(context.TODO(), clipboard.FmtText)
 for data := range ch {
       // print out clipboard data whenever it is changed
-      println(string(data))
+      println(string(data.Bytes))
+}
+```
+
+`Watch` is variadic and tags each value with the format it was detected
+in, so a single call can observe more than one format at once (pass no
+format to watch all supported ones):
+
+```go
+ch := clipboard.Watch(context.TODO())
+for data := range ch {
+      switch data.Format {
+      case clipboard.FmtText:
+            println("text:", string(data.Bytes))
+      case clipboard.FmtImage:
+            println("image bytes:", len(data.Bytes))
+      }
 }
 ```
 

clipboard.go

@@ -50,7 +50,21 @@ clipboard data is changed, use the watcher API:
 	ch := clipboard.Watch(context.TODO(), clipboard.FmtText)
 	for data := range ch {
 		// print out clipboard data whenever it is changed
-		println(string(data))
+		println(string(data.Bytes))
+	}
+
+Watch is variadic and each value is tagged with its format, so a single
+call can observe more than one format at once (passing no format watches
+all supported ones):
+
+	ch := clipboard.Watch(context.TODO())
+	for data := range ch {
+		switch data.Format {
+		case clipboard.FmtText:
+			println("text:", string(data.Bytes))
+		case clipboard.FmtImage:
+			println("image bytes:", len(data.Bytes))
+		}
 	}
 
 # Platform-specific caveats
@@ -173,10 +187,45 @@ func Write(t Format, buf []byte) <-chan struct{} {
 	return changed
 }
 
-// Watch returns a receive-only channel that received the clipboard data
-// whenever any change of clipboard data in the desired format happens.
+// Data is a single observed clipboard change: the format the change was
+// detected in, together with the raw bytes encoded the same way Read
+// returns them (UTF-8 for FmtText, PNG for FmtImage).
+type Data struct {
+	Format Format
+	Bytes  []byte
+}
+
+// Watch returns a receive-only channel that receives the clipboard data
+// whenever any change of clipboard data in one of the desired formats
+// happens. Each received value carries the format it was detected in, so a
+// single Watch call can observe multiple formats at once. If no format is
+// given, all supported formats (FmtText and FmtImage) are observed.
 //
-// The returned channel will be closed if the given context is canceled.
-func Watch(ctx context.Context, t Format) <-chan []byte {
-	return watch(ctx, t)
+// The returned channel will be closed once the given context is canceled.
+func Watch(ctx context.Context, t ...Format) <-chan Data {
+	if len(t) == 0 {
+		t = []Format{FmtText, FmtImage}
+	}
+
+	out := make(chan Data)
+	var wg sync.WaitGroup
+	for _, f := range t {
+		in := watch(ctx, f)
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for b := range in {
+				select {
+				case out <- Data{Format: f, Bytes: b}:
+				case <-ctx.Done():
+					return
+				}
+			}
+		}()
+	}
+	go func() {
+		wg.Wait()
+		close(out)
+	}()
+	return out
 }

clipboard_test.go

@@ -285,10 +285,13 @@ loop:
 				}
 				break loop
 			}
-			if !bytes.Equal(data, want) {
-				t.Fatalf("received data from watch mismatch, want: %v, got %v", string(want), string(data))
+			if !bytes.Equal(data.Bytes, want) {
+				t.Fatalf("received data from watch mismatch, want: %v, got %v", string(want), string(data.Bytes))
 			}
-			lastRead = data
+			if data.Format != clipboard.FmtText {
+				t.Fatalf("received data from watch has wrong format, want: %v, got %v", clipboard.FmtText, data.Format)
+			}
+			lastRead = data.Bytes
 		}
 	}
 	// After the context is cancelled, watch must close the channel (per the
@@ -308,6 +311,87 @@ loop:
 	}
 }
 
+// TestClipboardWatchMultiFormat exercises the variadic Watch: a single call
+// observes more than one format at once and each received value is tagged with
+// the format it was detected in. Watching with no format argument observes all
+// supported formats. This test cannot compile against the old single-format
+// Watch(ctx, Format) <-chan []byte signature.
+func TestClipboardWatchMultiFormat(t *testing.T) {
+	if degradesWithoutCgo() {
+		if val, ok := os.LookupEnv("CGO_ENABLED"); ok && val == "0" {
+			t.Skip("CGO_ENABLED is set to 0")
+		}
+	}
+
+	img, err := os.ReadFile("tests/testdata/clipboard.png")
+	if err != nil {
+		t.Fatalf("failed to read test image: %v", err)
+	}
+	// Use a payload distinct from other tests and clear the clipboard first:
+	// the Linux watcher emits only when the bytes differ from what it read at
+	// startup, so a leftover identical string would suppress the text event.
+	wantText := []byte("golang.design/x/clipboard#89-watch-multiformat")
+	clipboard.Write(clipboard.FmtText, []byte(""))
+
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second*20)
+	defer cancel()
+
+	// Watch all supported formats through a single call.
+	changed := clipboard.Watch(ctx)
+
+	// The clipboard holds only the most recently written format and the
+	// platform watchers poll once per second, so alternate the two formats
+	// on a tick slower than that poll interval. Writing both back-to-back
+	// would let the second clobber the first before any watcher observes it.
+	go func(ctx context.Context) {
+		tk := time.NewTicker(time.Millisecond * 1300)
+		defer tk.Stop()
+		writeImage := false
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-tk.C:
+				if writeImage {
+					clipboard.Write(clipboard.FmtImage, img)
+				} else {
+					clipboard.Write(clipboard.FmtText, wantText)
+				}
+				writeImage = !writeImage
+			}
+		}
+	}(ctx)
+
+	var sawText, sawImage bool
+	for !(sawText && sawImage) {
+		select {
+		case <-ctx.Done():
+			t.Fatalf("did not observe both formats from a single Watch: text=%v image=%v", sawText, sawImage)
+		case data, ok := <-changed:
+			if !ok {
+				t.Fatalf("watch channel closed before observing both formats: text=%v image=%v", sawText, sawImage)
+			}
+			switch data.Format {
+			case clipboard.FmtText:
+				if !bytes.Equal(data.Bytes, wantText) {
+					t.Fatalf("text event payload mismatch, want %q got %q", wantText, data.Bytes)
+				}
+				sawText = true
+			case clipboard.FmtImage:
+				// Image bytes round-trip through platform conversions
+				// (DIB/TIFF), so assert the payload is a decodable PNG
+				// rather than byte-identical to the source.
+				if _, err := png.Decode(bytes.NewReader(data.Bytes)); err != nil {
+					t.Fatalf("image event payload is not a valid PNG: %v", err)
+				}
+				sawImage = true
+			default:
+				t.Fatalf("watch reported an unexpected format: %v", data.Format)
+			}
+		}
+	}
+}
+
 func BenchmarkClipboard(b *testing.B) {
 	b.Run("text", func(b *testing.B) {
 		data := []byte("golang.design/x/clipboard")

example_test.go

@@ -50,7 +50,7 @@ func ExampleWatch() {
 	go func(ctx context.Context) {
 		clipboard.Write(clipboard.FmtText, []byte("你好，world"))
 	}(ctx)
-	fmt.Println(string(<-changed))
+	fmt.Println(string((<-changed).Bytes))
 	// Output:
 	// 你好，world
 }