From a622ac773c99738bf691b6a2f8ca8f8f039c78c0 Mon Sep 17 00:00:00 2001 From: alemi Date: Fri, 9 Feb 2024 01:04:24 +0100 Subject: [PATCH] docs: updated main doc page examples --- src/lib.rs | 90 +++++++++++++++++++++++++----------------------------- 1 file changed, 42 insertions(+), 48 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 3ceb4ff..5f953ec 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -27,59 +27,77 @@ //! * `client` : include the local [client] implementation (default enabled) //! //! ## examples -//! while the [client::Client] itself is the core structure implementing all methods, plugins will mostly -//! interact with [Instance] managers. +//! the [client::Client] itself is the core structure implementing all methods, plugins should +//! attempt to keep a single instance at any time +//! +//! working sessions are [workspace::Workspace] and while managing multiple ones is in theory +//! possible, it's not really working right now due to how authentication is managed //! //! ### async -//! this library is natively async and thus async usage should be preferred if possible with -//! [instance::a_sync::Instance] -//! //! ```rust,no_run //! use codemp::api::{Controller, TextChange}; -//! # use codemp::instance::a_sync::Instance; +//! # use codemp::client::Client; //! //! # async fn async_example() -> codemp::Result<()> { -//! let session = Instance::default(); // create global session -//! session.connect("http://alemi.dev:50051").await?; // connect to remote server +//! // creating a client session will immediately attempt to connect +//! let mut session = Client::new("http://alemi.dev:50053").await?; +//! +//! // login first, obtaining a new token granting access to 'some_workspace' +//! session.login( +//! "username".to_string(), +//! "password".to_string(), +//! Some("some_workspace".to_string()) +//! ).await?; //! -//! // join a remote workspace, obtaining a cursor controller -//! let cursor = session.join("some_workspace").await?; -//! cursor.send( // move cursor -//! codemp::proto::CursorPosition { +//! // join a remote workspace, obtaining a workspace handle +//! let workspace = session.join_workspace("some_workspace").await?; +//! +//! workspace.cursor().send( // move cursor +//! codemp::proto::cursor::CursorPosition { //! buffer: "test.txt".into(), -//! start: Some(codemp::proto::RowCol { row: 0, col: 0 }), -//! end: Some(codemp::proto::RowCol { row: 0, col: 1 }), +//! start: codemp::proto::cursor::RowCol { row: 0, col: 0 }, +//! end: codemp::proto::cursor::RowCol { row: 0, col: 1 }, //! } //! )?; -//! let op = cursor.recv().await?; // listen for event +//! let op = workspace.cursor().recv().await?; // receive event from server //! println!("received cursor event: {:?}", op); //! //! // attach to a new buffer and execute operations on it -//! session.create("test.txt", None).await?; // create new buffer -//! let buffer = session.attach("test.txt").await?; // attach to it +//! workspace.create("test.txt").await?; // create new buffer +//! let buffer = workspace.attach("test.txt").await?; // attach to it //! let local_change = TextChange { span: 0..0, content: "hello!".into() }; //! buffer.send(local_change)?; // insert some text -//! let remote_change = buffer.recv().await?; +//! let remote_change = buffer.recv().await?; // await remote change //! # //! # Ok(()) //! # } //! ``` //! //! ### sync -//! if async is not viable, including the feature `sync` will provide a sync-only [instance::sync::Instance] variant +//! if async is not viable, a solution might be keeping a global tokio runtime and blocking on it: //! //! ```rust,no_run -//! # use codemp::instance::sync::Instance; +//! # use codemp::client::Client; //! # use std::sync::Arc; //! # use codemp::api::Controller; //! # //! # fn sync_example() -> codemp::Result<()> { -//! let session = Instance::default(); // instantiate sync variant -//! session.connect("http://alemi.dev:50051")?; // connect to server +//! let rt = tokio::runtime::Runtime::new().unwrap(); +//! let mut session = rt.block_on( // using block_on allows calling async code +//! Client::new("http://alemi.dev:50051") +//! )?; +//! +//! rt.block_on(session.login( +//! "username".to_string(), +//! "password".to_string(), +//! Some("some_workspace".to_string()) +//! ))?; +//! +//! let workspace = rt.block_on(session.join_workspace("some_workspace"))?; //! //! // attach to buffer and blockingly receive events -//! let buffer = session.attach("test.txt")?; // attach to buffer, must already exist -//! while let Ok(op) = buffer.blocking_recv(session.rt()) { // must pass runtime +//! let buffer = rt.block_on(workspace.attach("test.txt"))?; // attach to buffer, must already exist +//! while let Ok(op) = rt.block_on(buffer.recv()) { // must pass runtime //! println!("received buffer event: {:?}", op); //! } //! # @@ -87,30 +105,6 @@ //! # } //! ``` //! -//! ### global -//! if instantiating the [Instance] manager is not possible, adding the feature `global` will -//! provide a static lazyly-allocated global reference: [struct@instance::global::INSTANCE]. -//! -//! ```rust,no_run -//! # use codemp::instance::sync::Instance; -//! # use std::sync::Arc; -//! use codemp::prelude::*; // prelude includes everything with "Codemp" in front -//! # fn global_example() -> codemp::Result<()> { -//! CODEMP_INSTANCE.connect("http://alemi.dev:50051")?; // connect to server -//! let cursor = CODEMP_INSTANCE.join("some_workspace")?; // join workspace -//! std::thread::spawn(move || { -//! loop { -//! match cursor.try_recv() { -//! Ok(Some(event)) => println!("received cursor event: {:?}", event), // there might be more -//! Ok(None) => std::thread::sleep(std::time::Duration::from_millis(10)), // wait for more -//! Err(e) => break, // channel closed -//! } -//! } -//! }); -//! # Ok(()) -//! # } -//! ``` -//! //! ## references //! //! ![another cool pic coz why not](https://alemi.dev/img/about-slice-2.png)