Clipboard

● Intermediate2 minBefore this: CapabilitiesSpec 14.17

std.clipboard reads and writes the system clipboard's text. What a person copied can be private, so it needs the capability Clipboard.

use std.clipboard

fn main() ! Error uses Clipboard, Console {
    try clipboard.write_text("order 7: refunded")
    print(try clipboard.read_text())       // order 7: refunded
}

Function	Gives
`clipboard.read_text() -> String ! ClipboardError uses Clipboard`	The clipboard's text; fails with `Empty` when it holds none
`clipboard.write_text(text) ! ClipboardError uses Clipboard`	Puts `text` on the clipboard, in place of what was there

ClipboardError is Empty, or Unavailable(reason) on a machine with no clipboard: a server, a container, a terminal with no desktop.
On Linux with X11, text a program writes stays on the clipboard only while the program runs; a clipboard manager, which most desktops have, keeps it after.
Text only, for now: images and other kinds of content are an open question.

It needs Clipboard

A function that reads or writes the clipboard says so in its uses, or it doesn't compile:

use std.clipboard

fn copied() -> String ! Error uses Console {
    try clipboard.read_text()
}

fn main() {
    print(copied() catch _ => "")
}

kavach run needs.kav

error: `copied` uses Clipboard, but its `uses` clause doesn't list it: add `Clipboard` to `uses` (spec 8.1)

In tests

Under kavach test the clipboard is a fake in memory that starts empty, so a test never reads or changes the real one:

use std.clipboard

/// Copies a receipt line, and gives back what the clipboard then holds.
fn copy_receipt(order_id: Int) -> String ! ClipboardError uses Clipboard
    ensure result == "order {order_id}: refunded"
{
    try clipboard.write_text("order {order_id}: refunded")
    try clipboard.read_text()
}

kavach run copy.kav

0 passed, 0 failedseed 7✓ copy_receipt  200 cases1 functions   1 ✓   0 ✗   0 weakly tested