simplificator-fsm 0.1.0 → 0.2.0

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009 pascalbetz
+Copyright (c) 2009 simplificator
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -1,7 +1,7 @@
 = fsm
 
-Description goes here.
+FSM is a simple finite state machine
 
 == Copyright
 
-Copyright (c) 2009 pascalbetz. See LICENSE for details.
+Copyright (c) 2009 simplificator GmbH. See LICENSE for details.

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :major: 0
-:minor: 1
+:minor: 2
 :patch: 0

data/lib/fsm.rb

@@ -1,33 +1,32 @@
-require File.join(File.dirname(__FILE__), 'fsm', 'errors')
-require File.join(File.dirname(__FILE__), 'fsm', 'machine')
-require File.join(File.dirname(__FILE__), 'fsm', 'machine_config')
-require File.join(File.dirname(__FILE__), 'fsm', 'state')
-require File.join(File.dirname(__FILE__), 'fsm', 'transition')
-require File.join(File.dirname(__FILE__), 'fsm', 'executable')
+%w[options errors machine state transition executable builder].each do |item|
+  require File.join(File.dirname(__FILE__), 'fsm', item)
+end
 
 module FSM
   module ClassMethods
     def define_fsm(&block)
-      raise "FSM is already defined. Call define_fsm only once" if Machine[self]
-      machine = Machine.new(self)
-      Machine[self] = machine
-      config = MachineConfig.new(machine)
-      config.process(&block)
-      machine.post_process
+      raise 'FSM is already defined. Call define_fsm only once' if Machine[self]
+      builder = Builder.new(self)
+      Machine[self] = builder.process(&block)
+      self.instance_eval() do 
+        alias_method "fsm_state_attribute", Machine[self].current_state_attribute_name
+        define_method(Machine[self].current_state_attribute_name) do
+          value = fsm_state_attribute
+          value ? value : Machine[self.class].initial_state_name
+        end
+      end
     end
-    
-
   end
   
   module InstanceMethods
     #
     # Which states are reachable from the current state
     def reachable_state_names
-      Machine[self.class].reachable_states.map() {|item| item.name}
+      Machine[self.class].reachable_states(self).map() {|item| item.name}
     end
     
     def available_transition_names
-      Machine[self.class].available_transitions.map() {|item| item.name}
+      Machine[self.class].available_transitions(self).map() {|item| item.name}
     end
   end
   

data/lib/fsm/builder.rb

@@ -0,0 +1,52 @@
+module FSM
+  # Builder exposees 'only' (well there are some other methods exposed) the methods that are required to build the configuration
+  class Builder
+    
+    # Blank Slate
+    instance_methods.each do |m| 
+      undef_method m unless  m == '__send__' || m == '__id__' || m == 'instance_eval'
+    end
+    
+    # Create a new Builder which creates a Machine for the target_class
+    def initialize(target_class)
+      @target_class = target_class
+      @machine = Machine.new(target_class)
+    end
+    
+    def process(&block)
+      raise ArgumentError.new('Block expected') unless block_given?
+      self.instance_eval(&block)
+      @machine
+    end
+    
+    private
+    # Add a transition
+    #  * name of the transition 
+    #  * from_name: name of the source state (symbol)
+    #  * to_name: name of the target state (symbol)
+    #  * options
+    #  
+    def transition(name, from_name, to_name, options = {})
+      @machine.transition(name, from_name, to_name, options)
+      nil # do not expose FSM details
+    end
+    
+    def state_attribute(name)
+      raise ArgumentError.new('Invalid attribute name') if name == nil
+      @machine.current_state_attribute_name = name
+      nil # do not expose FSM details
+    end
+    
+    def initial(name)
+      @machine.initial_state_name = name
+      nil # do not expose FSM details
+    end
+    
+    def state(name, options = {})
+      @machine.state(name, options)
+      nil # do not expose FSM details
+    end
+    
+    
+  end
+end

data/lib/fsm/executable.rb

@@ -2,24 +2,31 @@ module FSM
   #
   # Execute an action specified by either String, Sylbol or Proc.
   # Symbol and String represent methods which are called on the target object, Proc will get executed 
-  # and receives at least the target as parameter
+  # and receives at least the target as parameter. If others parameters are passed then they'll get forwarded as well.
   class Executable
     # Create a new Executable
     # if args is true, then arguments are passed on to the target method or the Proc, if false nothing 
     # will get passed
