all: add Windows support

Author: changkun

.github/workflows/clipboard.yml

@@ -19,7 +19,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest] # windows-latest
+        os: [ubuntu-latest, macos-latest, windows-latest]
 
     steps:
 

README.md

@@ -6,32 +6,39 @@ cross platform clipboard package in Go
 import "golang.design/x/clipboard"
 ```
 
-## Dependency
+## Features
 
-- Linux users: require X: `apt install -y libx11-dev` or `xorg-dev`
-- macOS users: require Cgo, no dependency
-- Windows users: unsupported yet
+- Cross platform supports: macOS, Unix-like (X11), and Windows
+- Copy/paste UTF-8 text
+- Copy/paste PNG encoded images
+- Command `gclip` as a demo application
 
 ## API Usage
 
-Quick start:
+Package `clipboard` provides three major APIs for manipulating the
+clipboard: `Read`, `Write`, and `Watch`. The most common operations are
+`Read` and `Write`. To use them, you can:
 
 ```go
-// write/read text format data of the clipboard
+// write/read text format data of the clipboard, and
+// the byte buffer regarding the text are UTF8 encoded.
 clipboard.Write(clipboard.FmtText, []byte("text data"))
 clipboard.Read(clipboard.FmtText)
 
-// write/read image format data of the clipboard, assume
-// image bytes are png encoded.
+// write/read image format data of the clipboard, and
+// the byte buffer regarding the image are PNG encoded.
 clipboard.Write(clipboard.FmtImage, []byte("image data"))
 clipboard.Read(clipboard.FmtImage)
 ```
 
-In addition, the `clipboard.Write` API returns a channel that
-can receive an empty struct as a signal that indicates the
-corresponding write call to the clipboard is outdated, meaning
-the clipboard has been overwritten by others and the previously
-written data is lost. For instance:
+Note that read/write regarding image format assumes that the bytes are
+PNG encoded since it serves the alpha blending purpose that might be
+used in other graphical software.
+
+In addition, `clipboard.Write` returns a channel that can receive an
+empty struct as a signal, which indicates the corresponding write call
+to the clipboard is outdated, meaning the clipboard has been overwritten
+by others and the previously written data is lost. For instance:
 
 ```go
 changed := clipboard.Write(clipboard.FmtText, []byte("text data"))
@@ -42,7 +49,7 @@ case <-changed:
 }
 ```
 
-You can ignore the reutrning channel if you don't need this type of
+You can ignore the returning channel if you don't need this type of
 notification. Furthermore, when you need more than just knowing whether
 clipboard data is changed, use the watcher API:
 
@@ -95,15 +102,29 @@ background using a shell `&` operator, for example:
 $ cat x.txt | gclip -copy &
 ```
 
-## Additional Notes
+## Platform Specific Details
+
+This package spent efforts to provide cross platform abstraction regarding
+accessing system clipboards, but here are a few details you might need to know.
+
+### Dependency
+
+- Unix-like users: require X11 dev package. For instance, Linux users should install `libx11-dev` or `xorg-dev` or `libX11-devel` to access X window system.
+- macOS users: require Cgo, no dependency
+- Windows users: no Cgo, no dependency
+
+### Screenshot
 
-In general, to put image data to system clipboard, there are system level shortcuts:
+In general, when you need test your implementation regarding images,
+There are system level shortcuts to put screenshot image into your system clipboard:
 
-- On macOS, using shortcut `Ctrl+Shift+Cmd+4`
-- On Linux/Ubuntu, using `Ctrl+Shift+PrintScreen`
+- On macOS, use `Ctrl+Shift+Cmd+4`
+- On Linux/Ubuntu, use `Ctrl+Shift+PrintScreen`
+- On Windows, use `Shift+Win+s`
 
-The package supports read/write plain text or PNG encoded image data.
-The other types of data are not supported yet, i.e. undefined behavior.
+As described in the API documentation, the package supports read/write
+UTF8 encoded plain text or PNG encoded image data. Thus,
+the other types of data are not supported yet, i.e. undefined behavior.
 
 ## License
 

clipboard.go

@@ -4,21 +4,73 @@
 //
 // Written by Changkun Ou <changkun.de>
 
+/*
+Package clipboard provides three major APIs for manipulating the
+clipboard: `Read`, `Write`, and `Watch`. The most common operations are
+`Read` and `Write`. To use them:
+
+	// write/read text format data of the clipboard, and
+	// the byte buffer regarding the text are UTF8 encoded.
+	clipboard.Write(clipboard.FmtText, []byte("text data"))
+	clipboard.Read(clipboard.FmtText)
+
+	// write/read image format data of the clipboard, and
+	// the byte buffer regarding the image are PNG encoded.
+	clipboard.Write(clipboard.FmtImage, []byte("image data"))
+	clipboard.Read(clipboard.FmtImage)
+
+Note that read/write regarding image format assumes that the bytes are
+PNG encoded since it serves the alpha blending purpose that might be
+used in other graphical software.
+
+In addition, `clipboard.Write` returns a channel that can receive an
+empty struct as a signal, which indicates the corresponding write call
+to the clipboard is outdated, meaning the clipboard has been overwritten
+by others and the previously written data is lost. For instance:
+
+	changed := clipboard.Write(clipboard.FmtText, []byte("text data"))
+
+	select {
+	case <-changed:
+		println(`"text data" is no longer available from clipboard.`)
+	}
+
+You can ignore the returning channel if you don't need this type of
+notification. Furthermore, when you need more than just knowing whether
+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))
+	}
+*/
 package clipboard // import "golang.design/x/clipboard"
 
 import (
 	"context"
+	"errors"
+	"fmt"
+	"os"
 	"sync"
 )
 
