barebone-fsm 0.0.1.1 → 0.0.1.2

data/README.rdoc

@@ -0,0 +1,86 @@
+== Overview
+This module implements a basic finite-state machine (FSM).
+An FSM consists of a finite number of states,
+with one of them being the current state of the FSM.
+Transitions are defined between states, which are triggered on events.
+For details on FSM, see this wiki page: {FSM}[http://en.wikipedia.org/wiki/Finite-state_machine].
+
+The motivation behind the module was to implement a very basic barebone FSM in Ruby.
+Features are kept at minimum as well as the code.
+Only two classes for the FSM are defined as the following:
+* FSM -> the finite state machine class
+* FSMState -> the state class
+
+Author:: Md. Imrul Hassan (mailto:mihassan@gmail.com)
+Copyright:: Copyright: Md. Imrul Hassan, 2013
+
+== Features
+Apart from having support for states and events, this module offers the following features:
+1. Default state
+2. Default event for each state
+3. Entry and exit events for each state
+4. DSL like coding style
+5. Access to state variables (including @state and @event) inside event blocks.
+   Currently the state variables can only be shared among event blocks of the same state.
+
+== Usage
+The FSM can be setup and triggered Succinctly using Domain Specific Language(DSL) like coding style.
+There are two methods to build and run which are defined for both FSM and FSMState classes.
+These methods, #build and #run, are alias of each other and can be used interchangebly.
+A basic fintite-state machine for a microwave is simulated in the following example:
+
+  fsm = FSM::FSM.new(:stopped) # :stopped is the default state to fall back
+  
+  fsm.build do # the states and events can be configured within the build block
+    state :stopped do # the events can be setup within the state block for :stopped state
+      event :open do # the event block is run when the event :open is triggered
+        puts "[Stopped]: Door Opened"
+        :open # the return value of the event block, :open, is the next state
+      end
+      event :start do
+        puts "[Stopped]: Started"
+        :started
+      end
+    end
+    state :open do
+      event :close do
+        puts "[#{@state}]: Door #{@event}" # the event block has access to state variables such as @state and @event
+        :stopped
+      end
+    end
+    state :started do
+      event :open do
+        @open_time = Time::now # new state variables can be defined
+        puts "[Started]: Door Opened"
+        :open
+      end
+      event :stop do
+        puts "The door was opened at #{@open_time}" # state variables from other event blocks can be used
+        puts "[Started]: Door Stopped after #{elapsed_time}"
+        :stopped
+      end
+    end
+  end
+  
+  fsm.run do # the events can be triggered from the run block
+    event :start
+    event :open
+    event :close
+    event :start
+    event :stop
+  end
+  
+  puts fsm
+
+== Status
+The module works as it is, but further testing and documentation is needed.
+The api is not stable yet, it may go trhough lots of changes before the first stable version is released.
+I am open to any suggestion or request to support custom features.
+
+== Changes
+* Version: 0.0.1.2
+  * @state instance variable for FSM is dropped in favour of the #state instance method.
+  * #state method and index operator [] now accept nil arguement for state name, which returns the current state.
+  * Two methods #build and #run are added to FSM and FSMState classes to support DSL like features.
+  * Explicit parameter passing for the event blocks is no longer available. 
+    Instead the block code for the events now have access to all instance variables of FSMState class such as @state and @event.

data/lib/barebone-fsm.rb

@@ -1,6 +1,4 @@
 ##
-# == Overview
-# ---
 # This module implements a basic finite-state machine (FSM).
 # An FSM consists of a finite number of states,
 # with one of them being the current state of the FSM.
@@ -12,62 +10,12 @@
 # Only two classes for the FSM are defined as the following:
 # * FSM -> the finite state machine class
 # * FSMState -> the state class
+# 
+# For further details see the README file.
 #
 # Author:: Md. Imrul Hassan (mailto:mihassan@gmail.com)
 # Copyright:: Copyright: Md. Imrul Hassan, 2013
 #
-# == Status
-# The module works, but further testing and documentation is needed.
-# The api is not stable yet, I may decide to change the way FSM is used.
-#
-# == Features
-# Apart from having support for states and events, this module offers the following features:
-# 1. Default state
-# 2. Default event for each state
-# 3. Entry and exit events for each state
-#
-# == Usage
-# ---
-# A simple example:
-#
-#   fsm = FSM::FSM.new
-#   state = fsm[:state_name]
-#   state.event(:event_name) do |st, ev| 
-#     puts "#{ev} triggered on state #{st}"
-#     :new_state}
-#   end
-#   fsm.event :event_name
-#
-# A complete example:
-#
-#   fsm = FSM::FSM.new(:stopped)
-# 
-#   fsm[:stopped].event(:open) { puts "[Stopped]: Door Opened"; :open}
-#   fsm[:stopped].event(:start) { puts "[Stopped]: Started"; :started}
-#   fsm[:stopped].event(:enter) {|st, ev| puts "[Stopped]: Eneter into state #{st}"}
-#   fsm[:stopped].event(:exit) {|st, ev| puts "[Stopped]: Exit from state #{st}"}
-# 
-#   fsm[:open].event(:close) { puts "[Open]: Door Closed"; :stopped}
-#   fsm[:open].event(:default) {|st, ev| puts "[Open]: Event [#{ev}] not defined in state #{st}"; :open}
-#   fsm[:open].event(:enter) {|st, ev| puts "[Open]: Eneter into state #{st}"}
-#   fsm[:open].event(:exit) {|st, ev| puts "[Open]: Exit from state #{st}"}
-# 
-#   fsm[:started].event(:open) { puts "[Started]: Door Opened"; :open}
-#   fsm[:started].event(:stop) { puts "[Started]: Stopped"; :stopped}
-#   fsm[:started].event(:enter) {|st, ev| puts "[Started]: Eneter into state #{st}"}
-#   fsm[:started].event(:exit) {|st, ev| puts "[Started]: Exit from state #{st}"}
-# 
-#   puts fsm
-# 
-#   fsm.event :open
-#   fsm.event :start 
-#   fsm.event :close 
-#   fsm.event :start 
-#   fsm.event :stop 
-#   fsm.event :start
-# 
-#   puts sm
-# 
 module FSM
 
   # == Overview
@@ -83,31 +31,45 @@ module FSM
   #
   class FSMState
 
-    attr_reader :name
+    # The readonly state variable represents an unique state.
+    # Though it can have any data type, usage of symbol or string is preferable.
+    attr_reader :state
 
     def initialize(state_name) 
-      @name = state_name
+      @state = state_name
       @events = {}
     end
 
     def to_s() 
-      @name.to_s + 
+      @state.to_s + 
         ": [" + 
           @events.keys.map(&:to_s).join(', ') + 
         "]" 
     end
 
+    # When the event_block is provided, it sets up a new event for this state.
+    # Otherwise, when the event_block is missing, the event_name is triggered.
+    # If the event is nil or not already setup, then the default event is triggered.
     def event(event_name, &event_block)
-      if block_given? then
+      if event_name and block_given? then
         @events[event_name] = event_block
-      else
-        if @events.has_key? event_name then
-          @events[event_name].call @name, event_name
-        elsif @events.has_key? :default then
-          @events[:default].call @name, event_name
-        end
+      elsif event_name and @events.has_key? event_name then
+        @event = event_name
+        self.instance_eval &@events[@event]
+      elsif @events.has_key? :default then
+        @event = :default
+        self.instance_eval &@events[@event]
       end
     end
+
+    # The #build/#run method sets up the events as given in the build_block.
+    # Only event method is supported within the build_block with the name of the event and an optional block supplied.
+    # The operation for each such line is carried out by the #event method.
+    def build(&build_block)
+      self.instance_eval &build_block
+    end
+
+    alias_method :run, :build
     
   end
 
@@ -131,7 +93,6 @@ module FSM
   #   end
   #
   class FSM
-    attr_reader :state
 
     def initialize(default_state=nil) 
       @states = {}
@@ -145,19 +106,36 @@ module FSM
       "FSM" + 
         ": {" + 
           @states.values.map{ |st| 
-            (st.name==@state ? ">" : "") + st.to_s
+            (st.state==@state ? ">" : "") + st.to_s
           }.join(', ') + 
         "}" 
     end
     
-    def [](state_name) 
-      unless @states.has_key? state_name then
+    # It returns the FSMState object for state_name.
+    # If the state is missing, then it first sets up the state, and then returns the newly created state.
+    def [](state_name=nil) 
+      state_name ||= @state
+      if state_name and not @states.has_key? state_name then
         @states[state_name] = FSMState.new(state_name)
         @state ||= state_name
       end
       @states[state_name]
     end
+
+    # When the state_block is provided, it sets up a new state.
+    # Otherwise, when the state_block is missing, the FSMState object for state_name is returned.
+    # If called without any parameter, then the current state is returned.
+    def state(state_name=nil, &state_block)
+      if block_given? then
+        self.[](state_name).build &state_block
+      else
+        self.[](state_name)
+      end
+    end
     
+    # It triggers the event_name event and changes the state of the FSM to its new state.
+    # The :entry and :exit events are called on the leaving state and the entering state.
+    # If the event does not mention the new state, then the state changes to the default state.
     def event(event_name) 
       @states[@state].event :exit
       new_state = @states[@state].event event_name
@@ -168,5 +146,15 @@ module FSM
       @states[@state].event :enter
     end
     
+    # The #build/#run method sets up the states and events as given in the build_block.
+    # Only state and event methods are supported within the build_block with the name of the state/event and a block supplied.
+    # The operation for each such line is carried out by the #state/#event method.
+    def build(&build_block)
+      self.instance_eval &build_block
+    end
+  
+    alias_method :run, :build
+
   end
-end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: barebone-fsm
 version: !ruby/object:Gem::Version
-  version: 0.0.1.1
+  version: 0.0.1.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,16 +9,18 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-18 00:00:00.000000000 Z
+date: 2013-01-19 00:00:00.000000000 Z
 dependencies: []
 description: A barebone implementation of finite state machine keeping simplicity
   in mind.
 email: mihassan@gmail.com
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.rdoc
 files:
 - lib/barebone-fsm.rb
+- README.rdoc
 homepage: http://rubygems.org/gems/barebone-fsm
 licenses: []
 post_install_message: