From b6b31502cf2f1c784d99bedc6df2a796799b1c10 Mon Sep 17 00:00:00 2001
From: Adrien Burgun <adrien.burgun@orange.fr>
Date: Tue, 21 Jun 2022 15:42:23 +0200
Subject: [PATCH] :pencil: `prelude` and start writing examples for `Pane`

---
 stackline/src/lib.rs  | 27 +++++++++++++++++++++++----
 stackline/src/pane.rs | 37 ++++++++++++++++++++++++++++++++++---
 2 files changed, 57 insertions(+), 7 deletions(-)

diff --git a/stackline/src/lib.rs b/stackline/src/lib.rs
index b1af5b9..08f0cf9 100644
--- a/stackline/src/lib.rs
+++ b/stackline/src/lib.rs
@@ -1,10 +1,19 @@
+/*! # Stackline v2
+
+`Stackline v2` is the successor of [stackline](https://github.com/adri326/stackline), an esoteric language inspired by [Wireworld](https://mathworld.wolfram.com/WireWorld.html) and [ORCA](https://github.com/hundredrabbits/Orca).
+
+This library is the rust implementation of the core logic of the language.
+
+
+*/
+
 use std::num::NonZeroUsize;
 
-mod signal;
-pub use signal::*;
+pub mod signal;
+use signal::*;
 
-mod pane;
-pub use pane::*;
+pub mod pane;
+use pane::*;
 
 pub mod utils;
 use utils::*;
@@ -18,3 +27,13 @@ use context::*;
 pub struct World {
     panes: Vec<Pane>,
 }
+
+pub mod prelude {
+    pub use crate::World;
+    pub use crate::pane::Pane;
+
+    pub use crate::utils::*;
+    pub use crate::signal::Signal;
+    pub use crate::context::UpdateContext;
+    pub use crate::tile::Tile;
+}
diff --git a/stackline/src/pane.rs b/stackline/src/pane.rs
index f2eb18d..a15d078 100644
--- a/stackline/src/pane.rs
+++ b/stackline/src/pane.rs
@@ -55,6 +55,21 @@ impl Pane {
         self.tiles.get(position.1 * self.width.get() + position.0)
     }
 
+    /// Returns a mutable reference to the [`Tile`] at `position`.
+    ///
+    /// ## Example
+    ///
+    /// ```
+    /// use stackline::prelude::*;
+    /// use stackline::tile::Wire;
+    ///
+    /// let mut pane = Pane::empty(4, 4).unwrap();
+    ///
+    /// pane.set_tile((0, 0), Wire::new(Orientation::Horizontal));
+    ///
+    /// let mut tile = pane.get_mut((0, 0)).unwrap();
+    /// tile.set_state(State::Active);
+    /// ```
     #[inline]
     pub fn get_mut<'b>(&'b mut self, position: (usize, usize)) -> Option<&'b mut FullTile> {
         if !self.in_bounds(position) {
@@ -64,6 +79,17 @@ impl Pane {
         self.tiles.get_mut(position.1 * self.width.get() + position.0)
     }
 
+    /// Sets the tile at `position` to `tile`. `T` must either implement [`Tile`] or be `()`.
+    #[inline]
+    pub fn set_tile<T>(&mut self, position: (usize, usize), tile: T) -> Option<()> where FullTile: From<T> {
+        let full_tile = self.get_mut(position)?;
+
+        *full_tile = FullTile::from(tile);
+
+        Some(())
+    }
+
+    /// Returns the [`State`] of the tile at `position`, if it exists.
     #[inline]
     pub fn get_state(&self, position: (usize, usize)) -> Option<State> {
         self.get(position).map(|x| x.state().clone())
@@ -76,9 +102,14 @@ impl Pane {
     #[inline]
     pub fn set_signal(&mut self, position: (usize, usize), mut signal: Signal) -> Option<()> {
         signal.set_position(position);
-        self.get_mut(position)?.set_signal(Some(signal))?;
-        self.signals.push(position);
-        Some(())
+        if let Some(tile) = self.get_mut(position) {
+            tile.set_signal(Some(signal))?;
+            tile.set_state(State::Active);
+            self.signals.push(position);
+            Some(())
+        } else {
+            None
+        }
     }
 
     #[inline]