Cross-platform native clipboard helpers for MoonBit.

desktop

clipboard

native

windows

macos

linux

Download zip

Author

moonbit-community

Version

0.6.0

License

Apache-2.0

Repository

github.com/moonbit-community/proton/tree/main/sys/clipboard

Last updated

16 hours ago

Downloads

23K

moonbitlang/async0.22.5

#moonbit-community/proton_clipboard

Cross-platform native clipboard helpers for MoonBit native builds.

This package reads and writes UTF-8 text on Windows, macOS, and Linux with a small asynchronous API.

#Quick Start

///|
async test "probe clipboard support and read text" {
  match @proton_clipboard.ensure_supported() {
    Ok(_) => ()
    Err(message) => assert_true(!message.is_empty())
  }

  match @proton_clipboard.read_text() {
    Ok(Some(_text)) => ()
    Ok(None) => ()
    Err(message) => assert_true(!message.is_empty())
  }
}

#Platform Backends

Windows: Win32 clipboard API
macOS: AppKit NSPasteboard
Linux: wl-copy / wl-paste, then xclip, then xsel

On Linux, at least one supported clipboard tool must be available on PATH.

Reads and writes are asynchronous on all platforms. On Linux, pipe I/O and waiting for the tool yield to other tasks. Cancellation propagates through the async runtime and stops and reaps the invoked tool. A successful write leaves any background clipboard owner created by the tool alive to serve later pastes. The package uses the async runtime's normal process and SIGPIPE handling.

Operational failures remain Err(String); cancellation is not converted to an operation error. Call read_text() and write_text() from an async function.

ensure_supported

source

fn ensure_supported() -> Result[Unit, String]

Verifies that the current native platform is supported by this package.

Returns Ok(()) when a backend is available and an explanatory Err(String) on unsupported targets or when required runtime tools are missing. Use this when you want to fail fast before attempting a clipboard read or write.

This is a convenience wrapper around is_supported() for callers that prefer Result-based control flow.

Example

test "ensure_supported gives a result-oriented capability check" {
  match @proton_clipboard.ensure_supported() {
    Ok(_) => ()
    Err(message) => assert_true(!message.is_empty())
  }
}

is_supported

source

fn is_supported() -> Bool

Returns true when the current native target has a clipboard backend that this package knows how to call.

On Linux this also checks whether a supported clipboard backend is available on PATH, so the result reflects both platform support and runtime tool availability.

This function performs only a capability probe. It does not read or modify clipboard contents.

Example

test "is_supported reports capability without touching clipboard" {
  let supported = @proton_clipboard.is_supported()
  match supported {
    true => ()
    false => ()
  }
}

read_text

source

async fn read_text() -> Result[String?, String] noraise

Reads the current clipboard text decoded from UTF-8.

The underlying implementation uses @utf8.decode_lossy, so any invalid UTF-8 byte sequences are replaced with the Unicode replacement character (U+FFFD) instead of causing an error.

Successful reads return Ok(Some(text)). If the clipboard currently has no text content, this returns Ok(None). Unsupported platforms and backend failures are reported as Err(String).

Linux tool I/O and process waits yield to other tasks and support cancellation. Only available on the native target.

Example

async test "read_text returns text, emptiness, or an error" {
  match @proton_clipboard.read_text() {
    Ok(Some(text)) => assert_true(text.length() >= 0)
    Ok(None) => ()
    Err(message) => assert_true(!message.is_empty())
  }
}

write_text

source

async fn write_text(text : String) -> Result[Unit, String] noraise

Replaces the current clipboard text with text.

Returns Ok(()) when the write succeeds. Unsupported platforms and backend failures are reported as Err(String). Passing an empty string clears the clipboard text for backends that model an empty clipboard as empty text.

The string is encoded as UTF-8 before it is passed to the native backend.

Example

async test "write_text accepts a string and reports success or failure" {
  match @proton_clipboard.write_text("") {
    Ok(_) => ()
    Err(message) => assert_true(!message.is_empty())
  }
}