nucleation 0.1.129__tar.gz → 0.1.132__tar.gz

{nucleation-0.1.129 → nucleation-0.1.132}/Cargo.lock

@@ -1687,7 +1687,7 @@ dependencies = [
 
 [[package]]
 name = "nucleation"
-version = "0.1.129"
+version = "0.1.132"
 dependencies = [
  "base64",
  "bytemuck",

{nucleation-0.1.129 → nucleation-0.1.132}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "nucleation"
-version = "0.1.129"
+version = "0.1.132"
 edition = "2021"
 description = "A high-performance Minecraft schematic parser and utility library"
 authors = ["Nano nano@schem.at"]

{nucleation-0.1.129 → nucleation-0.1.132}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nucleation
-Version: 0.1.129
+Version: 0.1.132
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: GNU Affero General Public License v3

{nucleation-0.1.129 → nucleation-0.1.132}/docs/rust/README.md

@@ -93,6 +93,32 @@ pub struct Region {
 }
 ```
 
+### DefinitionRegion
+
+A logical region defined by multiple bounding boxes, used for defining inputs, outputs, and other logical constructs.
+
+```rust
+pub struct DefinitionRegion {
+    pub boxes: Vec<BoundingBox>,
+    pub metadata: HashMap<String, String>,
+}
+```
+
+**Methods (Fluent API):**
+- `new() -> Self` - Create empty region
+- `from_bounds(min: (i32, i32, i32), max: (i32, i32, i32)) -> Self` - Create from bounds
+- `add_bounds(&mut self, min, max) -> &mut Self` - Add a bounding box
+- `add_point(&mut self, x, y, z) -> &mut Self` - Add a single point
+- `set_color(&mut self, color: u32) -> &mut Self` - Set visualization color
+- `with_metadata(&mut self, key, value) -> &mut Self` - Add metadata
+- `filter_by_block(&mut self, schematic, block_name) -> &mut Self` - Keep only matching blocks
+- `exclude_block(&mut self, schematic, block_name) -> &mut Self` - Remove matching blocks
+- `subtract(&mut self, other) -> &mut Self` - Boolean subtraction
+- `intersect(&mut self, other) -> &mut Self` - Boolean intersection
+- `union_into(&mut self, other) -> &mut Self` - Boolean union
+
+**Note:** Methods like `filter_by_block` require a reference to the `UniversalSchematic`. Due to Rust's borrowing rules, you may need to clone the region or build it separately before inserting it into the schematic if you need to filter based on the schematic's own blocks.
+
 ## Loading and Saving
 
 ### Litematic Format

{nucleation-0.1.129 → nucleation-0.1.132}/examples/rust.md

@@ -113,3 +113,50 @@ The Rust side does **not** re-export those symbols to avoid name clashes.
 * **Deterministic randomness**—chunk loading strategy `"Random"` hashes the
   schematic name, so the order is stable across runs.
 
+---
+
+## 6 · Definition Regions & Fluent API
+
+Nucleation provides a fluent API for defining logical regions within your schematic. This is useful for marking inputs, outputs, or other significant areas.
+
+### Basic Usage
+
+You can chain methods to define a region's properties:
+
+```rust
+schematic.create_region("my_region".to_string(), (0, 0, 0), (5, 5, 5))
+    .add_bounds((10, 0, 0), (15, 5, 5)) // Add disjoint area
+    .set_color(0xFF0000)                // Set visualization color
+    .with_metadata("type", "input");    // Add custom metadata
+```
+
+### Filtering Blocks (Borrow Checker Patterns)
+
+When filtering a region based on the blocks inside it (e.g., "keep only stone blocks"), you need to access the schematic's block data. In Rust, this creates a borrow checker challenge because the region is owned by the schematic.
+
+**Pattern A: Clone, Modify, Insert**
+Safest approach. Clone the region so you can borrow the schematic immutably while modifying the region.
+
+```rust
+if let Some(region) = schematic.definition_regions.get("layout") {
+    let mut region_clone = region.clone();
+    
+    // Now safe to borrow schematic immutably
+    region_clone.filter_by_block(&schematic, "minecraft:stone");
+    
+    // Update the schematic
+    schematic.definition_regions.insert("stone_only".to_string(), region_clone);
+}
+```
+
+**Pattern B: Build Before Inserting**
+Create the region independently, modify it, and then insert it into the schematic.
+
+```rust
+use nucleation::definition_region::DefinitionRegion;
+
+let mut new_region = DefinitionRegion::from_bounds((0,0,0), (5,5,5));
+new_region.exclude_block(&schematic, "minecraft:air");
+schematic.definition_regions.insert("non_air".to_string(), new_region);
+```
+

nucleation-0.1.132/examples/rust_fluent_api.rs

@@ -0,0 +1,50 @@
+use nucleation::definition_region::DefinitionRegion;
+use nucleation::UniversalSchematic;
+
+fn main() {
+    let mut schematic = UniversalSchematic::new("FluentRust".to_string());
+
+    // Setup some blocks
+    schematic.set_block_str(0, 0, 0, "minecraft:stone");
+    schematic.set_block_str(1, 0, 0, "minecraft:dirt");
+    schematic.set_block_str(2, 0, 0, "minecraft:stone");
+
+    // 1. Basic Fluent API (No dependency on schematic content)
+    // This works perfectly because we only borrow the region mutably (via the schematic),
+    // and we don't need to borrow the schematic again for these methods.
+    schematic
+        .create_region("layout".to_string(), (0, 0, 0), (2, 0, 0))
+        .add_bounds((0, 1, 0), (2, 1, 0))
+        .set_color(0xFF0000)
+        .with_metadata("description", "Main Layout");
+
+    println!("Created region 'layout'");
+
+    // 2. Advanced Fluent API (Filtering based on schematic content)
+    // In Rust, we cannot do:
+    // schematic.get_definition_region_mut("layout").filter_by_block(&schematic, "stone");
+    // Because `get_definition_region_mut` borrows `schematic` mutably,
+    // and `filter_by_block` needs to borrow `schematic` immutably.
+
+    // Pattern A: Clone the region, modify, and update (Safe, slightly slower)
+    if let Some(region) = schematic.definition_regions.get("layout") {
+        let mut region_clone = region.clone();
+
+        // Now we can pass &schematic because region_clone is separate
+        region_clone.filter_by_block(&schematic, "minecraft:stone");
+
+        // Update the schematic
+        schematic
+            .definition_regions
+            .insert("stone_only".to_string(), region_clone);
+    }
+
+    // Pattern B: Build region separately before inserting
+    let mut new_region = DefinitionRegion::from_bounds((0, 0, 0), (5, 5, 5));
+    new_region.exclude_block(&schematic, "minecraft:air");
+    schematic
+        .definition_regions
+        .insert("non_air".to_string(), new_region);
+
+    println!("Created filtered regions 'stone_only' and 'non_air'");
+}

{nucleation-0.1.129 → nucleation-0.1.132}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "nucleation"
-version = "0.1.129"
+version = "0.1.132"
 description = "A high-performance Minecraft schematic parser and utility library"
 authors = [{ name = "Nano", email = "nano@schem.at" }]
 license = { text = "AGPL-3.0-only" }