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 (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)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 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 ¶
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 ¶
Clear sets the operation to ClearOperation. This clears the clipboard.
This is a syntactic sugar for s.Operation(ClearOperation).
func (Sequence) Limit ¶
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) Operation ¶
Operation sets the operation for the OSC52 sequence. The default operation is SetOperation.
func (Sequence) Primary ¶
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 ¶
Query sets the operation to QueryOperation. This queries the clipboard contents.
This is a syntactic sugar for s.Operation(QueryOperation).
func (Sequence) Screen ¶
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 ¶
SetString sets the string for the OSC52 sequence. Strings are joined with a space character.
Source Files
Directories