clipboard

package
v0.0.0-...-0e33c82 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 12, 2025 License: MIT Imports: 7 Imported by: 0

README

Clipboard Package

A unified Go library for copying text to various clipboard targets including tmux buffers, system clipboard, and remote terminals via OSC52.

Features

  • Multi-target support: Copy to tmux buffer, system clipboard, and remote terminals
  • OSC52 integration: Copy to clipboard over SSH and remote sessions
  • Cross-platform: Supports macOS, Linux, and Windows
  • Flexible API: Choose specific targets or use all available ones

Quick Start

package main

import (
    "log"
    "github.com/Hanaasagi/magonote/pkg/clipboard"
)

func main() {
    // Copy to all available targets
    err := clipboard.Copy("Hello, World!")
    if err != nil {
        log.Fatal(err)
    }
}

API Overview

Basic Usage
// Copy to all available clipboard targets
err := clipboard.Copy("text")

// Copy to specific targets
err := clipboard.CopyToTmux("tmux only")
err := clipboard.CopyToSystem("system only") 
err := clipboard.CopyWithOSC52("remote via OSC52")
Advanced Configuration
// Create clipboard with custom options
c := clipboard.New(
    clipboard.WithTmux(true),        // Enable tmux buffer
    clipboard.WithSystem(false),     // Disable system clipboard
    clipboard.WithOSC52(true),       // Enable OSC52 sequences
    clipboard.WithOutput(os.Stderr), // Set OSC52 output destination
)

err := c.Copy("configured copy")
Individual Writers
// Tmux-only writer
tmuxWriter := clipboard.NewTmuxWriter()
err := tmuxWriter.Write("tmux content")

// System-only writer  
systemWriter := clipboard.NewSystemWriter()
err := systemWriter.Write("system content")

// OSC52-only writer
osc52Writer := clipboard.NewOSC52Writer(os.Stderr)
err := osc52Writer.Write("remote content")

Clipboard Targets

Tmux Buffer

Copies text to the tmux paste buffer. Works when running inside a tmux session.

  • Uses tmux load-buffer command
  • Automatically detects tmux environment via $TMUX variable
  • Clears buffer when copying empty string
System Clipboard

Copies to the operating system clipboard using platform-specific tools:

  • macOS: pbcopy
  • Linux: wl-copy (Wayland), xclip, xsel (X11)
  • Windows: clip
OSC52 Terminal Sequences

Copies via ANSI OSC52 escape sequences. Works over SSH and remote connections.

  • Encodes text in base64
  • Sends escape sequence to terminal
  • Automatically wraps in tmux DCS passthrough when in tmux
  • Ideal for remote sessions where system tools aren't available

Environment Detection

// Check what's available
available := clipboard.Available()
fmt.Printf("Tmux: %v\n", available["tmux"])
fmt.Printf("System: %v\n", available["system"])  
fmt.Printf("OSC52: %v\n", available["osc52"])

// Individual checks
if clipboard.IsTmuxSession() {
    // Running in tmux
}

if clipboard.HasSystemClipboard() {
    // System tools available
}

Remote SSH Usage

For remote SSH sessions, OSC52 is typically the best option:

// Detect remote session
isRemote := os.Getenv("SSH_CLIENT") != "" || os.Getenv("SSH_TTY") != ""

var c *clipboard.Clipboard
if isRemote {
    // Prefer OSC52 for remote sessions
    c = clipboard.New(
        clipboard.WithOSC52(true),
        clipboard.WithSystem(false),
        clipboard.WithTmux(clipboard.IsTmuxSession()),
    )
} else {
    // Use all methods for local sessions
    c = clipboard.New()
}

err := c.Copy("remote clipboard content")

Custom Writers

Implement the Writer interface for custom clipboard destinations:

type Writer interface {
    Write(text string) error
}

type CustomWriter struct{}

func (w *CustomWriter) Write(text string) error {
    // Custom clipboard logic
    return nil
}

License

MIT License - see LICENSE file for details.

Documentation

Overview

Example (RemoteSSH)

Example: Remote SSH session clipboard integration 

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/Hanaasagi/magonote/pkg/clipboard"
)

func main() {
	// In a remote SSH session, you typically want OSC52
	// which works through terminal escape sequences

	// Check if we're in a remote session (simplified check)
	isRemote := os.Getenv("SSH_CLIENT") != "" || os.Getenv("SSH_TTY") != ""

	var c *clipboard.Clipboard
	if isRemote {
		// For remote sessions, prefer OSC52 over system tools
		c = clipboard.New(
			clipboard.WithOSC52(true),
			clipboard.WithSystem(false),
			clipboard.WithTmux(clipboard.IsTmuxSession()),
		)
	} else {
		// For local sessions, use all available methods
		c = clipboard.New()
	}

	err := c.Copy("Remote clipboard content")
	if err != nil {
		log.Printf("Remote copy failed: %v", err)
	}

	fmt.Println("Configured for remote/local session")
}