-// Format represents the MIME type of clipboard data.
+var (
+	// activate only for running tests.
+	debug               = false
+	errUnavailable      = errors.New("clipboard unavailable")
+	errUnsupported      = errors.New("unsupported format")
+	errInvalidOperation = errors.New("invalid operation")
+)
+
+// Format represents the format of clipboard data.
 type Format int
 
 // All sorts of supported clipboard data
 const (
-	// FmtText indicates plain text MIME format
+	// FmtText indicates plain text clipboard format
 	FmtText Format = iota
-	// FmtImage indicates image/png MIME format
+	// FmtImage indicates image/png clipboard format
 	FmtImage
 )
 
@@ -27,33 +79,44 @@ const (
 // guarantee one read at a time.
 var lock = sync.Mutex{}
 
-// Read reads and returns the clipboard data.
+// Read returns a chunk of bytes of the clipboard data if it presents
+// in the desired format t presents. Otherwise, it returns nil.
 func Read(t Format) []byte {
 	lock.Lock()
 	defer lock.Unlock()
 
-	return read(t)
+	buf, err := read(t)
+	if err != nil {
+		if debug {
+			fmt.Fprintf(os.Stderr, "read clipboard err: %v\n", err)
+		}
+		return nil
+	}
+	return buf
 }
 
-// Write writes a given buffer to the clipboard.
-// The returned channel can receive an empty struct as signal that
-// indicates the clipboard has been overwritten from this write.
-//
-// If the MIME type indicates an image, then the given buf assumes
+// Write writes a given buffer to the clipboard in a specified format.
+// Write returned a receive-only channel can receive an empty struct
+// as a signal, which indicates the clipboard has been overwritten from
+// this write.
+// If format t indicates an image, then the given buf assumes
 // the image data is PNG encoded.
 func Write(t Format, buf []byte) <-chan struct{} {
 	lock.Lock()
 	defer lock.Unlock()
 
-	ok, changed := write(t, buf)
-	if !ok {
+	changed, err := write(t, buf)
+	if err != nil {
+		if debug {
+			fmt.Fprintf(os.Stderr, "write to clipboard err: %v\n", err)
+		}
 		return nil
 	}
 	return changed
 }
 
 // Watch returns a receive-only channel that received the clipboard data
-// if any changes of clipboard data in the desired format happends.
+// whenever any change of clipboard data in the desired format happens.
 //
 // The returned channel will be closed if the given context is canceled.
 func Watch(ctx context.Context, t Format) <-chan []byte {

clipboard_darwin.go

@@ -28,7 +28,7 @@ import (
 	"unsafe"
 )
 
-func read(t Format) (buf []byte) {
+func read(t Format) (buf []byte, err error) {
 	var (
 		data unsafe.Pointer
 		n    C.uint
@@ -40,18 +40,18 @@ func read(t Format) (buf []byte) {
 		n = C.clipboard_read_image(&data)
 	}
 	if data == nil {
-		return nil
+		return nil, errUnavailable
 	}
 	defer C.free(unsafe.Pointer(data))
 	if n == 0 {
-		return nil
+		return nil, nil
 	}
-	return C.GoBytes(data, C.int(n))
+	return C.GoBytes(data, C.int(n)), nil
 }
 
 // write writes the given data to clipboard and
 // returns true if success or false if failed.
-func write(t Format, buf []byte) (bool, <-chan struct{}) {
+func write(t Format, buf []byte) (<-chan struct{}, error) {
 	var ok C.int
 	switch t {
 	case FmtText:
@@ -70,7 +70,7 @@ func write(t Format, buf []byte) (bool, <-chan struct{}) {
 		}
 	}
 	if ok != 0 {
-		return false, nil
+		return nil, errInvalidOperation
 	}
 
 	// use unbuffered data to prevent goroutine leak
@@ -88,15 +88,15 @@ func write(t Format, buf []byte) (bool, <-chan struct{}) {
 			}
 		}
 	}()
-	return true, changed
+	return changed, nil
 }
 
 func watch(ctx context.Context, t Format) <-chan []byte {
 	recv := make(chan []byte, 1)
+	// not sure if we are too slow or the user too fast :)
+	ti := time.NewTicker(time.Second)
+	lastCount := C.long(C.clipboard_change_count())
 	go func() {
-		// not sure if we are too slow or the user too fast :)
-		ti := time.NewTicker(time.Second)
-		lastCount := C.long(C.clipboard_change_count())
 		for {
 			select {
 			case <-ctx.Done():

clipboard_linux.c

@@ -141,7 +141,7 @@ unsigned long read_data(XSelectionEvent *sev, Atom sel, Atom prop, Atom target,
     return size * sizeof(char);
 }
 
-// clipboard_read reads the clipboard selection in given mime type typ.
+// clipboard_read reads the clipboard selection in given format typ.
 // the readed bytes is written into buf and returns the size of the buffer.
 //
 // The caller of this function should responsible for the free of the buf.