V0.0.3

.github/workflows/crates.yml

@@ -16,7 +16,7 @@ on:
   workflow_dispatch:
 
 jobs:
-  independents:
+  base:
     env:
       CRATE_NAME: ${{ github.event.repository.name }}-${{ matrix.suffix }}
     name: Publish (${{ matrix.suffix }})
@@ -42,6 +42,7 @@ jobs:
       - run: cargo publish --all-features -v -p ${{ env.CRATE_NAME }} --token ${{ secrets.CARGO_REGISTRY_TOKEN }}
   publish:
     name: Publish (${{ github.event.repository.name }})
+    needs: base
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

Cargo.toml

@@ -23,15 +23,15 @@ thiserror = "1"
 
 [workspace.package]
 authors = ["Joe McCain III <jo3mccain@icloud.com>",]
-categories = [ ]
+categories = [ "mathematics", "science", "simulation" ]
 description = "This crate focuses on building concrete implementations for Turing Machines."
 edition = "2021"
 homepage = "https://github.com/FL03/rstm/wiki"
-keywords = [ ]
+keywords = [ "turing", "turing-machine", "utm" ]
 license = "Apache-2.0"
 readme = "README.md"
 repository = "https://github.com/FL03/rstm.git"
-version = "0.0.2"
+version = "0.0.3"
 
 [profile.dev]
 opt-level = 0

README.md

@@ -38,8 +38,27 @@ cargo build --features full -r --workspace
 ```rust
     extern crate rstm;
 
-    fn main() -> Result<(), Box<dyn std::error::Error>> {
+    use rstm::state::BinState::{Invalid, Valid};
+    use rstm::{rule, Program, State, StdTape, TM};
 
+    fn main() -> Result<(), Box<dyn std::error::Error>> {
+        tracing_subscriber::fmt().with_target(false).init();
+
+        // initialize the tape data
+        let alpha: Vec<u8> = vec![1, 0, 1, 1, 0, 1, 1, 1, 0, 1, 1, 0, 0, 1, 0, 1, 0, 0, 1];
+        // define the rules for the machine
+        let rules = vec![
+            rule![(Invalid, 0) -> Right(Invalid, 0)],
+            rule![(Invalid, 1) -> Right(Valid, 0)],
+            rule![(Valid, 0) -> Right(Valid, 1)],
+            rule![(Valid, 1) -> Left(Valid, 0)],
+        ];
+
+        let tape = StdTape::from_iter(alpha);
+        let program = Program::from_state(State(Invalid)).with_instructions(rules);
+        // create a new instance of the machine
+        let tm = TM::new(program, tape);
+        tm.execute()?;
         Ok(())
     }
 ```

core/src/actors/actor.rs

@@ -0,0 +1,69 @@
+/*
+    Appellation: actor <module>
+    Contrib: FL03 <jo3mccain@icloud.com>
+*/
+use crate::rules::Directive;
+use crate::{Head, State, Symbolic};
+
+/// [Actor] aptly describe the `TMH` model
+pub struct Actor<Q, S> {
+    /// the input alphabet
+    pub alpha: Vec<S>,
+    pub ptr: Head<Q, usize>,
+}
+
+impl<Q, S> Actor<Q, S> {
+    pub fn new(State(state): State<Q>, tape: impl IntoIterator<Item = S>) -> Self {
+        Self {
+            alpha: Vec::from_iter(tape),
+            ptr: Head::new(State(state), 0),
+        }
+    }
+
+    pub const fn head(&self) -> &Head<Q, usize> {
+        &self.ptr
+    }
+
+
+
+    pub fn state(&self) -> State<&Q> {
+        self.ptr.state()
+    }
+
+    pub fn handle<D>(&mut self, rule: D) -> Head<&Q, &S>
+    where
+        D: Directive<Q, S>,
+        S: Symbolic,
+    {
+        self.write(rule.value().clone());
+        self.ptr.shift_inplace(rule.direction());
+        Head {
+            state: self.ptr.state.to_ref(),
+            symbol: self.read(),
+        }
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.alpha.is_empty()
+    }
+
+    pub fn is_halted(&self) -> bool {
+        self.ptr.symbol >= self.alpha.len()
+    }
+
+    pub fn len(&self) -> usize {
+        self.alpha.len()
+    }
+
+    pub fn read(&self) -> &S {
+        &self.alpha[self.ptr.symbol % self.len()]
+    }
+
+    pub fn write(&mut self, symbol: S) {
+        if self.ptr.symbol < self.alpha.len() {
+            self.alpha[self.ptr.symbol] = symbol;
+        } else {
+            self.alpha.push(symbol);
+        }
+    }
+}

core/src/actors/mod.rs

@@ -0,0 +1,44 @@
+/*
+    Appellation: actors <module>
+    Contrib: FL03 <jo3mccain@icloud.com>
+*/
+#[doc(inline)]
+pub use self::actor::Actor;
+
+pub(crate) mod actor;
+
+#[allow(unused_imports)]
+pub(crate) mod prelude {
+    pub use super::actor::Actor;
+}
+
+use crate::{Program, Symbolic};
+
+pub struct Model<Q, S> {
+    pub actor: Actor<Q, S>,
+    pub program: Program<Q, S>,
+}
+
+impl<Q, S> Model<Q, S> {
+    pub fn with_program(self, program: Program<Q, S>) -> Self {
+        Model { program, ..self }
+    }
+}
+impl<Q, S> Iterator for Model<Q, S>
+where
+    Q: Clone + PartialEq,
+    S: Symbolic,
+{
+    type Item = S;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        if self.actor.is_halted() {
+            return None;
+        }
+        let state = self.actor.state();
+        let symbol = self.actor.read();
+        let rule = self.program.get(state, symbol)?;
+        self.actor.handle(rule.clone());
+        unimplemented!()
+    }
+}

