From 16307cd2355a792bd9a388ec7bdf00ffa60f7cf2 Mon Sep 17 00:00:00 2001 From: Michael Sippel Date: Mon, 24 Jun 2024 12:19:15 +0200 Subject: [PATCH] elaborated README --- README.md | 77 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 48 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 1b45710..02a24f9 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,67 @@ # r3vi -Rust Runtime for Reactive View-Projections +### Rust Runtime for Reactive View-Projections -Using **r3vi** you can define *Projections*, i.e. transformations on *Views* that are -updated *reactively* on changes in the source-view. -These updates are performed incrementally using fine-granuar diffs. +r3vi is a Rust library designed to handle reactive transformations on data views, known as Projections. These projections are updated incrementally and efficiently whenever the source data changes, utilizing fine-grained diffs. -*Views* are abstract accessor-interfaces that also define the update protocol (the diff). -*Observers* can register to observe a *View* and are notified with the according diff-message -whenever the view changes. -*Projections* are transformations from one view into antoher. -They are made of the target view and an observer that observes the source view. +Key Concepts +- **Views**: Abstract accessor interfaces that define the protocol for updates, including the structure of the diffs. +- **Observers**: Entities that can register to monitor a View and receive notifications with the appropriate diff messages whenever the view undergoes changes. +- **Projections**: Transformations from one view to another. A projection comprises a target view and an observer that listens to changes in the source view and updates the target view accordingly. +r3vi provides essential data structures and projections to build projectional pipelines with an interface similar to native Rust iterators, enabling seamless and reactive data transformations. -R3vi provides basic data-structures and projections to build projectional pipelines -with an interface similar to native rust iterators. - - -## Examples +### Examples +Below is an example demonstrating how to use r3vi to create and manipulate reactive views: ```rust use r3vi::buffer::vec::*; -let mut buffer = VecBuffer::::new(); -buffer.push(3); +fn main() { + // Create a new VecBuffer of i32 + let mut buffer = VecBuffer::::new(); + buffer.push(3); -let projected_port = buffer.get_port() - .to_sequence() // make SequenceView from Vec - .map(|x| x + 10) - .filter(|x| x > 10); + // Create a projected port from the buffer + let projected_port = buffer.get_port() + .to_sequence() // Convert VecBuffer to SequenceView + .map(|x| x + 10) + .filter(|x| *x > 10); -let projected_view = projected_port.get_view(); + // Obtain the projected view + let projected_view = projected_port.get_view(); -assert_eq!(projected_view.get(&0), Some(13)); + // Assert initial values in the projected view + assert_eq!(projected_view.get(&0), Some(13)); -buffer.push(5); // maps to 15 -buffer.push(-9); // maps to 1, is eliminated by filter -buffer.push(1); // maps to 11 - -assert_eq!(projected_view.get(&1), Some(15)); -assert_eq!(projected_view.get(&2), Some(11)); + // Add more elements to the buffer and observe changes in the projected view + buffer.push(5); // 5 maps to 15 in the projection + buffer.push(-9); // -9 maps to 1, which is filtered out + buffer.push(1); // 1 maps to 11 in the projection + // Assert updated values in the projected view + assert_eq!(projected_view.get(&1), Some(15)); + assert_eq!(projected_view.get(&2), Some(11)); +} ``` +#### How It Works +1. **Creating a Buffer**: We start by creating a `VecBuffer` to store integers. +2. **Defining a Projection**: Using `get_port()`, we convert the buffer to a sequence view, apply a map transformation to add 10 to each element, and then filter out values less than or equal to 10. +3. **Obtaining a View**: The transformed data is accessed through `get_view()`, allowing us to interact with the projected data. +4. **Reactive Updates**: As new elements are added to the buffer, the projections update reactively, maintaining the transformations and filters defined. + +This example demonstrates the reactive nature of r3vi's projections, where changes in the source data are automatically and incrementally propagated to the target view. + +### Getting Started +To start using **r3vi**, add it to your `Cargo.toml`: + +```toml +[dependencies] +r3vi = "0.1" +``` + +For detailed documentation and more examples, please refer to the official documentation. ## License +This project is licensed under the [GPLv3](COPYING) License. -[GPLv3](COPYING)