Documentation
¶
Overview ¶
Package clipboard owns the OSC 52 channel that carries text between a program and the clipboard beside its user-facing terminal.
A terminal is often not where the program is. Over ssh, in a container, inside a multiplexer on another machine, the tools that reach a clipboard directly — pbcopy, wl-copy, xclip — reach the wrong one or none at all. The terminal is the only thing on the user's side of the connection, so asking it to do the copying is the only approach that works everywhere the same way.
That is what OSC 52 is. It is also a capability a terminal may refuse: writing is commonly allowed and reading commonly is not, because a program that can read the clipboard can read whatever the user copied out of a password manager. Neither refusal is reported — a terminal that will not do it simply does nothing — so an unanswered Channel.Request is ordinary. The channel expires it rather than treating an unrelated future OSC 52 as the requested text.
Nothing here touches a terminal or a clipboard. A Channel produces byte strings and settles answers; terminal adapters own when and where those strings are sent.
Index ¶
Constants ¶
const Command = 52
Command is OSC 52's operating system command number.
Variables ¶
This section is empty.
Functions ¶
func Limit ¶
func Limit() int
Limit is the largest text Channel.Copy will carry, in bytes. It is here so a refusal can be explained as a size instead of appearing as a copy that did nothing.
Types ¶
type Channel ¶ added in v0.7.0
type Channel struct {
// contains filtered or unexported fields
}
Channel is one stateful OSC 52 path to a user-facing terminal.
Its zero value is a direct path ready for use. New additionally adapts encoding to a tmux session described by an environment. All methods are safe to call from different goroutines. A Channel must not be copied after first use.
func New ¶ added in v0.7.0
New returns a channel suited to the terminal environment. lookup belongs to the terminal being driven: a remote adapter passes the accepted PTY environment, not the server process environment. Nil constructs the same direct channel as the zero value.
func (*Channel) Answer ¶ added in v0.7.0
Answer settles a terminal's OSC 52 parameters as text when they answer the live request for the same selection.
An unreadable answer still settles that request but reports false; treating it as an empty success would clear a selection. An answer for another selection is left alone for the terminal adapter to publish as the raw OSC event it received.
func (*Channel) Clear ¶ added in v0.7.0
Clear returns the sequence that empties a clipboard. It is a copy of nothing rather than a command of its own, which is how the protocol spells it.
func (*Channel) Copy ¶ added in v0.7.0
Copy returns the sequence that asks the terminal to put text on a clipboard.
The text is base64-encoded, which is what makes this safe to send at all: the encoding's alphabet contains neither the escape byte nor the terminator, so no text — pasted, downloaded, or produced by something hostile upstream — can end the sequence early and have the rest of itself read as commands.
It reports false for text too large to carry. See Limit.
func (*Channel) Request ¶ added in v0.7.0
Request starts one clipboard read and returns the sequence to send.
It reports false while an earlier request is still eligible for an answer. OSC 52 has no request identity, so sending two and guessing which response belongs to which would make ownership weaker rather than concurrency stronger. A request a terminal silently refuses expires by itself.
type Selection ¶
type Selection uint8
Selection is which of a terminal's two clipboards is meant.
const ( // System is the clipboard a copy command fills and a paste command reads. It // is the zero value because it is what "the clipboard" means to nearly // everyone: the X11 primary selection is a convention of one windowing system, // and this one is universal. System Selection = iota // Primary is the X11 selection that middle-click pastes, filled by selecting // text rather than by any command. Terminals elsewhere ignore it. Primary )
Source Files