core/src/lib.rs

@@ -11,15 +11,17 @@ extern crate alloc;
 
 #[doc(inline)]
 pub use self::{
-    error::Error, ops::prelude::*, rules::prelude::*, state::State, tape::StdTape,
-    traits::prelude::*, types::prelude::*,
+    error::Error, ops::prelude::*, rules::prelude::*, state::State, tape::Tape, traits::prelude::*,
+    types::prelude::*,
 };
 
 #[macro_use]
 pub(crate) mod macros;
 #[macro_use]
 pub(crate) mod seal;
 
+#[doc(hidden)]
+pub mod actors;
 pub mod error;
 pub mod ops;
 pub mod rules;

core/src/macros.rs

@@ -2,6 +2,9 @@
     Appellation: macros <module>
     Contrib: FL03 <jo3mccain@icloud.com>
 */
+#![allow(unused)]
 
+#[macro_use]
+pub mod fmt;
 #[macro_use]
 pub mod states;

core/src/macros/fmt.rs

@@ -0,0 +1,18 @@
+/*
+    Appellation: fmt <module>
+    Contrib: FL03 <jo3mccain@icloud.com>
+*/
+
+macro_rules! unit_impl_fmt {
+    (@impl $trait:ident::<$T:ty>($($fmt:tt)*)) => {
+        impl core::fmt::$trait for $T {
+            fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
+                core::fmt::$trait::fmt(self, f, $($fmt)*)
+            }
+        }
+    };
+    ($T:ty: $($trait:ident($($fmt:tt)*)),*) => {
+        $(impl_fmt!(@impl $trait::<$T>($($fmt)*));)*
+    };
+}
+

core/src/ops/shift.rs

@@ -3,6 +3,9 @@
     Contrib: FL03 <jo3mccain@icloud.com>
 */
 
+/// [`Shift`] describes a generalized shift operation;
+/// w.r.t. Turing machines, Moore (1990) describes a shift operation as a _movement_ of the
+/// tape head
 pub trait Shift<T> {
     type Output;
 

core/src/ops/transform.rs

@@ -3,14 +3,12 @@
     Contrib: FL03 <jo3mccain@icloud.com>
 */
 
-/// The [`Transform`] trait generically describes objects capable of applying some transformation.
-/// From a "rustic" point of view, the trait simply provides an additional reference point for
-/// the `map` method, which is a method that applies a function to a value and returns a new value.
-///  
-/// [`Transform::transform`] is a method that takes a reference to `self` and a value of type `T`
-/// and returns a value of type [`Transform::Output`].
+/// [`Transform`] is describes a binary operation capable of applying some transformation.
+/// More commonly, the typical "rustic" manner of which an object is transformed is through
+/// the [`map`] method, which applies a function to a value and returns a new value.
 pub trait Transform<T> {
     type Output;
-
+    /// [`Transform::transform`] is a method that takes a reference to `self` and a value of type
+    /// `T` and returns a value of type [`Transform::Output`].
     fn transform(&self, delta: T) -> Self::Output;
 }

core/src/rules/instruction.rs

@@ -17,39 +17,50 @@ impl<Q, S> Instruction<Q, S> {
     pub fn new() -> InstructionBuilder<Q, S> {
         InstructionBuilder::new()
     }
-    /// Returns a reference to the [head](Head) of the [instruction](Instruction)
+    /// Returns an immutable reference to the [Head]
     pub const fn head(&self) -> &Head<Q, S> {
         &self.head
     }
-    /// Returns a mutable reference to the [head](Head) of the [instruction](Instruction)
+    /// Returns a mutable reference to the [Head]
     pub fn head_mut(&mut self) -> &mut Head<Q, S> {
         &mut self.head
     }
-    /// Returns a reference to the [tail](Tail) of the [instruction](Instruction)
+    /// Returns an instance of the [Head] whose elements are immutable references
+    pub fn head_ref(&self) -> Head<&'_ Q, &'_ S> {
+        self.head().to_ref()
+    }
+    /// Returns an immutable reference to the [Tail] of the [Instruction]
     pub const fn tail(&self) -> &Tail<Q, S> {
         &self.tail
     }
-    /// Returns a mutable reference to the [tail](Tail) of the [instruction](Instruction)
+    /// Returns a mutable reference to the [Tail] of the [Instruction]
     pub fn tail_mut(&mut self) -> &mut Tail<Q, S> {
         &mut self.tail
     }
-    /// Returns the direction the [head](Head) is instructed to move
+
+    pub fn tail_ref(&self) -> Tail<&'_ Q, &'_ S> {
+        self.tail().to_ref()
+    }
+    /// Returns the direction of the shift
     pub fn direction(&self) -> Direction {
         self.tail().direction()
     }
     /// Returns the current [state](State) of the [head](Head)
     pub fn state(&self) -> State<&'_ Q> {
-        self.head().get_state()
+        self.head().state()
     }
     /// Returns the current symbol of the [head](Head)
     pub const fn symbol(&self) -> &S {
         self.head().symbol()
     }
-    /// Returns the next [state](State) the agent is instructed to move to
+    pub fn next_head(&self) -> Head<&'_ Q, &'_ S> {
+        self.tail().to_head_ref()
+    }
+    /// Returns the next [State] of the system
     pub fn next_state(&self) -> State<&'_ Q> {
         self.tail().next_state()
     }
-    /// Returns the symbol the [head](Head) is instructed to write
+    /// Returns the value which for which the current object will be replaced with
     pub const fn write_symbol(&self) -> &S {
         self.tail().write_symbol()
     }