-    def initialize(thing, args = false)
+    def initialize(thing)
+      raise ArgumentError.new("Unknown thing #{thing}") unless thing
       @thing = thing
-      @has_arguments = args
     end
     
     # execute this executable on the given target
-    def execute(target, args)
+    def execute(target, *args)
       case @thing
       when String, Symbol:
-        @has_arguments ? target.send(@thing, *args) : target.send(@thing)
+        if (args.length > 0)
+          target.send(@thing, *args)
+        else
+          target.send(@thing)
+        end
       when Proc:
-        @has_arguments ? @thing.call(target, *args) : @thing.call(target)
-      when Nil:
+        if (args.length > 0) 
+          @thing.call(target, *args)
+        else
+          @thing.call(target)
+        end
       else
         raise "Unknown Thing #{@thing}"
       end

data/lib/fsm/machine.rb

@@ -1,11 +1,11 @@
 module FSM
   class Machine
-    attr_accessor(:current_state, :states, :state_attribute)
+    attr_accessor(:initial_state_name, :current_state_attribute_name, :states)
     
-    def initialize(klass)
-      @klass = klass
+    def initialize(target_class)
+      @target_class = target_class
       self.states = {}
-      self.state_attribute = :state
+      self.current_state_attribute_name = :state
     end
     
     def self.[](includer)
@@ -19,76 +19,69 @@ module FSM
     def state(name, options = {})
       raise "State is already defined: '#{name}'" if self.states[name]
       self.states[name] = State.new(name, options)
-      initial(name) unless self.current_state
-      nil
+      self.initial_state_name=(name) unless self.initial_state_name
     end
     
-    def initial(name)
-      self.current_state = self.states[name]
-      raise UnknownState.new("Unknown state '#{name}'. Define states first with state(name)") unless self.current_state
-      nil
+    def initial_state_name=(value)
+      raise UnknownState.new("Unknown state '#{value}'. Define states first with state(name)") unless self.states[value]
+      @initial_state_name = value
     end
     
     def transition(name, from_name, to_name, options = {})
       raise ArgumentError.new("name, from_name and to_name are required") if name.nil? || from_name.nil? || to_name.nil?
       raise UnknownState.new("Unknown source state '#{from}'") unless self.states[from_name]
       raise UnknownState.new("Unknown target state '#{to}'") unless self.states[to_name]
-      define_transition_method(name, to_name)
+      
       from_state = self.states[from_name]
       to_state = self.states[to_name]
+      
       transition = Transition.new(name, from_state, to_state, options)
-      from_state.transitions[to_state.name] = transition
-      nil
+      from_state.add_transition(transition)
+      
+      define_transition_method(name, to_name)
+      
     end
     
-    def attribute(name)
-      self.state_attribute = name
+    def self.get_current_state_name(target)
+      value = target.send(Machine[target.class].current_state_attribute_name)
+      (value && value.is_a?(String)) ? value.intern : value
     end
     
-    def reachable_states()
-      self.states.map do |name, state|
-        state.to_states if state == current_state
-      end.flatten.compact
+    def self.set_current_state_name(target, value)
+      target.send("#{Machine[target.class].current_state_attribute_name}=", value)
     end
+
     
-    def available_transitions()
-      current_state.transitions.values  
+    def reachable_states(target)
+      reachables = []
+      current_state_name = Machine.get_current_state_name(target)
+      self.states.map do |name, state|
+        reachables += state.to_states if state.name == current_state_name
+      end
+      reachables
     end
     
-    
-    def post_process
-      define_state_attribute_methods(self.state_attribute)
+    def available_transitions(target)
+      self.states[Machine.get_current_state_name(target)].transitions.values
     end
     
-    
-    
     private
     
-    def define_state_attribute_methods(name)
-      @klass.instance_eval do
-        define_method("#{name}") do 
-          Machine[self.class].current_state.name
-        end
-        
-        define_method("#{name}=") do |value|
-          Machine[self.class].current_state = Machine[self.class].states[value]
-          raise("Unknown State #{value}") unless Machine[self.class].current_state
-        end
-      end
-    end
-    
     def define_transition_method(name, to_name)
-      @klass.instance_eval do
+      @target_class.instance_eval do
         define_method(name) do |*args|
