elaborated README

This commit is contained in:
Michael Sippel 2024-06-24 12:19:15 +02:00
parent 10c63e8ae5
commit 16307cd235
Signed by: senvas
GPG key ID: F96CF119C34B64A6

View file

@ -1,48 +1,67 @@
# r3vi # 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 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.
updated *reactively* on changes in the source-view.
These updates are performed incrementally using fine-granuar diffs.
*Views* are abstract accessor-interfaces that also define the update protocol (the diff). Key Concepts
*Observers* can register to observe a *View* and are notified with the according diff-message - **Views**: Abstract accessor interfaces that define the protocol for updates, including the structure of the diffs.
whenever the view changes. - **Observers**: Entities that can register to monitor a View and receive notifications with the appropriate diff messages whenever the view undergoes changes.
*Projections* are transformations from one view into antoher. - **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.
They are made of the target view and an observer that observes the source view. 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 ### Examples
with an interface similar to native rust iterators. Below is an example demonstrating how to use r3vi to create and manipulate reactive views:
## Examples
```rust ```rust
use r3vi::buffer::vec::*; use r3vi::buffer::vec::*;
fn main() {
// Create a new VecBuffer of i32
let mut buffer = VecBuffer::<i32>::new(); let mut buffer = VecBuffer::<i32>::new();
buffer.push(3); buffer.push(3);
// Create a projected port from the buffer
let projected_port = buffer.get_port() let projected_port = buffer.get_port()
.to_sequence() // make SequenceView from Vec .to_sequence() // Convert VecBuffer to SequenceView
.map(|x| x + 10) .map(|x| x + 10)
.filter(|x| x > 10); .filter(|x| *x > 10);
// Obtain the projected view
let projected_view = projected_port.get_view(); let projected_view = projected_port.get_view();
// Assert initial values in the projected view
assert_eq!(projected_view.get(&0), Some(13)); assert_eq!(projected_view.get(&0), Some(13));
buffer.push(5); // maps to 15 // Add more elements to the buffer and observe changes in the projected view
buffer.push(-9); // maps to 1, is eliminated by filter buffer.push(5); // 5 maps to 15 in the projection
buffer.push(1); // maps to 11 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(&1), Some(15));
assert_eq!(projected_view.get(&2), Some(11)); 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 ## License
This project is licensed under the [GPLv3](COPYING) License.
[GPLv3](COPYING)