1
2# go-osc52
3
4<p>
5 <a href="https://github.com/aymanbagabas/go-osc52/releases"><img src="https://img.shields.io/github/release/aymanbagabas/go-osc52.svg" alt="Latest Release"></a>
6 <a href="https://pkg.go.dev/github.com/aymanbagabas/go-osc52/v2?tab=doc"><img src="https://godoc.org/github.com/golang/gddo?status.svg" alt="GoDoc"></a>
7</p>
8
9A Go library to work with the [ANSI OSC52](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands) terminal sequence.
10
11## Usage
12
13You can use this small library to construct an ANSI OSC52 sequence suitable for
14your terminal.
15
16
17### Example
18
19```go
20import (
21 "os"
22 "fmt"
23
24 "github.com/aymanbagabas/go-osc52/v2"
25)
26
27func main() {
28 s := "Hello World!"
29
30 // Copy `s` to system clipboard
31 osc52.New(s).WriteTo(os.Stderr)
32
33 // Copy `s` to primary clipboard (X11)
34 osc52.New(s).Primary().WriteTo(os.Stderr)
35
36 // Query the clipboard
37 osc52.Query().WriteTo(os.Stderr)
38
39 // Clear system clipboard
40 osc52.Clear().WriteTo(os.Stderr)
41
42 // Use the fmt.Stringer interface to copy `s` to system clipboard
43 fmt.Fprint(os.Stderr, osc52.New(s))
44
45 // Or to primary clipboard
46 fmt.Fprint(os.Stderr, osc52.New(s).Primary())
47}
48```
49
50## SSH Example
51
52You can use this over SSH using [gliderlabs/ssh](https://github.com/gliderlabs/ssh) for instance:
53
54```go
55var sshSession ssh.Session
56seq := osc52.New("Hello awesome!")
57// Check if term is screen or tmux
58pty, _, _ := s.Pty()
59if pty.Term == "screen" {
60 seq = seq.Screen()
61} else if isTmux {
62 seq = seq.Tmux()
63}
64seq.WriteTo(sshSession.Stderr())
65```
66
67## Tmux
68
69Make sure you have `set-clipboard on` in your config, otherwise, tmux won't
70allow your application to access the clipboard [^1].
71
72Using the tmux option, `osc52.TmuxMode` or `osc52.New(...).Tmux()`, wraps the
73OSC52 sequence in a special tmux DCS sequence and pass it to the outer
74terminal. This requires `allow-passthrough on` in your config.
75`allow-passthrough` is no longer enabled by default
76[since tmux 3.3a](https://github.com/tmux/tmux/issues/3218#issuecomment-1153089282) [^2].
77
78[^1]: See [tmux clipboard](https://github.com/tmux/tmux/wiki/Clipboard)
79[^2]: [What is allow-passthrough](https://github.com/tmux/tmux/wiki/FAQ#what-is-the-passthrough-escape-sequence-and-how-do-i-use-it)
80
81## Credits
82
83* [vim-oscyank](https://github.com/ojroques/vim-oscyank) this is heavily inspired by vim-oscyank.
View as plain text