-
-
Notifications
You must be signed in to change notification settings - Fork 145
The CB Standard
When I started the Clipboard Project, I never actually intended it to work with any existing GUI or desktop clipboard systems. Instead, everything would occur using a bespoke filesystem-based implementation. What this means is that everything is a file or directory. All the files you copy are literally copied, and the same goes for any other info you add to it. Shockingly, this is a completely novel idea, only being partially replicated before by the Plan9 platform that used a "clipboard file" with which to read and write text.
Until the Clipboard Project, computer clipboard systems have all used bespoke methods to access "the clipboard." Windows uses specific C++ functions to access the Windows clipboard. macOS is largely the same, but with Objective-C and Swift instead of C++. For Linux and all of the BSDs, you can choose between X11 or Wayland, both using an API you access with C. Haiku, a lesser-known system compared to even BSD, uses a C++ API somewhat like a combination of macOS and Windows. All of these methods of accessing "the clipboard" depend on some bespoke server or service to provide the clipboard functionality.
So, presented with the vast array of different systems requiring a special snowflake implementation, I decided the best place to start would be to Break The Rules and make something completely generic. How might I do that? As it turns out, on almost all systems out there, you can generate a "temporary directory" to store anything in, just temporarily. So I did just that. And, the rest is history.
This standard is only current to the Clipboard Project 0.6.0 release. Future updates may cause breaking changes or incompatibilities!
The root directory may reside in a directory that exists until system shutdown, or a directory that will always remain until until the user deletes it. Refer to directories that exist until system shutdown as temporary directories and directories that will always remain until until the user deletes them as persistent directories.
The Clipboard Project uses the C++ std::filesystem::temp_directory_path function to generate a directory that it creates a Clipboard directory under as the temporary directory. CB also uses the value of the HOME environment variable on non-Windows systems and the USERPROFILE environment variable on Windows as a directory that it places the .clipboard directory under as the persistent directory.
All clipboards which do not start with a _ character reside in the temporary directory and use a directory using the name of the clipboard to store all contents in.
The Metadata Directory contains several files that describe the clipboard and its data.
When a program accesses this clipboard, it should create the file lock which contains the process ID of that process formatted as a string.
The notes file stores a string that can describe the clipboard's purpose.
The originals file stores a newline-separated list of file paths that the implementation will delete when pasting.
The Data Directory contains all raw data, files, or directories copied by the user.
The rawdata.clipboard file contains any raw data that is not a file or directory.
I'd like that this Wiki page be updated in the future to be more comprehensive so that other implementations of the CB standard can exist and eventually become a good way to interface with "the clipboard."
If you'd like to contribute to this standard, feel free to open an Issue with the necessary changes because GitHub doesn't allow Pull Requests for Wikis yet.