hexedtech/codemp
3
0
Fork 0
mirror of https://github.com/hexedtech/codemp.git synced 2024-11-21 23:04:49 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: move descr directly into traits, not module

Browse source
This commit is contained in:
əlemi 2023-09-10 03:39:44 +02:00
parent 9040222570
commit c0892b36cd
2 changed files with 80 additions and 70 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
src/api/controller.rs
View file

@ -1,9 +1,7 @@
//! # Controller
//!
//! this generic trait is implemented by actors managing stream procedures.
//! events can be enqueued for dispatching without blocking ([Controller::send]), and an async blocking
//! api ([Controller::recv]) is provided to wait for server events. Additional sync blocking
//! ([Controller::blocking_recv]) and callback-based ([Controller::callback]) are implemented.
//! an bidirectional stream handler to easily manage async operations across local buffers and the
//! server
use crate::Result;
use std::sync::Arc;
@ -20,6 +18,15 @@ pub(crate) trait ControllerWorker<T : Sized + Send + Sync> {
}
/// async and threadsafe handle to a generic bidirectional stream
///
/// this generic trait is implemented by actors managing stream procedures.
/// events can be enqueued for dispatching without blocking ([Controller::send]), and an async blocking
/// api ([Controller::recv]) is provided to wait for server events. Additional sync blocking
/// ([Controller::blocking_recv]) and callback-based ([Controller::callback]) are implemented.
///
/// * if possible, prefer a pure [Controller::recv] consumer
/// * a second possibility in preference is using a [Controller::callback]
/// * if neither is feasible a [Controller::poll]/[Controller::try_recv] approach is available
#[tonic::async_trait]
pub trait Controller<T : Sized + Send + Sync> : Sized + Send + Sync {
/// type of upstream values, used in [Self::send]

135
src/api/factory.rs
View file

@ -1,72 +1,8 @@
//! ### factory
//!
//! a helper trait to produce Operation Sequences, knowing the current
//! state of the buffer
//!
//! ```rust
//! use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
//! a helper trait that any string container can implement, which generates opseqs
//!
//! let mut factory = SimpleOperationFactory::from("");
//! let op = factory.insert("asd", 0);
//! factory.update(op)?;
//! assert_eq!(factory.content(), "asd");
//! # Ok::<(), codemp::ot::OTError>(())
//! ```
//!
//! use [OperationFactory::insert] to add new characters at a specific index
//!
//! ```rust
//! # use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
//! # let mut factory = SimpleOperationFactory::from("asd");
//! factory.update(factory.insert(" dsa", 3))?;
//! assert_eq!(factory.content(), "asd dsa");
//! # Ok::<(), codemp::ot::OTError>(())
//! ```
//!
//! use [OperationFactory::delta] to arbitrarily change text at any position
//!
//! ```rust
//! # use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
//! # let mut factory = SimpleOperationFactory::from("asd dsa");
//! let op = factory.delta(2, " xxx ", 5).expect("replaced region is equal to origin");
//! factory.update(op)?;
//! assert_eq!(factory.content(), "as xxx sa");
//! # Ok::<(), codemp::ot::OTError>(())
//! ```
//!
//! use [OperationFactory::delete] to remove characters from given index
//!
//! ```rust
//! # use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
//! # let mut factory = SimpleOperationFactory::from("as xxx sa");
//! factory.update(factory.delete(2, 5))?;
//! assert_eq!(factory.content(), "assa");
//! # Ok::<(), codemp::ot::OTError>(())
//! ```
//!
//! use [OperationFactory::replace] to completely replace buffer content
//!
//! ```rust
//! # use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
//! # let mut factory = SimpleOperationFactory::from("assa");
//! let op = factory.replace("from scratch").expect("replace is equal to origin");
//! factory.update(op)?;
//! assert_eq!(factory.content(), "from scratch");
//! # Ok::<(), codemp::ot::OTError>(())
//! ```
//!
//! use [OperationFactory::cancel] to remove characters at index, but backwards
//!
//! ```rust
//! # use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
//! # let mut factory = SimpleOperationFactory::from("from scratch");
//! factory.update(factory.cancel(12, 8))?;
//! assert_eq!(factory.content(), "from");
//! # Ok::<(), codemp::ot::OTError>(())
//! ```
//!
//!
//! This trait provides an implementation for String, but plugin developers
//! an OperationFactory trait implementation is provided for String, but plugin developers
//! should implement their own operation factory interfacing directly with the editor
//! buffer when possible.
@ -97,6 +33,73 @@ pub fn op_effective_range(op: &OperationSeq) -> Range<u64> {
}
/// a helper trait that any string container can implement, which generates opseqs
///
/// all operations are to be considered mutating current state, obtainable with
/// [OperationFactory::content]. generating an operation has no effect on internal state
///
/// ### examples
///
/// ```rust
/// use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
///
/// let mut factory = SimpleOperationFactory::from("");
/// let op = factory.insert("asd", 0);
/// factory.update(op)?;
/// assert_eq!(factory.content(), "asd");
/// # Ok::<(), codemp::ot::OTError>(())
/// ```
///
/// use [OperationFactory::insert] to add new characters at a specific index
///
/// ```rust
/// # use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
/// # let mut factory = SimpleOperationFactory::from("asd");
/// factory.update(factory.insert(" dsa", 3))?;
/// assert_eq!(factory.content(), "asd dsa");
/// # Ok::<(), codemp::ot::OTError>(())
/// ```
///
/// use [OperationFactory::delta] to arbitrarily change text at any position
///
/// ```rust
/// # use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
/// # let mut factory = SimpleOperationFactory::from("asd dsa");
/// let op = factory.delta(2, " xxx ", 5).expect("replaced region is equal to origin");
/// factory.update(op)?;
/// assert_eq!(factory.content(), "as xxx sa");
/// # Ok::<(), codemp::ot::OTError>(())
/// ```
///
/// use [OperationFactory::delete] to remove characters from given index
///
/// ```rust
/// # use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
/// # let mut factory = SimpleOperationFactory::from("as xxx sa");
/// factory.update(factory.delete(2, 5))?;
/// assert_eq!(factory.content(), "assa");
/// # Ok::<(), codemp::ot::OTError>(())
/// ```
///
/// use [OperationFactory::replace] to completely replace buffer content
///
/// ```rust
/// # use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
/// # let mut factory = SimpleOperationFactory::from("assa");
/// let op = factory.replace("from scratch").expect("replace is equal to origin");
/// factory.update(op)?;
/// assert_eq!(factory.content(), "from scratch");
/// # Ok::<(), codemp::ot::OTError>(())
/// ```
///
/// use [OperationFactory::cancel] to remove characters at index, but backwards
///
/// ```rust
/// # use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
/// # let mut factory = SimpleOperationFactory::from("from scratch");
/// factory.update(factory.cancel(12, 8))?;
/// assert_eq!(factory.content(), "from");
/// # Ok::<(), codemp::ot::OTError>(())
/// ```
pub trait OperationFactory {
/// the current content of the buffer
fn content(&self) -> String;