-          from_state = Machine[self.class].current_state
-          to_state = Machine[self.class].states[to_name]
+          machine = Machine[self.class]
+          from_name = Machine.get_current_state_name(self)
+          from_state = machine.states[from_name]
+          to_state = machine.states[to_name]
           transition = from_state.transitions[to_name]
-          raise InvalidStateTransition.new("No transition defined from #{from_state.name} -> #{to_state.name}") unless transition
+          raise InvalidStateTransition.new("No transition defined from #{from_name} -> #{to_name}") unless transition
           
           from_state.exit(self)
           transition.fire_event(self, args)
           to_state.enter(self)
-          Machine[self.class].current_state = to_state
+          Machine.set_current_state_name(self, to_name)
+          true # at the moment always return true ... as soon as we have guards or thelike this could be false as well 
         end
       end
     end

data/lib/fsm/options.rb

@@ -0,0 +1,17 @@
+module FSM
+  module Options
+    module InstanceMethods
+      def assert_options(options, optional_keys = {}, mandatory_keys = {})
+        keys_processed = []
+        mandatory_keys.each do |key|
+          raise ArgumentError.new("Mandatory Key #{key} is missing") unless options.keys.include?(key)
+          keys_processed << key
+        end
+        options.keys.each do |key|
+          raise ArgumentError.new("Unsupported key #{key}") unless optional_keys.include?(key) || mandatory_keys.include?(key)
+        end
+      end 
+    end
+    
+  end
+end

data/lib/fsm/state.rb

@@ -3,6 +3,7 @@ module FSM
   # A State has a name and a list of outgoing transitions.
   # 
   class State
+    include FSM::Options::InstanceMethods
     attr_reader(:name, :transitions)
     
     # name: a symbol which identifies this state
@@ -10,28 +11,38 @@ module FSM
     #  * :enter : a symbol or string or Proc
     #  * :exit : a symbol or string or Proc
     def initialize(name, options = {})
+      raise ArgumentError.new('Name is required') unless name
+      assert_options(options, [:enter, :exit])
       @name = name
-      @enter = Executable.new options[:enter]
-      @exit = Executable.new options[:exit]
+      @enter = Executable.new options[:enter] if options.has_key?(:enter)
+      @exit = Executable.new options[:exit] if options.has_key?(:exit)
       @transitions = {}
     end
     
     # Called when this state is entered
     def enter(target)
-      @enter.execute(target, nil)
+      @enter.execute(target) if @enter
+      nil
     end
     # Called when this state is exited
     def exit(target)
-      @exit.execute(target, nil)
+      @exit.execute(target) if @exit
+      nil
     end    
     
+    def add_transition(transition)
+      raise ArgumentError.new("#{self} already has a transition to '#{transition.name}'") if @transitions.has_key?(transition.name)
+      raise ArgumentError.new("the transition '#{transition.name}' is already defined") if @transitions.detect() {|to_name, tr| transition.name == tr.name}
+      @transitions[transition.to.name] = transition
+    end
+    
     # All states that are reachable form this state by one hop
     def to_states
-      self.transitions.map { |to_name, transition| transition.to}
+      @transitions.map { |to_name, transition| transition.to}
     end
     
     def to_s
-      "State '#{self.name}' (#{self.object_id})"
+      "State '#{self.name}'"
     end
 
   end

data/lib/fsm/transition.rb

@@ -1,16 +1,20 @@
 module FSM
   class Transition
+    include FSM::Options::InstanceMethods
     attr_accessor(:name, :from, :to, :event)
     def initialize(name, from, to, options = {})
+      raise ArgumentError.new("name, from and to are required but were '#{name}', '#{from}' and '#{to}'") unless name && from && to
+      assert_options(options, [:event])
       self.name = name
       self.from = from
       self.to = to
-      self.event = Executable.new options[:event], true
+      self.event = Executable.new options[:event] if options.has_key?(:event)
     end
     
     def fire_event(target, args)
-      self.event.execute(target, args)
+      self.event.execute(target, *args) if self.event
     end    
+    
     def to_s
       "Transition from #{self.from.name} -> #{self.to.name} with event #{self.event}"
     end    

data/test/executable_test.rb

