osc52

README

go-osc52

A Go library to work with the ANSI OSC52 terminal sequence.

Example

str := "Hello World!"
osc52.Copy(str) // Copies str to system clipboard
osc52.CopyPrimary(str) // Copies str to primary clipboard (X11 only)

SSH Example

You can use this over SSH using gliderlabs/ssh for instance:

envs := sshSession.Environ()
pty, _, _ := s.Pty()
envs = append(envs, "TERM="+pty.Term)
output := NewOutput(sshSession, envs)
// Copy text in your application
output.Copy("Hello awesome!")

If you're using tmux, you could pass the TMUX environment variable to help detect tmux:

ssh -o SendEnv=TMUX <host>

Tmux users

If you're using tmux, make sure you set set -g default-terminal in your tmux config, to a value that starts with tmux-. tmux-256color for instance. See this for more details.

go-osc52 will wrap the OSC52 sequence in a tmux escape sequence if tmux is detected. If you're running tmux >= 3.3, OSC52 won't work and you'll need to set the set -g allow-passthrough on in your tmux config.

set -g allow-passthrough on

or set set -g set-clipboard on in your tmux config and use your outer terminal in your code instead:

// Assuming this code is running in tmux >= 3.3 in kitty
seq := osc52.Sequence("Hello awesome!", "xterm-kitty", osc52.ClipboardC)
os.Stderr.WriteString(seq)

Credits

• vim-oscyank this is heavily inspired by vim-oscyank.

Documentation

Overview

OSC52 is a terminal escape sequence that allows copying text to the clipboard.

The sequence consists of the following:

OSC 52 ; Pc ; Pd BEL

Pc is the clipboard choice:

c: clipboard
p: primary
q: secondary (not supported)
s: select (not supported)
0-7: cut-buffers (not supported)

Pd is the data to copy to the clipboard. This string should be encoded in base64 (RFC-4648).

If Pd is "?", the terminal replies to the host with the current contents of the clipboard.

If Pd is neither a base64 string nor "?", the terminal clears the clipboard.

See https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands where Ps = 52 => Manipulate Selection Data.

Index

• func Clear(term string, c Clipboard) string
• func Contents(term string, c Clipboard) string
• func Copy(str string)
• func CopyClipboard(str string, c Clipboard)
• func CopyPrimary(str string)
• func Sequence(str string, term string, c Clipboard) string
• type Clipboard
  • func (c Clipboard) String() string
• type Output
  • func DefaultOutput() *Output
  • func NewOutput(out io.Writer, envs []string) *Output
  • func (o *Output) Copy(str string)
  • func (o *Output) CopyClipboard(str string, c Clipboard)
  • func (o *Output) CopyPrimary(str string)

Functions

func Clear

func Clear(term string, c Clipboard) string

Clear returns the OSC52 sequence to clear the clipboard.

func Contents

func Contents(term string, c Clipboard) string

Contents returns the contents of the clipboard.

func Copy

func Copy(str string)

Copy copies the OSC52 string to the output. This uses the system clipboard buffer.

func CopyClipboard

func CopyClipboard(str string, c Clipboard)

CopyClipboard copies the OSC52 string to the output. This uses the passed clipboard buffer.

func CopyPrimary

func CopyPrimary(str string)

CopyPrimary copies the OSC52 string to the output. This uses the primary clipboard buffer.

func Sequence

func Sequence(str string, term string, c Clipboard) string

Sequence returns the OSC52 sequence for the given string, terminal, and clipboard choice.

Types

type Clipboard

type Clipboard uint

Clipboard is the clipboard buffer to use.

const (
	// SystemClipboard is the system clipboard buffer.
	SystemClipboard Clipboard = iota
	// PrimaryClipboard is the primary clipboard buffer (X11).
	PrimaryClipboard
)

func (Clipboard) String

func (c Clipboard) String() string

String implements the fmt.Stringer interface for Clipboard.

type Output

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

Output is where the OSC52 string should be written.

func DefaultOutput

func DefaultOutput() *Output

DefaultOutput returns the default output for Copy.

func NewOutput

func NewOutput(out io.Writer, envs []string) *Output

NewOutput returns a new Output.

func (*Output) Copy

func (o *Output) Copy(str string)

Copy copies the OSC52 string to the output. This uses the system clipboard buffer.

func (*Output) CopyClipboard

func (o *Output) CopyClipboard(str string, c Clipboard)

CopyClipboard copies the OSC52 string to the output. This uses the passed clipboard buffer.

func (*Output) CopyPrimary

func (o *Output) CopyPrimary(str string)

CopyPrimary copies the OSC52 string to the output. This uses the primary clipboard buffer.