elaborated README

README.md

@@ -1,48 +1,65 @@
-# r3vi
+# r3vi - Rust Runtime for Reactive View-Projections
 
-Rust Runtime for Reactive View-Projections
+**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.
 
-Using **r3vi** you can define *Projections*, i.e. transformations on *Views* that are
+## Key Concepts
-updated *reactively* on changes in the source-view.
+- **Views**: Abstract accessor interfaces that define the protocol for updates, including the structure of the diffs.
-These updates are performed incrementally using fine-granuar 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.
 
-*Views* are abstract accessor-interfaces that also define the update protocol (the diff).
+### Examples
-*Observers* can register to observe a *View* and are notified with the according diff-message
+Below is an example demonstrating how to use **r3vi** to create and manipulate reactive views:
-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.
-
-R3vi provides basic data-structures and projections to build projectional pipelines
-with an interface similar to native rust iterators.
-
-
-## Examples
 
 ```rust
 use r3vi::buffer::vec::*;
 
-let mut buffer = VecBuffer::<i32>::new();
+fn main() {
-buffer.push(3);
+    // Create a new VecBuffer of i32
+    let mut buffer = VecBuffer::<i32>::new();
+    buffer.push(3);
 
-let projected_port = buffer.get_port()
+    // Create a projected port from the buffer
-                      .to_sequence()     // make SequenceView from Vec
+    let projected_port = buffer.get_port()
-                      .map(|x| x + 10)
+                          .to_sequence()  // Convert VecBuffer to SequenceView
-                      .filter(|x| x > 10);
+                          .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
+    // 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_eq!(projected_view.get(&1), Some(15));
-assert_eq!(projected_view.get(&2), Some(11));
 
+    // 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)