codemp/src/lib.rs

133 lines
4.8 KiB
Rust
Raw Normal View History

//! # Code MultiPlexer - cooperative development
//!
//! `codemp` is an async client library to create cooperation tools for any text editor.
//!
//! It is built as a batteries-included client library managing an authenticated user, multiple
//! workspaces each containing any number of buffers.
//!
//! The [`Client`] is completely managed by the library itself, making its use simple across async
//! contexts and FFI boundaries. All memory is managed by the library itself, which gives out always
//! atomic reference-counted pointers to internally mutable objects. Asynchronous actions are
//! abstracted away by the [`api::Controller`], providing an unopinionated approach with both
//! callback-based and blocking-based APIs.
2023-08-20 00:46:55 +02:00
//!
//! The library also provides ready-to-use bindings in a growing number of other programming languages,
//! to support a potentially infinite number of editors.
//!
//! # Overview
//! The main entrypoint is [`Client::connect`], which establishes an authenticated connection with
//! a supported remote server and returns a [`Client`] handle to interact with it.
//!
//! ```no_run
//! # async {
//! let client = codemp::Client::connect(
2024-09-21 11:52:46 +02:00
//! codemp::api::Config::new(
//! "mail@example.net",
//! "dont-use-this-password"
//! )
//! )
//! .await
//! .expect("failed to connect!");
//! # };
2023-08-20 00:46:55 +02:00
//! ```
//!
//! A [`Client`] can acquire a [`Workspace`] handle by joining an existing one it can access with
//! [`Client::join_workspace`] or create a new one with [`Client::create_workspace`].
//!
//! ```no_run
//! # async {
2024-09-21 11:52:46 +02:00
//! # let client = codemp::Client::connect(codemp::api::Config::new("", "")).await.unwrap();
//! client.create_workspace("my-workspace").await.expect("failed to create workspace!");
2024-09-21 11:52:46 +02:00
//! let workspace = client.join_workspace("my-workspace").await.expect("failed to attach!");
//! # };
//! ```
2024-02-09 01:04:24 +01:00
//!
//! A [`Workspace`] handle can be used to acquire a [`cursor::Controller`] to track remote [`api::Cursor`]s
//! and one or more [`buffer::Controller`] to send and receive [`api::TextChange`]s.
//!
//! ```no_run
//! # async {
2024-09-21 11:52:46 +02:00
//! # let client = codemp::Client::connect(codemp::api::Config::new("", "")).await.unwrap();
//! # client.create_workspace("").await.unwrap();
2024-09-21 11:52:46 +02:00
//! # let workspace = client.join_workspace("").await.unwrap();
2024-10-03 04:06:54 +02:00
//! use codemp::api::controller::{AsyncSender, AsyncReceiver}; // needed to access trait methods
//! let cursor = workspace.cursor();
//! let event = cursor.recv().await.expect("disconnected while waiting for event!");
2024-10-10 12:25:06 +02:00
//! println!("user {} moved on buffer {}", event.user, event.sel.buffer);
//! # };
//! ```
//!
//! Internally, [`buffer::Controller`]s store the buffer state as a [diamond_types] CRDT, guaranteeing
//! eventual consistency. Each [`api::TextChange`] is translated in a network counterpart that is
//! guaranteed to converge.
//!
//! ```no_run
//! # async {
2024-09-21 11:52:46 +02:00
//! # let client = codemp::Client::connect(codemp::api::Config::new("", "")).await.unwrap();
//! # client.create_workspace("").await.unwrap();
2024-09-21 11:52:46 +02:00
//! # let workspace = client.join_workspace("").await.unwrap();
2024-10-03 03:43:20 +02:00
//! # use codemp::api::controller::{AsyncSender, AsyncReceiver};
2024-09-21 11:52:46 +02:00
//! let buffer = workspace.attach("/some/file.txt").await.expect("failed to attach");
//! buffer.content(); // force-sync
2024-10-10 12:25:06 +02:00
//! if let Some(mut update) = buffer.try_recv().await.unwrap() {
2024-10-06 10:24:23 +02:00
//! println!(
//! "content: {}, span: {}-{}",
2024-10-10 12:25:06 +02:00
//! update.change.content, update.change.start, update.change.end
2024-10-06 10:24:23 +02:00
//! );
2024-10-10 12:25:06 +02:00
//! buffer.ack(update.version);
//! } // if None, no changes are currently available
//! # };
//! ```
//!
//! ## FFI
//! As mentioned, we provide bindings in various programming languages. To obtain them, you can
//! compile with the appropriate feature flag. Currently, the following are supported:
//! * `lua`
//! * `javascript`
//! * `java` (requires additional build steps to be usable)
//! * `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)
//!
2024-09-07 22:10:47 +02:00
#![doc(html_logo_url = "https://code.mp/static/logo-round.png")]
2024-09-11 15:04:34 +02:00
#![doc(html_favicon_url = "https://code.mp/static/favicon.ico")]
/// core structs and traits
pub mod api;
/// cursor related types and controller
pub mod cursor;
/// buffer related types and controller
pub mod buffer;
/// workspace handle and operations
pub mod workspace;
2024-08-22 00:57:24 +02:00
pub use workspace::Workspace;
/// client handle, containing all of the above
2024-08-22 00:57:24 +02:00
pub mod client;
pub use client::Client;
2024-08-10 16:13:16 +02:00
/// crate error types
2024-08-22 00:57:24 +02:00
pub mod errors;
2024-02-09 01:16:16 +01:00
2024-08-22 00:57:24 +02:00
/// all-in-one imports : `use codemp::prelude::*;`
pub mod prelude;
2024-08-14 17:12:36 +02:00
2024-08-22 00:57:24 +02:00
/// common utils used in this library and re-exposed
pub mod ext;
/// language-specific ffi "glue"
pub mod ffi;
/// internal network services and interceptors
pub(crate) mod network;
/// Get the current version of the client
pub fn version() -> &'static str {
env!("CARGO_PKG_VERSION")
}