Output:

Configured for remote/local session

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Available 

func Available() map[string]bool

Available returns which clipboard targets are available

Example 
package main

import (
	"fmt"

	"github.com/Hanaasagi/magonote/pkg/clipboard"
)

func main() {
	// Check which clipboard targets are available
	available := clipboard.Available()

	fmt.Printf("Tmux available: %v\n", available["tmux"])
	fmt.Printf("System available: %v\n", available["system"])
	fmt.Printf("OSC52 available: %v\n", available["osc52"])

	// Output will vary based on environment
}

func Copy 

func Copy(text string) error

Copy is a convenience function for quick clipboard operations

Example 
package main

import (
	"fmt"
	"log"

	"github.com/Hanaasagi/magonote/pkg/clipboard"
)

func main() {
	// Quick way to copy text using default settings
	err := clipboard.Copy("Quick copy!")
	if err != nil {
		log.Printf("Copy failed: %v", err)
	}

	fmt.Println("Quick copy completed")
}

Output:

Quick copy completed

func CopyToSystem 

func CopyToSystem(text string) error

CopyToSystem is a convenience function for system-only copying

Example 
package main

import (
	"fmt"
	"log"

	"github.com/Hanaasagi/magonote/pkg/clipboard"
)

func main() {
	// Copy only to system clipboard
	err := clipboard.CopyToSystem("System only")
	if err != nil {
		log.Printf("System copy failed: %v", err)
	}

	fmt.Println("Copied to system clipboard")
}

Output:

Copied to system clipboard

func CopyToTmux 

func CopyToTmux(text string) error

CopyToTmux is a convenience function for tmux-only copying

Example 
package main

import (
	"fmt"
	"log"

	"github.com/Hanaasagi/magonote/pkg/clipboard"
)

func main() {
	// Copy only to tmux buffer
	err := clipboard.CopyToTmux("Tmux only")
	if err != nil {
		log.Printf("Tmux copy failed: %v", err)
	}

	fmt.Println("Copied to tmux buffer")
}

Output:

Copied to tmux buffer

func CopyWithOSC52 

func CopyWithOSC52(text string) error

CopyWithOSC52 is a convenience function for OSC52-only copying

Example 
package main

import (
	"fmt"
	"log"

	"github.com/Hanaasagi/magonote/pkg/clipboard"
)

func main() {
	// Copy using OSC52 terminal escape sequence
	err := clipboard.CopyWithOSC52("Remote copy via OSC52")
	if err != nil {
		log.Printf("OSC52 copy failed: %v", err)
	}

	fmt.Println("Copied via OSC52")
}

Output:

Copied via OSC52

func HasSystemClipboard 

func HasSystemClipboard() bool

HasSystemClipboard returns true if system clipboard tools are available

Example 
package main

import (
	"fmt"

	"github.com/Hanaasagi/magonote/pkg/clipboard"
)

func main() {
	// Check if system clipboard tools are available
	if clipboard.HasSystemClipboard() {
		fmt.Println("System clipboard tools available")
	} else {
		fmt.Println("No system clipboard tools found")
	}

	// Output will vary based on system
}

func IsTmuxSession 

func IsTmuxSession() bool

IsTmuxSession returns true if running inside tmux

Example 
package main

import (
	"fmt"

	"github.com/Hanaasagi/magonote/pkg/clipboard"
)

func main() {
	// Check if running inside tmux
	if clipboard.IsTmuxSession() {
		fmt.Println("Running inside tmux")
	} else {
		fmt.Println("Not running inside tmux")
	}

	// Output will vary based on environment
}

Types

type Clipboard 

type Clipboard struct {
	// contains filtered or unexported fields
}

Clipboard provides unified access to multiple clipboard targets

func New 

func New(opts ...Option) *Clipboard

New creates a new Clipboard with default settings

Example 
package main

import (
	"fmt"
	"log"

	"github.com/Hanaasagi/magonote/pkg/clipboard"
)

func main() {
	// Create a new clipboard with default settings (all targets enabled)
	c := clipboard.New()

	// Copy text to all available clipboard targets
	err := c.Copy("Hello, World!")
	if err != nil {
		log.Printf("Copy failed: %v", err)
	}

	fmt.Println("Text copied to clipboard")
}

Output:

Text copied to clipboard
Example (WithOptions) 
package main