@@ -0,0 +1,33 @@
+require 'test_helper'
+
+class ExecutableTest < Test::Unit::TestCase
+  context 'Should execute method without arguments' do
+    should 'with symbol' do
+      assert_equal 4, FSM::Executable.new(:length).execute('1234')
+    end
+    should 'with string' do
+      assert_equal 4, FSM::Executable.new('length').execute('1234')
+    end
+    should 'with proc' do
+      assert_equal 4, FSM::Executable.new(lambda { |target| target.length }).execute('1234')
+    end
+  end
+  
+  context 'Should execute method with arguments' do
+    should 'with symbol' do
+      assert_equal 'firstlast', FSM::Executable.new(:+).execute('first', 'last')
+    end
+    should 'with string' do
+      assert_equal 'firstlast', FSM::Executable.new('+').execute('first', 'last')
+    end
+    
+    should 'with proc varargs' do
+      assert_equal 'some things are good', FSM::Executable.new(lambda {|target, *args| args.join(' ') }).execute(:foo, 'some', 'things', 'are', 'good')
+    end
+    
+    should 'with proc' do
+      assert_equal 'some things', FSM::Executable.new(lambda {|target, a, b| "#{a} #{b}" }).execute(:foo, 'some', 'things')
+    end
+    
+  end
+end

data/test/invoice_sample_test.rb

@@ -0,0 +1,67 @@
+require 'test_helper'
+
+class Invoice
+  attr_accessor(:state, :amount)
+  include FSM
+  define_fsm do
+    state_attribute(:state) 
+    state(:open)
+    state(:paid)
+    state(:refunded)
+    
+    transition(:pay, :open, :paid, :event => :event_paid)
+    transition(:refund, :paid, :refunded)
+  end
+  
+  
+  def initialize(state = :open, amount = 1000)
+    self.state = state
+    self.amount = amount
+  end
+  
+  private
+  def event_paid(amount_paid)
+    raise "Not enough paid" unless amount_paid == self.amount
+    self.amount -= amount_paid
+  end
+end
+
+class InvoiceTest < Test::Unit::TestCase
+  context 'Invoice' do
+    
+    should 'Initial State is the first state defined unless no initial() call was made' do
+      invoice = Invoice.new
+      assert_equal(:open, invoice.state)
+    end
+    
+    should 'Accept an initial state from outside' do
+      invoice = Invoice.new(:paid)
+      assert_equal(:paid, invoice.state)
+    end
+    
+    should 'Trasition to paid and then refunded' do
+      invoice = Invoice.new
+      assert_equal(:open, invoice.state)
+      
+      invoice.pay(1000)
+      assert_equal(:paid, invoice.state)
+      
+      invoice.refund
+      assert_equal(:refunded, invoice.state)
+    end
+    
+    should 'Raise on illegal transition' do
+      invoice = Invoice.new
+      assert_raise(FSM::InvalidStateTransition) do
+        invoice.refund
+      end
+    end
+    
+    should 'Pass the arguments to the event handler' do
+      invoice = Invoice.new
+      invoice.pay(1000)
+      assert_equal(0, invoice.amount)
+    end
+    
+  end
+end

data/test/options_test.rb

@@ -0,0 +1,37 @@
+require 'test_helper'
+
+class OptionsTest < Test::Unit::TestCase
+  include FSM::Options::InstanceMethods
+  context 'assert_options' do
+    should 'allow empty options' do
+      assert_options({})
+    end
+    should('throw on unknown key') do
+      assert_raise(ArgumentError) do
+        assert_options({:foo => 12}, [], [])
+      end
+      assert_raise(ArgumentError) do
+        assert_options({:foo => 12}, [:optional], [])
+      end
+      assert_raise(ArgumentError) do
+        assert_options({:foo => 12}, [], [:mandatory])
+      end
+      assert_raise(ArgumentError) do
+        assert_options({:foo => 12}, [:optional], [:mandatory])
+      end
+    end
+    should('find missong mandatory options') do
+      assert_raise(ArgumentError) do
+        assert_options({}, [], [:foo])
+      end
+      assert_raise(ArgumentError) do
+        assert_options({:foo => 12}, [], [:bar])
+      end
+      assert_raise(ArgumentError) do
+        assert_options({:foo => 12}, [:bar], [:bar])
+      end
+      assert_options({:foo => 42}, [], [:foo])
+      assert_options({:foo => 42}, [:foo], [:foo])
+    end
+  end
+end

