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.
const MaxPayload = 100_000
MaxPayload is the largest text Channel.Copy will carry, in bytes.
The bound exists because the far end has one too, and theirs is silent: a terminal handed more than it will take does not copy the first part, it discards the lot. Multiplexers impose another bound. A conservative size that survives both is more useful than a larger request that reports success and vanishes. The exported constant lets an application explain a refusal before it looks like a copy that did nothing.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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; a nil *Channel is inert. 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.
A syntactically valid answer for the requested selection settles the request even when its payload cannot be decoded; treating that payload as an empty success would clear a selection. Malformed parameters and answers for another selection are left alone for the terminal adapter to publish as the raw OSC event it received, and do not take ownership of the live request.
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 MaxPayload.
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