From cda0584b0e1700b9d7ffdad7758f10f1d62e8ea8 Mon Sep 17 00:00:00 2001 From: "alemi.dev" Date: Mon, 14 Oct 2024 14:13:35 +0200 Subject: [PATCH] docs(ffi): comparison examples (#47) docs: added ffi comparison examples --- src/ext.rs | 2 +- src/ffi/mod.rs | 146 +++++++++++++++++++++++++++++++++++++++++++++++++ src/lib.rs | 4 +- 3 files changed, 150 insertions(+), 2 deletions(-) diff --git a/src/ext.rs b/src/ext.rs index 06a3cc1..32a6594 100644 --- a/src/ext.rs +++ b/src/ext.rs @@ -6,7 +6,7 @@ use tokio::sync::mpsc; /// Poll all given buffer controllers and wait, returning the first one ready. /// -/// It will spawn tasks blocked on [`Controller::poll`] for each buffer controller. +/// It will spawn tasks blocked on [`AsyncReceiver::poll`] for each buffer controller. /// As soon as one finishes, its controller is returned and all other tasks are canceled. /// /// If a timeout is provided, the result may be `None` if it expires before any task is diff --git a/src/ffi/mod.rs b/src/ffi/mod.rs index bc92147..1ddd89a 100644 --- a/src/ffi/mod.rs +++ b/src/ffi/mod.rs @@ -2,12 +2,73 @@ //! `codemp` aims to be available as a library from as many programming languages as possible. //! To achieve this, we rely on Foreign Function Interface. //! +//! ```no_run +//! # async { +//! use codemp::api::controller::{AsyncReceiver, AsyncSender}; // needed for send/recv trait methods +//! +//! // connect first, api.code.mp is managed by hexed.technology +//! let client = codemp::Client::connect(codemp::api::Config::new( +//! "mail@example.net", "dont-use-this-password" +//! )).await?; +//! +//! // create and join a workspace +//! client.create_workspace("some-workspace").await?; +//! let workspace = client.join_workspace("some-workspace").await?; +//! +//! // create a new buffer in this workspace and attach to it +//! workspace.create("/my/file.txt").await?; +//! let buffer = workspace.attach("/my/file.txt").await?; +//! +//! // write `hello!` at the beginning of this buffer +//! buffer.send(codemp::api::TextChange { +//! start: 0, end: 0, +//! content: "hello!".to_string(), +//! })?; +//! +//! // wait for cursor movements +//! loop { +//! let event = workspace.cursor().recv().await?; +//! println!("user {} moved on buffer {}", event.user, event.sel.buffer); +//! } +//! # Ok::<(),Box>(()) +//! # }; +//! ``` +//! //! ## JavaScript //! Our JavaScript glue is built with [`napi`](https://napi.rs). //! //! All async operations are handled on a separate tokio runtime, automatically managed by `napi`. //! Callbacks are safely scheduled to be called on the main loop thread. //! +//! ```js +//! import * as codemp from 'codemp'; +//! +//! // connect first, api.code.mp is managed by hexed.technology +//! let client = await codemp.connect({ +//! username: "mail@example.net", password: "dont-use-this-password" +//! }); +//! +//! // create and join a workspace +//! await client.create_workspace("some-workspace"); +//! let workspace = await client.join_workspace("some-workspace"); +//! +//! // create a new buffer in this workspace and attach to it +//! await workspace.create("/my/file.txt"); +//! let buffer = await workspace.attach("/my/file.txt"); +//! +//! // write `hello!` at the beginning of this buffer +//! await buffer.send({ +//! start: 0, end: 0, +//! content: "hello!", +//! }); +//! +//! // wait for cursor movements +//! while (true) { +//! let event = await workspace.cursor().recv(); +//! console.log(`user ${event.user} moved on buffer ${event.buffer}`); +//! } +//! ``` +//! //! ## Python //! Our Python glue is built with [`PyO3`](https://pyo3.rs). //! @@ -15,6 +76,34 @@ //! value. The `Future` itself is run on a `tokio` runtime in a dedicated thread, which must be //! stared with `codemp.init()` before doing any async operations. //! +//! ```py +//! import codemp +//! +//! # connect first, api.code.mp is managed by hexed.technology +//! config = codemp.get_default_config() +//! config.username = "mail@example.net" +//! config.password = "dont-use-this-password" +//! client = codemp.connect(config).wait() +//! +//! # create and join a workspace +//! client.create_workspace("some-workspace").wait() +//! workspace = client.join_workspace("some-workspace").wait() +//! +//! # create a new buffer in this workspace and attach to it +//! workspace.create("/my/file.txt").wait() +//! buffer = workspace.attach("/my/file.txt").wait() +//! +//! # write `hello!` at the beginning of this buffer +//! buffer.send( +//! 0, 0, "hello!" +//! ).wait() +//! +//! # wait for cursor movements +//! while true: +//! event = workspace.cursor().recv().wait() +//! print(f"user {event.user} moved on buffer {event.buffer}") +//! ``` +//! //! ## Lua //! Our Lua glue is built with [`mlua`](https://github.com/mlua-rs/mlua). //! @@ -33,6 +122,35 @@ //! We provide pre-built binaries at [codemp.dev/releases/lua](https://codemp.dev/releases/lua/). //! **Please do not rely on this link, as our built binaries will likely move somewhere else soon!**. //! +//! ```lua +//! CODEMP = require('codemp') +//! +//! -- connect first, api.code.mp is managed by hexed.technology +//! local client = CODEMP.connect({ +//! username = "mail@example.net", password = "dont-use-this-password" +//! }):await() +//! +//! -- create and join a workspace +//! client:create_workspace("my-workspace"):await() +//! local workspace = client:join_workspace("my-workspace"):await() +//! +//! -- create a new buffer in this workspace and attach to it +//! workspace:create_buffer("/my/file.txt"):await() +//! local buffer = workspace:attach_buffer("/my/file.txt"):await() +//! +//! -- write `hello!` at the beginning of this buffer +//! buffer:send({ +//! start = 0, finish = 0, +//! content = "hello!" +//! }):await() +//! +//! -- wait for cursor movements +//! while true do +//! local event = workspace.cursor:recv():await() +//! print("user " .. event.user .. " moved on buffer " .. event.buffer) +//! end +//! ``` +//! //! ## Java //! Our Java glue is built with [`jni`](https://github.com/jni-rs/jni-rs). //! @@ -42,6 +160,34 @@ //! Exceptions coming from the native side have generally been made checked to imitate Rust's philosophy with `Result`. //! `JNIException`s are however unchecked: there is nothing you can do to recover from them, as they usually represent a severe error in the glue code. If they arise, it's probably a bug. //! +//! ```java +//! import mp.code.*; +//! +//! // connect first, api.code.mp is managed by hexed.technology +//! Client client = Client.connect( +//! new data.Config("mail@example.net", "dont-use-this-password") +//! ); +//! +//! // create and join a workspace +//! client.createWorkspace("some-workspace"); +//! Workspace workspace = client.joinWorkspace("some-workspace"); +//! +//! // create a new buffer in this workspace and attach to it +//! workspace.createBuffer("/my/file.txt"); +//! BufferController buffer = workspace.attachToBuffer("/my/file.txt"); +//! +//! // write `hello!` at the beginning of this buffer +//! buffer.send(new data.TextChange( +//! 0, 0, "hello!", +//! java.util.OptionalLong.empty() // optional, used for error detection +//! )); +//! +//! // wait for cursor movements +//! while (true) { +//! data.Cursor event = workspace.getCursor().recv(); +//! System.out.printf("user %s moved on buffer %s\n", event.user, event.buffer); +//! } +//! ``` #![allow(clippy::unit_arg)] diff --git a/src/lib.rs b/src/lib.rs index 739f9b2..8ddf2c8 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -88,8 +88,10 @@ //! * `python` //! //! For some of these, ready-to-use packages are available in various registries: -//! * [PyPI (python)](https://pypi.org/project/codemp) //! * [npm (javascript)](https://www.npmjs.com/package/codemp) +//! * [PyPI (python)](https://pypi.org/project/codemp) +//! * [Maven Central (java)](https://central.sonatype.com/artifact/mp.code/codemp) +//! * [LuaRocks (lua)](https://luarocks.org/modules/alemi/codemp) //! #![doc(html_logo_url = "https://code.mp/static/logo-round.png")] #![doc(html_favicon_url = "https://code.mp/static/favicon.ico")]