import (
	"fmt"
	"log"
	"os"

	"github.com/Hanaasagi/magonote/pkg/clipboard"
)

func main() {
	// Create clipboard with specific options
	c := clipboard.New(
		clipboard.WithTmux(true),        // Enable tmux buffer
		clipboard.WithSystem(false),     // Disable system clipboard
		clipboard.WithOSC52(true),       // Enable OSC52 terminal copying
		clipboard.WithOutput(os.Stderr), // Set output for OSC52
	)

	err := c.Copy("Configured clipboard")
	if err != nil {
		log.Printf("Copy failed: %v", err)
	}

	fmt.Println("Text copied with custom configuration")
}

Output:

Text copied with custom configuration

func (*Clipboard) Copy 

func (c *Clipboard) Copy(text string) error

Copy writes text to all enabled clipboard targets

type OSC52Writer 

type OSC52Writer struct {
	// contains filtered or unexported fields
}

OSC52Writer provides OSC52-only clipboard access

Example 
package main

import (
	"fmt"
	"log"
	"os"

	"github.com/Hanaasagi/magonote/pkg/clipboard"
)

func main() {
	// Create an OSC52 writer for custom output
	writer := clipboard.NewOSC52Writer(os.Stderr)

	err := writer.Write("Custom OSC52 output")
	if err != nil {
		log.Printf("OSC52 write failed: %v", err)
	}

	fmt.Println("OSC52 sequence written")
}

Output:

OSC52 sequence written

func NewOSC52Writer 

func NewOSC52Writer(output io.Writer) *OSC52Writer

NewOSC52Writer creates an OSC52-only clipboard writer

func (*OSC52Writer) Write 

func (o *OSC52Writer) Write(text string) error

Write copies text using OSC52 escape sequence

type Option 

type Option func(*Clipboard)

Option configures a Clipboard

func WithOSC52 

func WithOSC52(enabled bool) Option

WithOSC52 enables/disables OSC52 terminal copying

func WithOutput 

func WithOutput(w io.Writer) Option

WithOutput sets the output destination for OSC52 sequences

func WithSystem 

func WithSystem(enabled bool) Option

WithSystem enables/disables system clipboard copying

func WithTmux 

func WithTmux(enabled bool) Option

WithTmux enables/disables tmux buffer copying

type SystemWriter 

type SystemWriter struct{}

SystemWriter provides system-only clipboard access

Example 
package main

import (
	"fmt"
	"log"

	"github.com/Hanaasagi/magonote/pkg/clipboard"
)

func main() {
	// Create a system-only writer
	writer := clipboard.NewSystemWriter()

	err := writer.Write("System clipboard content")
	if err != nil {
		log.Printf("System write failed: %v", err)
	}

	fmt.Println("Written to system clipboard")
}

Output:

Written to system clipboard

func NewSystemWriter 

func NewSystemWriter() *SystemWriter

NewSystemWriter creates a system-only clipboard writer

func (*SystemWriter) Write 

func (s *SystemWriter) Write(text string) error

Write copies text to system clipboard

type TmuxWriter 

type TmuxWriter struct{}

TmuxWriter provides tmux-only clipboard access

Example 
package main

import (
	"fmt"
	"log"

	"github.com/Hanaasagi/magonote/pkg/clipboard"
)

func main() {
	// Create a tmux-only writer
	writer := clipboard.NewTmuxWriter()

	err := writer.Write("Tmux buffer content")
	if err != nil {
		log.Printf("Tmux write failed: %v", err)
	}

	fmt.Println("Written to tmux buffer")
}

Output:

Written to tmux buffer

func NewTmuxWriter 

func NewTmuxWriter() *TmuxWriter

NewTmuxWriter creates a tmux-only clipboard writer

func (*TmuxWriter) Write 

func (t *TmuxWriter) Write(text string) error

Write copies text to tmux buffer

type Writer 

type Writer interface {
	Write(text string) error
}

Writer represents a clipboard destination

Example

Example: Custom writer implementing the Writer interface 

package main

import (
	"fmt"
	"log"
)

func main() {
	// You can implement custom clipboard writers
	type CustomWriter struct{}

	writeFunc := func(w *CustomWriter) func(string) error {
		return func(text string) error {
			fmt.Printf("Custom writer received: %s\n", text)
			return nil
		}
	}

	// Use the custom writer
	writer := &CustomWriter{}
	writeMethod := writeFunc(writer)
	err := writeMethod("Custom clipboard implementation")
	if err != nil {
		log.Printf("Custom write failed: %v", err)
	}

}

Output:

Custom writer received: Custom clipboard implementation

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.