Documentation
¶
Overview ¶
Package clipboard encodes the sequences a terminal uses to carry text to and from the system clipboard.
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 a Request that goes unanswered is the ordinary case and not an error.
Nothing here touches a terminal or a clipboard. These are byte strings and the text they carry, which is what lets every claim in this package be a test.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Clear ¶
Clear is the sequence that empties a clipboard.
It is a copy of nothing rather than a command of its own, which is all the protocol offers: an empty payload is how it is spelled.
func Copy ¶
Copy is 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 Limit ¶
func Limit() int
Limit is the largest text Copy will carry, in bytes. It is here so that a refusal can be explained to the user as a size rather than appearing as a copy that did nothing.
func Request ¶
Request is the sequence that asks a terminal what is on a clipboard.
The answer does not come back from here. It arrives on the terminal's input as an operating system command numbered 52, mixed in with whatever the user is typing, and Parse reads it. Most terminals will not answer at all — see the package comment — so nothing should wait on one.
Types ¶
type Selection ¶
type Selection byte
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 = 'c' // Primary is the X11 selection that middle-click pastes, filled by selecting // text rather than by any command. Terminals elsewhere ignore it. Primary Selection = 'p' )
func Parse ¶
Parse reads the text out of a terminal's answer to a Request.
The argument is the parameters of the operating system command, which is everything after the command number: a selection, a semicolon, and the text base64-encoded.
It reports false for anything it cannot read, and that is the common case worth getting right rather than an edge: a terminal that declines to answer may still answer with nothing, and a decoder that turned that into an empty successful paste would clear whatever the user had selected.
Source Files