data/test/state_test.rb

@@ -0,0 +1,21 @@
+require 'test_helper'
+
+class StateTest < Test::Unit::TestCase
+  context 'Initializer' do
+    should 'require name' do
+      assert_raise(ArgumentError) do
+        FSM::State.new(nil, nil, nil)
+      end
+     
+      FSM::State.new('bla')
+    end
+    
+    should 'allow only valid options' do
+      assert_raise(ArgumentError) do
+        FSM::State.new('bla', :foo => 12)
+      end
+      FSM::State.new('bla', :enter => :some)
+      FSM::State.new('bla', :exit => :some)
+    end
+  end
+end

data/test/transition_test.rb

@@ -0,0 +1,38 @@
+require 'test_helper'
+
+class TransitionTest < Test::Unit::TestCase
+  context 'Initializer' do
+    should 'require name, from and to' do
+      assert_raise(ArgumentError) do
+        FSM::Transition.new(nil, nil, nil)
+      end
+      assert_raise(ArgumentError) do
+        FSM::Transition.new('bla', nil, nil)
+      end
+      assert_raise(ArgumentError) do
+        FSM::Transition.new(nil, 'bli', nil)
+      end
+      assert_raise(ArgumentError) do
+        FSM::Transition.new(nil, nil, 'blo')
+      end
+      assert_raise(ArgumentError) do
+        FSM::Transition.new('bli', 'bli', nil)
+      end
+      assert_raise(ArgumentError) do
+        FSM::Transition.new(nil, 'blo', 'blo')
+      end
+      assert_raise(ArgumentError) do
+        FSM::Transition.new('blo', nil, 'bli')
+      end
+      
+      FSM::Transition.new('bla', 'bli', 'blo')
+    end
+    
+    should 'allow only valid options' do
+      assert_raise(ArgumentError) do
+        FSM::Transition.new('bla', 'bli', 'blo', :foo => 12)
+      end
+      FSM::Transition.new('bla', 'bli', 'blo', :event => :some)
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: simplificator-fsm
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - simplificator
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-05-14 00:00:00 -07:00
+date: 2009-05-18 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -28,14 +28,19 @@ files:
 - Rakefile
 - VERSION.yml
 - lib/fsm.rb
+- lib/fsm/builder.rb
 - lib/fsm/errors.rb
 - lib/fsm/executable.rb
 - lib/fsm/machine.rb
-- lib/fsm/machine_config.rb
+- lib/fsm/options.rb
 - lib/fsm/state.rb
 - lib/fsm/transition.rb
-- test/fsm_test.rb
+- test/executable_test.rb
+- test/invoice_sample_test.rb
+- test/options_test.rb
+- test/state_test.rb
 - test/test_helper.rb
+- test/transition_test.rb
 has_rdoc: true
 homepage: http://github.com/simplificator/fsm
 post_install_message: 
@@ -63,5 +68,9 @@ signing_key:
 specification_version: 3
 summary: A simple finite state machine (FSM) gem.
 test_files: 
-- test/fsm_test.rb
+- test/executable_test.rb
+- test/invoice_sample_test.rb
+- test/options_test.rb
+- test/state_test.rb
 - test/test_helper.rb
+- test/transition_test.rb

data/lib/fsm/machine_config.rb

@@ -1,21 +0,0 @@
-module FSM
-  class MachineConfig
-    CONFIG_METHODS = %w[state transition initial attribute]
-    instance_methods.each do |m| 
-      undef_method m unless  m == '__send__' || m == '__id__' || m == 'instance_eval'
-    end
-    
-    def initialize(target)
-      @target = target
-    end
-    
-    def process(&block)
-      instance_eval(&block)
-    end
-    
-    def method_missing(sym, *args, &block)
-      raise "Unknown config method '#{sym}'. Only #{CONFIG_METHODS.map() {|item| "'#{item}'" }.join(', ')} are known" unless CONFIG_METHODS.include?(sym.to_s)
-      @target.__send__(sym, *args, &block)
-    end
-  end
-end

data/test/fsm_test.rb

@@ -1,7 +0,0 @@
-require 'test_helper'
-
-class FsmTest < Test::Unit::TestCase
-  should "probably rename this file and start testing for real" do
-    flunk "hey buddy, you should probably rename this file and start testing for real"
-  end
-end