Merge pull request #7 from akashsoni01/procmacros

Procmacros

Author: codefonsi

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "rust-key-paths"
-version = "0.6.0"
+version = "0.7.0"
 edition = "2024"
 authors = ["Codefonsi <[email protected]>"]
 license = "MPL-2.0"
@@ -13,18 +13,20 @@ readme = "./README.md"
 include = ["src/**/*", "Cargo.toml", "../../README.md", "LICENSE"]
 
 [dependencies]
-key-paths-core = { path = "key-paths-core", version = "0.6.0" }
+key-paths-core = { path = "key-paths-core", version = "0.7.0" }
+key-paths-derive = { path = "key-paths-derive", version = "0.1.0"}
 
 
 [workspace]
 resolver = "3" # or "3"
 members = [
-    "key-paths-core"
+    "key-paths-core",
+    "key-paths-derive"
 ]
 
 [patch.crates-io]
 key-paths-core = { path = "key-paths-core" }
-
+key-paths-derive = { path = "key-paths-derive" }
 
 [features]
 default = []

README.md

@@ -1,33 +1,92 @@
 # 🔑 KeyPaths & CasePaths in Rust
 
 Key paths and case paths provide a **safe, composable way to access and modify nested data** in Rust.
-Inspired by **Swift’s KeyPath / CasePath** system, this crate lets you work with **struct fields** and **enum variants** as *first-class values*.
+Inspired by **Swift’s KeyPath / CasePath** system, this this feature rich crate lets you work with **struct fields** and **enum variants** as *first-class values*.
 
 ---
 
 ## ✨ Features
 
-* ✅ **ReadableKeyPath** → safely read struct fields.
-* ✅ **WritableKeyPath** → safely read/write struct fields.
-* ✅ **EnumKeyPath (CasePaths)** → extract and embed enum variants.
-* ✅ **Composable** → chain key paths together(Upcoming).
-* ✅ **Iterable** → iterate or mutate values across collections.
-* ✅ **Macros** → concise `readable_keypath!`, `writable_keypath!`, `enum_keypath!`.
+- ✅ **Readable/Writable keypaths** for struct fields
+- ✅ **Failable keypaths** for `Option<T>` chains (`_fr`/`_fw`)
+- ✅ **Enum CasePaths** (readable and writable prisms)
+- ✅ **Composition** across structs, options and enum cases
+- ✅ **Iteration helpers** over collections via keypaths
+- ✅ **Proc-macros**: `#[derive(Keypaths)]` for structs/tuple-structs and enums, `#[derive(Casepaths)]` for enums
 
 ---
 
 ## 📦 Installation
 
 ```toml
 [dependencies]
-key_paths_core = "0.6"
+key-paths-core = "0.6"
+key-paths-derive = "0.1"
 ```
 
 ---
 
-## 🚀 Examples - Go to latest examples directory docs will be updated later
+## 🚀 Examples
 
-### 1. CasePaths with Enums
+See `examples/` for many runnable samples. Below are a few highlights.
+
+### 1) Structs with #[derive(Keypaths)]
+
+```rust
+use key_paths_core::KeyPaths;
+use key_paths_derive::Keypaths;
+
+#[derive(Debug, Keypaths)]
+struct Size { width: u32, height: u32 }
+
+#[derive(Debug, Keypaths)]
+struct Rectangle { size: Size, name: String }
+
+fn main() {
+    let mut rect = Rectangle { size: Size { width: 30, height: 50 }, name: "MyRect".into() };
+
+    // Readable/writable
+    println!("width = {:?}", Size::width_r().get(&rect.size));
+    if let Some(w) = Size::width_w().get_mut(&mut rect.size) { *w += 10; }
+
+    // Compose: Rectangle -> Size -> width
+    let rect_width = Rectangle::size_r().compose(Size::width_r());
+    println!("rect.width = {:?}", rect_width.get(&rect));
+}
+```
+
+### 2) Optional chaining (failable keypaths)
+
+```rust
+use key_paths_core::KeyPaths;
+use key_paths_derive::Keypaths;
+
+#[derive(Debug, Keypaths)]
+struct Engine { horsepower: u32 }
+#[derive(Debug, Keypaths)]
+struct Car { engine: Option<Engine> }
+#[derive(Debug, Keypaths)]
+struct Garage { car: Option<Car> }
+
+fn main() {
+    let mut g = Garage { car: Some(Car { engine: Some(Engine { horsepower: 120 }) }) };
+
+    // Read horsepower if present
+    let hp = Garage::car_fr()
+        .compose(Car::engine_fr())
+        .compose(Engine::horsepower_r());
+    println!("hp = {:?}", hp.get(&g));
+
+    // Mutate horsepower if present
+    if let Some(car) = Garage::car_fw().get_mut(&mut g) {
+        if let Some(engine) = Car::engine_fw().get_mut(car) {
+            if let Some(hp) = Engine::horsepower_w().get_mut(engine) { *hp += 30; }
+        }
+    }
+}
+```
+
+### 3) Enum CasePaths (readable/writable prisms)
 
 ```rust
 use key_paths_core::KeyPaths;
@@ -38,7 +97,7 @@ enum Payment {
 }
 
 fn main() {
-    let kp = KeyPaths::writable_enum(
+let kp = KeyPaths::writable_enum(
         |v| Payment::Cash { amount: v },
         |p: &Payment| match p {
             Payment::Cash { amount } => Some(amount),
@@ -64,74 +123,7 @@ fn main() {
 
 ---
 
-### 2. Readable KeyPaths - helper macros wip
-
-```rust
-use key_paths_core::KeyPaths;
-
-#[derive(Debug)]
-struct Size {
-    width: u32,
-    height: u32,
-}
-
-#[derive(Debug)]
-struct Rectangle {
-    size: Size,
-    name: String,
-}
-
-fn main() {
-    let mut rect = Rectangle {
-        size: Size {
-            width: 30,
-            height: 50,
-        },
-        name: "MyRect".into(),
-    };
-
-    let width_direct = KeyPaths::readable(|r: &Rectangle| &r.size.width);
-    println!("Width: {:?}", width_direct.get(&rect));
-}
-```
-
----
-
-### 3. Writable KeyPaths - helper macros wip
-
-```rust
-use key_paths_core::KeyPaths;
-
-#[derive(Debug)]
-struct Size {
-    width: u32,
-    height: u32,
-}
-#[derive(Debug)]
-struct Rectangle {
-    size: Size,
-    name: String,
-}
-fn main() {
-    let mut rect = Rectangle {
-        size: Size {
-            width: 30,
-            height: 50,
-        },
-        name: "MyRect".into(),
-    };
-    let width_mut = KeyPaths::writable(
-        |r: &mut Rectangle| &mut r.size.width,
-    );
-    // Mutable
-    if let Some(hp_mut) = width_mut.get_mut(&mut rect) {
-        *hp_mut += 50;
-    }
-    println!("Updated rectangle: {:?}", rect);
-}
-```
-
-### 4. Composability and failablity
+### 4) Compose enum prisms with struct fields
  ```rust
 use key_paths_core::KeyPaths;
 
@@ -170,7 +162,7 @@ fn main() {
     println!("{garage:?}");
 }
 ```
-### 4. Mutablity
+### 5) Iteration via keypaths
  ```rust
 use key_paths_core::KeyPaths;
 
@@ -264,10 +256,10 @@ ABox { name: "A box", size: Size { width: 10, height: 20 }, color: Other(RGBU8(0
 
 ## 🛠 Roadmap
 
-* [ ] `compose` support for combining multiple key paths.
-* [ ] Derive macros for automatic KeyPath generation (Upcoming).
-* [ ] Nested struct & enum traversal.
-* [ ] Optional chaining (`User?.profile?.name`) with failable.
+- [x] Compose across structs, options and enum cases
+- [x] Derive macros for automatic keypath generation
+- [x] Optional chaining with failable keypaths
+- [ ] Derive macros for complex multi-field enum variants
 ---
 
 ## 📜 License

examples/basics_macros.rs

@@ -0,0 +1,74 @@
+use key_paths_core::KeyPaths;
+use key_paths_derive::Keypaths;
+
+#[derive(Debug, Keypaths)]
+struct Size {
+    width: u32,
+    height: u32,
+}
+
+#[derive(Debug, Keypaths)]
+struct Rectangle {
+    size: Size,
+    name: String,
+}
+
+fn main() {
+    let mut rect = Rectangle {
+        size: Size {
+            width: 30,
+            height: 50,
+        },
+        name: "MyRect".into(),
+    };
+
+    // Define readable and writable keypaths.
+    let size_kp: KeyPaths<Rectangle, Size> = KeyPaths::readable(|r: &Rectangle| &r.size);
+    let width_kp: KeyPaths<Size, u32> = KeyPaths::readable(|s: &Size| &s.width);
+
+    // Compose nested paths (assuming composition is supported).
+    // e.g., rect[&size_kp.then(&width_kp)] — hypothetical chaining
+
+    // Alternatively, define them directly:
+    let width_direct: KeyPaths<Rectangle, u32> = KeyPaths::readable(|r: &Rectangle| &r.size.width);
+    println!("Width: {:?}", width_direct.get(&rect));
+
+    // Writable keypath for modifying fields:
+    let width_mut: KeyPaths<Rectangle, u32> = KeyPaths::writable(
+        // |r: &Rectangle| &r.size.width,
+        |r: &mut Rectangle| &mut r.size.width,
+    );
+    // Mutable
+    if let Some(hp_mut) = width_mut.get_mut(&mut rect) {
+        *hp_mut += 50;
+    }
+    println!("Updated rectangle: {:?}", rect);
+
+    // Keypaths from derive-generated methods
+    let rect_size_fw = Rectangle::size_fw();
+    let rect_name_fw = Rectangle::name_fw();
+    let size_width_fw = Size::width_fw();
+    let size_height_fw = Size::height_fw();
+
+    let name_readable = Rectangle::name_r();
+    println!("Name (readable): {:?}", name_readable.get(&rect));
+
+    let size_writable = Rectangle::size_w();
+    if let Some(s) = size_writable.get_mut(&mut rect) {
+        s.width += 1;
+    }
+
+    // Use them
+    if let Some(s) = rect_size_fw.get_mut(&mut rect) {
+        if let Some(w) = size_width_fw.get_mut(s) {
+            *w += 5;
+        }
+        if let Some(h) = size_height_fw.get_mut(s) {
+            *h += 10;
+        }
+    }
+    if let Some(name) = rect_name_fw.get_mut(&mut rect) {
+        name.push_str("_fw");
+    }
+    println!("After failable updates: {:?}", rect);
+}