|
| 1 | +# `deep_causality_ast` |
| 2 | + |
| 3 | +[](https://crates.io/crates/deep_causality_ast) |
| 4 | +[](https://docs.rs/deep_causality_ast) |
| 5 | +[](https://opensource.org/licenses/MIT) |
| 6 | + |
| 7 | +A persistent, immutable, thread-safe tree data structure for the `deep_causality` project. |
| 8 | + |
| 9 | +## Overview |
| 10 | + |
| 11 | +This crate provides `ConstTree<T>`, a foundational Abstract Syntax Tree (AST) structure designed for efficiency and safety in concurrent environments. It is a persistent data structure, meaning that all modifications are non-destructive and return a new instance of the tree, sharing as much of the underlying data as possible with the original. |
| 12 | + |
| 13 | +This copy-on-write behavior makes it highly efficient to pass trees around and create modified versions without incurring the cost of deep copies. |
| 14 | + |
| 15 | +## Core Features |
| 16 | + |
| 17 | +* **Persistent & Immutable**: Operations that "modify" the tree are non-destructive. They return a new, modified `ConstTree`, leaving the original unchanged. |
| 18 | +* **Efficient Cloning**: `ConstTree` is built on `std::sync::Arc`. Cloning a tree is a cheap, constant-time operation that simply increments a reference count. |
| 19 | +* **Thread-Safe**: It is `Send` and `Sync` (if `T` is `Send` and `Sync`), allowing it to be safely shared across threads without locks. |
| 20 | +* **Rich API**: Includes a comprehensive API for construction, traversal, searching, and functional mapping. |
| 21 | + * Multiple iteration strategies (pre-order, post-order, level-order, consuming). |
| 22 | + * Consuming (`into_map`) and non-consuming (`map`) mapping methods. |
| 23 | + * Monadic `join` method to flatten a `ConstTree<ConstTree<T>>`. |
| 24 | + |
| 25 | +## Usage |
| 26 | + |
| 27 | +Here is a basic example of how to create and interact with a `ConstTree`. |
| 28 | + |
| 29 | +```rust |
| 30 | +use deep_causality_ast::ConstTree; |
| 31 | + |
| 32 | +fn main() { |
| 33 | + // Create a tree with a root value and some children. |
| 34 | + let leaf1 = ConstTree::new(10); |
| 35 | + let leaf2 = ConstTree::from(20); // `From<T>` is implemented. |
| 36 | + let tree = ConstTree::with_children(5, vec![leaf1, leaf2]); |
| 37 | + |
| 38 | + // --- Inspection --- |
| 39 | + assert_eq!(*tree.value(), 5); |
| 40 | + assert_eq!(tree.children().len(), 2); |
| 41 | + assert_eq!(tree.depth(), 2); |
| 42 | + assert_eq!(tree.size(), 3); |
| 43 | + |
| 44 | + // --- Iteration --- |
| 45 | + // The tree can be iterated over in several ways. |
| 46 | + let values: Vec<i32> = tree.iter_pre_order().copied().collect(); |
| 47 | + assert_eq!(values, vec![5, 10, 20]); |
| 48 | + |
| 49 | + // --- Modification --- |
| 50 | + // `add_child` returns a new tree; the original is unchanged. |
| 51 | + let leaf3 = ConstTree::new(30); |
| 52 | + let modified_tree = tree.add_child(leaf3); |
| 53 | + |
| 54 | + assert_eq!(tree.children().len(), 2); // Original is unaffected. |
| 55 | + assert_eq!(modified_tree.children().len(), 3); |
| 56 | + assert_eq!(*modified_tree.children()[2].value(), 30); |
| 57 | + |
| 58 | + // --- Mapping --- |
| 59 | + // `map` creates a new tree with a different value type. |
| 60 | + let string_tree = modified_tree.map(&mut |v| format!("val: {}", v)); |
| 61 | + assert_eq!(*string_tree.value(), "val: 5"); |
| 62 | + assert_eq!(*string_tree.children()[0].value(), "val: 10"); |
| 63 | + |
| 64 | + // `into_map` consumes the tree. |
| 65 | + let owned_string_tree = modified_tree.into_map(|v| format!("owned: {}", v)); |
| 66 | + assert_eq!(*owned_string_tree.value(), "owned: 5"); |
| 67 | +} |
| 68 | +``` |
| 69 | + |
| 70 | +## 👨💻👩💻 Contribution |
| 71 | + |
| 72 | +Contributions are welcomed especially related to documentation, example code, and fixes. |
| 73 | +If unsure where to start, just open an issue and ask. |
| 74 | + |
| 75 | +Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in deep_causality by you, |
| 76 | +shall be licensed under the MIT licence, without any additional terms or conditions. |
| 77 | + |
| 78 | +## 📜 Licence |
| 79 | + |
| 80 | +This project is licensed under the [MIT license](LICENSE). |
| 81 | + |
| 82 | +## 👮️ Security |
| 83 | + |
| 84 | +For details about security, please read |
| 85 | +the [security policy](https://github.com/deepcausality-rs/deep_causality/blob/main/SECURITY.md). |
0 commit comments