baby_bots 0.0.3 → 0.0.4

data/lib/baby_bots/baby_bot.rb

@@ -1,42 +1,63 @@
+# A tiny finite-state automata library.
+#
+# Author:: Justin Hamilton (mailto:justinanthonyhamilton@gmail.com)
+# Copyright :: BSD2 (see LICENSE for more details)
+
 module BabyBots
 
+  # Error to handle attempts to transition to a state that does not exist.
   class NoSuchStateException < Exception
   end
 
+  # Error to handle attempts to use a transition that does not exist.
   class NoSuchTransitionException < Exception
   end
 
+  # A tiny finite-state automata class.
   class BabyBot
     attr_accessor :curr, :states, :start
 
+    # Accepts an optional hash of states.
     def initialize(states={})
+      # Hash of state names to state objects
       @states = states
+      # Initial state
       @start = nil
+      # Current state
       @curr = nil
     end
 
-    # add a new state to the state machine
+    # Adds a new state to the finite-state automata, also accepts
+    # an optional start flag, which will set the supplied state as the initial
+    # state. Note that this machine may only have one start state. Additionally,
+    # adding the first start state will set @curr to be this state, after this
+    # has been done @curr will remain on whatever state it is currently residing
+    # on, and must be reset using the reset method.
     def add_state(state, start=nil)
-      # key on state names to the actual state hash
+      # key on state names to the actual state object
       @states[state.state] = state
+
+      # if this is a start state
       if start
         @start = state
-        @curr = @start
+
+        # only set the current state to the start state if @curr is nil.
+        if @curr.nil? then @curr = @start end
       end
     end
 
+    # Build up this machine's states with a given state table. The format of
+    # this table is assumed to be {state_name => {event1 => transition1, ...}}.
+    # build assumes that the first state provided is the start state, although
+    # the optional no_first parameter may be set to override this.
+    def build(table, no_first=false)
+      first_state = !no_first
 
-    # accepts a hash of hashes consiting of {state => {event => transition, ...} ...}
-    # structure, and adds these states to the state machine, assumes first state
-    # is the starting state
-    def build(table)
-      first_state = true
-      
-      # iterate through the provided {state => {event => transition, ...}, ...}
+      # iterate through each provided state table entries
       table.each do |state, state_table|
         temp_state = State.new(state)
-        
-        # iterate through each event and transition, building up the transitions
+
+        # iterate through the current state table, adding events => transition
         state_table.each do |event, transition|
           temp_state.add_transition(event, transition)
         end
@@ -48,13 +69,20 @@ module BabyBots
       end
     end
 
+    # Return the current state's actual state.
     def state
       @curr.state
     end
 
-    # this is the driving function behind the fsa, process
-    # will check the current state, doing any processing necessary
-    # on the input based on whether or not this 
+    # Process the finite state automata with the given event.
+    # This will first see if the finite state automata has a defined method
+    # named "pre_{current_state}", and if so "cook" the input event with this
+    # method. Process will then use the cooked input if available, or the raw
+    # input if there is none to compute the transition. Before actually 
+    # transitioning, it will then send the raw output to a method of
+    # "post_{current_state}", which will be the return value. If a method named
+    # "post_cook_{current_state}" is supplied, it will send the cooked event to
+    # this method instead of using "post_{current_state}".
     def process(event=nil)
       # get the current state
       curr_state = @curr
@@ -64,12 +92,15 @@ module BabyBots
         cooked_event = send("pre_#{@curr.state}", event)
       end
 
+      # calculate the next state
       if cooked_event
         next_state = @states[curr.table[cooked_event]]
       else
         next_state = @states[curr.table[event]]
       end
 
+      # if there is no such transition, see if there is an a translation
+      # known as else, and use that as the next state
       if next_state.nil?
         next_state = @states[curr.table[:else]]
       end
@@ -89,7 +120,6 @@ module BabyBots
         ret_val = send("post_#{@curr.state}", cooked_event)
       end
       
