yatm 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be3ead1b208b860b2ef2021496657196eff8a1bc42fc25c569cf77d3be6f37ff
-  data.tar.gz: a502d0f27f32c4a8686f5edca9aaf6e53f842a524b3e6cd26f34140528966bc5
+  metadata.gz: 648dc35601df1be85b015a29fff60f789820bd605e8b90e2f2b78d81fd9ec749
+  data.tar.gz: 9fad47b236af179fed6869d7813ecfa37da86fe7c8a06e53bd8abe07dde1b819
 SHA512:
-  metadata.gz: 8f63ffe798d7500425b9d2de058fbc4704584b5a9b3fbc20ac440677df16b5b1a1d1fb512cc5c3efcf5e97fb5c89d974c5cf15560cf8fad22bf54e511bdd9602
-  data.tar.gz: fa8a1cfef51c8cc0673a17c461e53319ab3d953e7cc8b85803e6136a3f010665c27992d7ae26f83f0bcfa162369691e9778414d88e9391ef31f88b1212bb8e5d
+  metadata.gz: acd14ce8af175e496e737be3e67d91045456a8c8334d9cac9a90e7122989e0f727f40780f3ca9e641cdf128533eca3e395cb6f614188c67c9184f7953d63a571
+  data.tar.gz: da9d9e6e5ab7dcb3ec5c3bb4c0c3bded322140d509774c33b3c4ebd6257904f0d4f272d5e02d7087df4ec41fbcc30ea7748a334ebc52c7b57203ee33962fee76

data/lib/yatm/error.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# @abstract Subclass and override {#text} to set the default error message.
 class YATM::Error < StandardError
   def text
     raise NotImplementedError

data/lib/yatm/machine/machine.rb

@@ -1,18 +1,48 @@
 # frozen_string_literal: true
 
+# This is the class used to set up and use the turing machine.
+#
+# Use {#event} to create the various transitions. The states are automatically
+# inferred to be all the states added through this method.
+#
+# Use {#initial_state} once to select the initial state, and {#final_state}
+# however many times to mark states as final.
+#
+# The content of the tape can be given upon initializing the machine, through
+# the parameter `content`, or with the method {#reset}.
+#
+# @example A turing machine which prints an "OX" and halts at position 0.
+#   m = YATM::Machine.new
+#   m.event nil,
+#     start:   [:running, "O", :r],
+#     running: [:halt, "X", :l]
+#   m.initial_state :start
+#   m.final_state :halt
+#   m.run!
 class YATM::Machine
-  attr_reader :tape, :state_machine, :history
-
+  # The tape over which values can be written and read by the machine.
+  attr_reader :tape
+  # The state machine associated with this turing machine.
+  attr_reader :state_machine
+  # @return [Array<Hash>] A record of the transitions undergone by the machine.
+  attr_reader :history
+
+  # @param position [Integer] The initial position of the machine's head.
+  # @param content [Array] The initial content of the tape, starting from position 0.
   def initialize(position: 0, content: [nil])
     @tape = YATM::Tape.new(content, position: position)
     @state_machine = YATM::StateMachine.new
     @history = []
   end
 
+  # @param state [String, Symbol, Number] The state to be set as the starting state.
+  # @return [String, Symbol, Number] The initial state.
   def initial_state(...); @state_machine.initial_state(...); end
 
+  # (see YATM::StateMachine#final_state)
   def final_state(...); @state_machine.final_state(...); end
 
+  # (see YATM::StateMachine#states)
   def states(...); @state_machine.states(...); end
 
   def events(...); @state_machine.events(...); end

data/lib/yatm/state_machine/state_machine.rb

@@ -4,7 +4,12 @@ require_relative "state_machine_errors"
 require_relative "event"
 
 class YATM::StateMachine
-  attr_reader :current_state, :events, :final_states, :initial_state
+  # The current state of the state machine
+  attr_reader :current_state
+  # @return [Array<YATM::StateMachine::Event>] A list of the events that can processed by the machine
+  attr_reader :events
+  # @return [Array] A list of the final states
+  attr_reader :final_states
 
   def initialize
     @events = {}
@@ -15,6 +20,14 @@ class YATM::StateMachine
     @current_state = @initial_state
   end
 
+  # @return [String] A string representation of the state machine
+  #
+  # @example Example output
+  #   puts state_machine.to_s
+  #
+  #   | states:  [:start, :A, :B, :end]
+  #   | current: :start
+  #   | events: [nil, 0, 1]
   def to_s
     <<~TO_S.chomp
       | states:  #{states}
