osc52

README

go-osc52

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

Usage

You can use this small library to construct an ANSI OSC52 sequence suitable for your terminal.

Example

import (
  "os"
  "fmt"

  "github.com/aymanbagabas/go-osc52/v2"
)

func main() {
  s := "Hello World!"

  // Copy `s` to system clipboard
  osc52.New(s).WriteTo(os.Stderr)

  // Copy `s` to primary clipboard (X11)
  osc52.New(s).Primary().WriteTo(os.Stderr)

  // Query the clipboard
  osc52.Query().WriteTo(os.Stderr)

  // Clear system clipboard
  osc52.Clear().WriteTo(os.Stderr)

  // Use the fmt.Stringer interface to copy `s` to system clipboard
  fmt.Fprint(os.Stderr, osc52.New(s))

  // Or to primary clipboard
  fmt.Fprint(os.Stderr, osc52.New(s).Primary())
}

SSH Example

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

var sshSession ssh.Session
seq := osc52.New("Hello awesome!")
// Check if term is screen or tmux
pty, _, _ := s.Pty()
if pty.Term == "screen" {
  seq = seq.Screen()
} else if isTmux {
  seq = seq.Tmux()
}
seq.WriteTo(sshSession.Stderr())

Tmux

Make sure you have set-clipboard on in your config, otherwise, tmux won't allow your application to access the clipboard [^1].

Using the tmux option, osc52.TmuxMode or osc52.New(...).Tmux(), wraps the OSC52 sequence in a special tmux DCS sequence and pass it to the outer terminal. This requires allow-passthrough on in your config. allow-passthrough is no longer enabled by default since tmux 3.3a [^2].

[^1]: See tmux clipboard [^2]: What is allow-passthrough

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.

Examples:

// copy "hello world" to the system clipboard
fmt.Fprint(os.Stderr, osc52.New("hello world"))

// copy "hello world" to the primary Clipboard
fmt.Fprint(os.Stderr, osc52.New("hello world").Primary())

// limit the size of the string to copy 10 bytes
fmt.Fprint(os.Stderr, osc52.New("0123456789").Limit(10))

// escape the OSC52 sequence for screen using DCS sequences
fmt.Fprint(os.Stderr, osc52.New("hello world").Screen())

// escape the OSC52 sequence for Tmux
fmt.Fprint(os.Stderr, osc52.New("hello world").Tmux())

// query the system Clipboard
fmt.Fprint(os.Stderr, osc52.Query())

// query the primary clipboard
fmt.Fprint(os.Stderr, osc52.Query().Primary())

// clear the system Clipboard
fmt.Fprint(os.Stderr, osc52.Clear())

// clear the primary Clipboard
fmt.Fprint(os.Stderr, osc52.Clear().Primary())

Index

• type Clipboard
• type Mode
• type Operation
• type Sequence
  • func Clear() Sequence
  • func New(strs ...string) Sequence
  • func Query() Sequence
  • func (s Sequence) Clear() Sequence
  • func (s Sequence) Clipboard(c Clipboard) Sequence
  • func (s Sequence) Limit(l int) Sequence
  • func (s Sequence) Mode(m Mode) Sequence
  • func (s Sequence) Operation(o Operation) Sequence
  • func (s Sequence) Primary() Sequence
  • func (s Sequence) Query() Sequence
  • func (s Sequence) Screen() Sequence
  • func (s Sequence) SetString(strs ...string) Sequence
  • func (s Sequence) String() string
  • func (s Sequence) Tmux() Sequence
  • func (s Sequence) WriteTo(out io.Writer) (int64, error)

Types

type Clipboard

type Clipboard rune

Clipboard is the clipboard buffer to use.

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

type Mode

type Mode uint

Mode is the mode to use for the OSC52 sequence.

const (
	// DefaultMode is the default OSC52 sequence mode.
	DefaultMode Mode = iota
	// ScreenMode escapes the OSC52 sequence for screen using DCS sequences.
	ScreenMode
	// TmuxMode escapes the OSC52 sequence for tmux. Not needed if tmux
	// clipboard is set to `set-clipboard on`
	TmuxMode
)

type Operation

type Operation uint

Operation is the OSC52 operation.

const (
	// SetOperation is the copy operation.
	SetOperation Operation = iota
	// QueryOperation is the query operation.
	QueryOperation
	// ClearOperation is the clear operation.
	ClearOperation
)

type Sequence

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

Sequence is the OSC52 sequence.

func Clear

func Clear() Sequence

Clear creates a new OSC52 sequence with the ClearOperation. This returns a new OSC52 sequence to clear the clipboard.

This is a syntactic sugar for New().Clear().

func New

func New(strs ...string) Sequence

New creates a new OSC52 sequence with the given string(s). Strings are joined with a space character.

func Query

func Query() Sequence

Query creates a new OSC52 sequence with the QueryOperation. This returns a new OSC52 sequence to query the clipboard contents.

This is a syntactic sugar for New().Query().

func (Sequence) Clear

func (s Sequence) Clear() Sequence

Clear sets the operation to ClearOperation. This clears the clipboard.

This is a syntactic sugar for s.Operation(ClearOperation).

func (Sequence) Clipboard

func (s Sequence) Clipboard(c Clipboard) Sequence

Clipboard sets the clipboard buffer for the OSC52 sequence.

func (Sequence) Limit

func (s Sequence) Limit(l int) Sequence

Limit sets the limit for the OSC52 sequence. The default limit is 0 (no limit).

Strings longer than the limit get ignored. Settting the limit to 0 or a negative value disables the limit. Each terminal defines its own escapse sequence limit.

func (Sequence) Mode

func (s Sequence) Mode(m Mode) Sequence

Mode sets the mode for the OSC52 sequence.

func (Sequence) Operation

func (s Sequence) Operation(o Operation) Sequence

Operation sets the operation for the OSC52 sequence. The default operation is SetOperation.

func (Sequence) Primary

func (s Sequence) Primary() Sequence

Primary sets the clipboard buffer to PrimaryClipboard. This is the X11 primary clipboard.

This is a syntactic sugar for s.Clipboard(PrimaryClipboard).

func (Sequence) Query

func (s Sequence) Query() Sequence

Query sets the operation to QueryOperation. This queries the clipboard contents.

This is a syntactic sugar for s.Operation(QueryOperation).

func (Sequence) Screen

func (s Sequence) Screen() Sequence

Screen sets the mode to ScreenMode. Used to escape the OSC52 sequence for `screen`.

This is a syntactic sugar for s.Mode(ScreenMode).

func (Sequence) SetString

func (s Sequence) SetString(strs ...string) Sequence

SetString sets the string for the OSC52 sequence. Strings are joined with a space character.

func (Sequence) String

func (s Sequence) String() string

String returns the OSC52 sequence.

func (Sequence) Tmux

func (s Sequence) Tmux() Sequence

Tmux sets the mode to TmuxMode. Used to escape the OSC52 sequence for `tmux`.

Note: this is not needed if tmux clipboard is set to `set-clipboard on`. If TmuxMode is used, tmux must have `allow-passthrough on` set.

This is a syntactic sugar for s.Mode(TmuxMode).

func (Sequence) WriteTo

func (s Sequence) WriteTo(out io.Writer) (int64, error)

WriteTo writes the OSC52 sequence to the writer.