-
       # actually transition, and make sure such a transition exists
       @curr = next_state
       if @curr.nil?
@@ -100,6 +130,7 @@ module BabyBots
       return ret_val
     end
 
+    # Reset the current state to be the start state.
     def restart
       @curr = @start
     end

data/lib/baby_bots/state.rb

@@ -1,22 +1,49 @@
 module BabyBots
+  # Transition state used to remove events from a transition table.
+  NOWHERE = :nowhere__
 
+  # The state contained within the BabyBots Finite State Automata.
+  # States have an event that transitions to a new state. They may also
+  # have an event named :else which will be the transition used by the
+  # containing BabyBot when calculating transitions where no such supplied
+  # events exist.
   class State 
     attr_reader :state, :table
     
+    # Sets the state name, as well as an optionally supplied transition table.
     def initialize(state, table={})
+      # state name
       @state = state
+      
+      # transition table
       @table = table
     end
 
-    def add_transition(event, transition, &callback)
-      @table[event] = transition
+    # Adds a transition to the transition table. Table format is 
+    # event => transition, where event is the "input" into the state.
+    #
+    # Transitions are allowed to be deleted by being set to NOWHERE.
+    def add_transition(event, transition)
+      if transition == NOWHERE
+        remove_transition(event)
+      else
+        @table[event] = transition
+      end
     end
 
-    # the idea behind build is that you can call multiple
-    # :event :transition and the build method
-    # will parse them out and add them to state
-    def build(*args)
-      args.map {|k,v| add_transition(k, v) }
+    # Provided a table, merge the state's current transition table
+    # with the supplied one. Note that since this is part of a 
+    # finite state machine, supplying events that already exist
+    # in the transition table override this transition.
+    def build(table)
+      table.each { |k,v| add_transition(k, v) }
+    end
+
+
+    # Delete an entry from the transition table.
+    def remove_transition(event)
+      @table.delete(event)
     end
   end
+
 end

data/lib/baby_bots/version.rb

@@ -1,3 +1,4 @@
 module BabyBots
-  VERSION = "0.0.3"
+  # Current development version
+  VERSION = "0.0.4"
 end

data/spec/baby_bot_spec.rb

@@ -0,0 +1,32 @@
+require 'spec_helper.rb'
+
+$loading = BabyBots::State.new(:loading, {1 => :ready, :else => :loading})
+$ready   = BabyBots::State.new(:ready,   {1 => :run, :else => :loading})
+$run     = BabyBots::State.new(:run,     {:else => :run})
+                               
+
+TEST_MACHINE1 = { :loading => {1 => :ready, :else => :loading},
+                                   :ready   => {1 => :run, :else => :loading},
+                                   :run     => {:else => :run} }
+
+describe BabyBots::BabyBot do
+  it "should be able to be initiated with no additional initialization" do
+    test = BabyBots::BabyBot.new
+    test.states.should == {}
+  end
+
+  it "should be able to be initialized with a state table" do
+    test = BabyBots::BabyBot.new(TEST_MACHINE1)
+    test.states.should == TEST_MACHINE1
+  end
+
+  it "should have states be able to be added using add_state" do
+    test = BabyBots::BabyBot.new
+    test.add_state($loading)
+    test.states.should == {:loading => $loading}
+    test.add_state($ready)
+    test.states.should == {:loading => $loading, :ready => $ready}
+    test.add_state($run)
+    test.states.should == {:loading => $loading, :ready => $ready, :run => $run}
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+require_relative '../lib/baby_bots/baby_bot.rb'
+require_relative '../lib/baby_bots/state.rb'
+
+

data/spec/state_spec.rb