@@ -23,33 +36,73 @@ class YATM::StateMachine
     TO_S
   end
 
+  # @return [Array] The list of all states of the state machine
   def states
     @events.map do |_name, event|
       event.keys + event.map { |_, val| val[:to] }
     end.flatten.uniq
   end
 
-  def initial_state(state)
+  # @overload initial_state(state)
+  #   @param state [#to_s && #to_sym] The state to be set as the starting state
+  #   @return [Object] The initial state
+  # @overload initial_state
+  #   @return [Object] The initial state
+  #
+  # @see states
+  def initial_state(state = nil)
+    return @initial_state if state.nil?
+
     @initial_state = self.class.statify(state)
     @current_state = @initial_state
   end
 
+  # @param states [#to_s && #to_sym] The state or array of states to be marked
+  #   as final states
+  # @return [Array] The complete list of final states
   def final_state(*states)
     states.each do |state|
       (@final_states << self.class.statify(state)).uniq!
     end
+    @final_states
   end
 
+  # @param name [Object] The name of the event.
+  #
+  #   Note that this is also the value which, when read from the tape, will
+  #   trigger the processing of this event.
+  # @param **transitions [Hash | Hash[, Hash...]] One or more transitions.
+  #
+  #   Transitions can be of the following forms:
+  #   - `state1 => [state2, value, movement]`
+  #   - `state1 => [state2, value]`
+  #   - `state1 => [state2]`
+  #   - `state1 => state2`
+  #   On all cases, the machine is going from `state1` to `state2`, writing
+  #   `value` on the current position of the tape, and moving the head in the
+  #   direction specified by `movement`.
+  # @return [YATM::StateMachine::Event] The event object creared
   def event(name, **transitions)
     @events[name] = YATM::Event.new(name, **transitions)
   end
 
+  # @param value [Object] Tape value to be processed (trigger corresponding
+  #   event) by the machine
+  # @return [Hash | nil] A representation of the transition which was triggered,
+  #   or nil if none was
   def process(value)
     process!(value)
   rescue StateMachineError
     nil
   end
 
+  # @param value [Object] Tape value to be processed (trigger corresponding
+  #   event) by the machine
+  # @return [Hash] A representation of the transition which was triggered
+  # @raise [InitialStateNotSet] No initial state was set. See {initial_state}
+  # @raise [InvalidEvent] There is no event registered under the given value
+  # @raise [InvalidTransition] There is an event registered under the given
+  #   value, but it contains no transitions from the machine's current state
   def process!(value)
     return { final: @current_state } if @final_states.include?(@current_state)
     raise InitialStateNotSet unless @current_state
@@ -62,12 +115,24 @@ class YATM::StateMachine
     transition
   end
 
-  def self.statify(state)
-    raise InvalidState, state unless state.respond_to?(:to_s)
+  class << self
+    # @param state [#to_s && #to_sym] The object to be statified
+    # @return [Symbol] The object's statified form
+    # @raise [InvalidState] The object given could not be statified
+    def statify!(state)
+      raise InvalidState, state unless state.respond_to?(:to_s)
+
+      state = state.to_s
+      raise InvalidState, state unless state.respond_to?(:to_sym)
 
-    state = state.to_s
-    raise InvalidState, state unless state.respond_to?(:to_sym)
+      state.to_sym
+    end
 
-    state.to_sym
+    # @param state [#to_s && #to_sym] The object to be statified
+    # @return [Symbol | nil] If the object could be statified, it's statified
+    #   form. Nil otherwise
+    def statify(state)
+      statify!(state) rescue StateMachineError
+    end
   end
 end

data/lib/yatm/tape/tape.rb

@@ -32,6 +32,7 @@ class YATM::Tape
       @pos -= 1
       expand if table_pos > tape.size
     when YATM::NONE
+      # do nothing
     else
       raise InvalidMove
     end

data/lib/yatm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module YATM
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/lib/yatm.rb

@@ -5,6 +5,7 @@ require_relative "yatm/tape/tape"
 require_relative "yatm/state_machine/state_machine"
 require_relative "yatm/machine/machine"
 
+# This is the main module.
 module YATM
   ANY   = :*
   SAME  = :_

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yatm
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - tiago-macedo
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-08-19 00:00:00.000000000 Z
+date: 2022-09-12 00:00:00.000000000 Z
 dependencies: []
 description: |-
   This gem provides you with the module `YATM`.