@@ -0,0 +1,80 @@
+require 'spec_helper.rb'
+
+TEST_NAME     = :test
+TEST_TRANS1_1 = {0 => :test}
+TEST_TRANS1_2 = {1 => :done}
+TEST_TRANS1_3 = {:else => :test}
+TEST_TABLE1   = TEST_TRANS1_1.merge TEST_TRANS1_2.merge TEST_TRANS1_3
+TEST_TABLE2   = {2 => :two, 3 => :three}
+
+
+describe BabyBots::State do
+  it "should require a state name" do
+    test = BabyBots::State.new(TEST_NAME)
+    test.state.should == TEST_NAME
+  end
+
+  it "should provide an empty transition table if none is supplied" do
+    test = BabyBots::State.new(TEST_NAME)
+    test.state.should == TEST_NAME
+    test.table.should == {}
+  end
+
+  it "should accept a state name and transition table" do
+    test = BabyBots::State.new(TEST_NAME, TEST_TABLE1)
+    test.state.should == TEST_NAME
+    test.table.should == TEST_TABLE1
+  end
+
+  it "should be able to have its transition table built after construction" do
+    test = BabyBots::State.new(TEST_NAME)
+    test.table.should == {}
+    test.build(TEST_TABLE1)
+    test.table.should == TEST_TABLE1
+  end
+
+  it "should merge changes between uses of build" do
+    test = BabyBots::State.new(TEST_NAME, TEST_TABLE2)
+    test.table.should == TEST_TABLE2
+    test.build(TEST_TABLE1)
+    test.table.should == TEST_TABLE2.merge(TEST_TABLE1)
+  end
+    
+  it "should allow transitions to be added piece-by-piece via add_transition" do
+    test = BabyBots::State.new(TEST_NAME)
+    test.table.should == {}
+    test.add_transition(0, :test)
+    test.table.should == {0 => :test}
+    test.add_transition(1, :done)
+    test.table.should == {0 => :test, 1 => :done}
+    test.add_transition(:else, :test)
+    test.table.should == TEST_TABLE1
+  end
+  
+  it "should allow transitions to be overwritten using add_transition" do
+    test = BabyBots::State.new(TEST_NAME, TEST_TABLE1)
+    test.table.should == TEST_TABLE1
+    test.add_transition(:else, :error)
+    test.table.should == TEST_TRANS1_1.merge(TEST_TRANS1_2.merge({:else => :error}))
+  end
+  
+  it "should allow transitions to be overwritten using build" do
+    test = BabyBots::State.new(TEST_NAME, TEST_TABLE1)
+    test.build({:else => :error})
+    test.table.should == TEST_TRANS1_1.merge(TEST_TRANS1_2.merge({:else => :error}))
+  end
+
+  it "should allow transitions to be removed using remove_transition" do
+    test = BabyBots::State.new(TEST_NAME, TEST_TABLE1)
+    test.remove_transition(:else)
+    test.table.should == TEST_TRANS1_1.merge(TEST_TRANS1_2)
+  end
+
+  it "should allow transitions to be deleted by setting their transition to NOWHERE" do
+    test = BabyBots::State.new(TEST_NAME, TEST_TABLE1)
+    test.add_transition(:else, BabyBots::NOWHERE)
+    test.table.should == TEST_TRANS1_1.merge(TEST_TRANS1_2)
+    test.build({0 => BabyBots::NOWHERE, 1 => BabyBots::NOWHERE})
+    test.table.should == {}
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: baby_bots
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -27,6 +27,9 @@ files:
 - lib/baby_bots/baby_bot.rb
 - lib/baby_bots/state.rb
 - lib/baby_bots/version.rb
+- spec/baby_bot_spec.rb
+- spec/spec_helper.rb
+- spec/state_spec.rb
 homepage: https://github.com/jamiltron/BabyBots
 licenses: []
 post_install_message: 
@@ -53,4 +56,7 @@ specification_version: 3
 summary: While there are many fsa libraries out there, I wanted to implement my own
   so I could learn how to create a module/gem, as I am not really a Ruby guy and have
   no idea how.
-test_files: []
+test_files:
+- spec/baby_bot_spec.rb
+- spec/spec_helper.rb
+- spec/state_spec.rb