stateology 0.1.3 → 0.1.6

data/CHANGELOG

@@ -0,0 +1,9 @@
+
+
+3-12-08
+* nested states now supported
+26-11-08
+* can now provide state() (instance method) a block; the block will be invoked after the successful change of state
+
+23-11-08
+* supported subclassing of classes that include Stateology (see README)

data/README.markdown

@@ -0,0 +1,161 @@
+Stateology
+==========
+
+*Clean and fast Object state transitions in Ruby using the Mixology C extension.*
+
+Supports:
+* Dynamic switching between states (mixing and unmixing modules)
+* Clean DSL-style syntax 
+* Optional state\_entry() and state\_exit() hooks for each state (automatically called upon state entry and exit)
+* support for subclassing of classes that include Stateology (see below)
+* support for nested states, i.e states defined within other states
+
+Use as in the following:
+
+    class Sample
+        include Stateology
+        
+        state(:Happy) {
+            def state_entry
+                puts "entering Happy state"
+            end
+            
+            def do_something
+                puts "Pets a puppy"
+            end
+            
+            def state_exit
+                puts "exiting Happy state"
+            end
+        }
+        
+        state(:Angry) {
+            def state_entry
+                puts "entering Angry state"
+            end
+            
+            def do_something
+                puts "Kicks a puppy"
+            end
+            
+            def state_exit
+                puts "exiting Angry state"
+            end
+        }
+        
+        # methods declared outside a 'state' are not part of any state
+        
+        def state_entry
+            puts "entering Default state"
+        end
+        
+        def do_something
+            puts "stares at the ceiling"
+        end
+        
+        def state_exit
+            puts "exiting Default state"
+        end
+        
+        # if we want the state_entry to run on instantiation
+        # we must call it from the initialize method
+        def initialize
+            state_entry
+        end
+    
+    end
+
+    s = Sample.new
+
+    # in no state
+    s.do_something  #=> "stares at the ceiling"
+
+    # now switch to Happy state
+    s.state :Happy
+    s.do_something  #=> "Pets a puppy"
+
+    # now switch to Angry state
+    s.state :Angry
+    s.do_something  #=> "Kicks a puppy"
+
+    # now switch back to no state
+    s.state nil
+    s.do_something  #=> "stares at the ceiling"
+
+UPDATE:
+
+* made it so subclasses can inherit states from their superclasses e.g
+    
+
+        class A
+            include Stateology
+            
+            state(:Happy) {
+                def state_entry
+                    puts "entering Happy state"
+                end
+                
+                def hello
+                    puts "hello from A"
+                end
+            }
+        end
+
+        class B < A
+            state(:Happy) {
+                def hello
+                    puts "hello from B"
+                end
+            }
+        end
+
+        b = B.new
+
+        b.state :Happy
+        #=> "entering Happy state"
+
+        b.hello
+        #=> "hello from B"
+
+* prior behaviour was for state\_entry not to exist in class B as Happy module from class A was overwritten by the new Happy module in B
+* how does this fix work? the Happy module in B just includes any extant Happy module accessible in B
+
+
+
+
+A FEW THINGS TO NOTE
+--------------------
+
+* When an object is instantiated it begins life in no state and only ordinary instance methods are accessible (The ordinary instance methods are those defined outside of any state() {} block)
+
+* The ordinary instance methods are available to any state so long as they are not overridden by the state.
+
+* To change from any given state to 'no state' pass nil as a parameter to the state method
+e.g s.state nil
+
+* 'no state', while not a state, may nonetheless have state\_entry() and state\_exit() methods; and these methods will be invoked on 'entry' and exit from 'no state'
+
+* The state\_entry method for 'no state' is not automatically called on object instantiation. If you wish state\_entry to run when the object is instantiated invoke it in the initialize() method.
+
+* The state\_entry method can also accept parameters:
+e.g s.state :Happy, "hello"
+In the above the string "hello" is passed as a parameter to the state\_entry() method of the Happy state.
+
+* The #state method can accept either a Symbol (e.g :Happy) or a Module (e.g Happy or Sample::Happy). The following are equivalent:
+s.state :Happy #=> change state to Happy
+
+* The #state method can take a block; the block will be executed after the successful change of state:
+e.g s.state(:Happy) { s.hello }    #=> hello method invoked immediately after change of state as it's in the block
+
+s.state Sample::Happy #=> equivalent to above (note the fully qualified name; as Happy is a module defined under the Sample class)
+
+* alternatively; if the #state method is invoked internally by another instance method of the Sample class then a fully qualified module name is not required:
+state Happy #=> Fully qualified module name not required when #state invoked in an instance method
+
+* The #state method can also act as a 'getter' method when invoked with no parameters. It will return the current state name in Symbol form (e.g :Happy)
+
+* The #state\_mod method works similarly to the #state 'getter' except it returns the Module representing the current state (e.g Sample::Happy)
+
+* The #state?(state\_name) returns boolean true if the current state is equal to state\_name, and false if not. state\_name can be either a Module or a Symbol
+
+

data/lib/stateology.rb

@@ -7,7 +7,8 @@ end
 require 'mixology'
 
 module Stateology
-    
+    VERSION = "0.1.6"
+
     # alternative to 'nil'
     Default = nil
 
@@ -18,113 +19,171 @@ module Stateology
 
     # class methods
     module SM_Class_Methods
-        def state(name, &block)      
-            m = Module.new(&block)   
-                  
-            if constants.include?(name.to_s) then
-                inherited_state = const_get(name)
-                
-                # ignore if the constant is not a module                                
-                m.send(:include, inherited_state) if Module === inherited_state
+        def state(name, &block)
+
+            # if const is defined here then module_eval
+            if constants.include?(name.to_s) && const_defined?(name) then
+                self.module_eval(&block)
+            else
+
+                m = Module.new
+                # if the state is defined further up the chain then "inherit it"
+                if constants.include?(name.to_s) && !const_defined?(name) then
+                    # if constant not defined here then must be inherited
+                    inherited_state = const_get(name)
+
+                    # ignore if the constant is not a module
+                    m.send(:include, inherited_state) if inherited_state.instance_of?(Module)
+                end
+
+                m.send(:include, Stateology)
+                m.module_eval(&block)
+
+                const_set(name, m)
             end
-            
-            const_set(name, m)     
-            
         end
     end
-    
+
+    # strip the class path and return just the constant name, i.e Hello::Fren -> Fren
+    def __elided_class_path(sym)
+        "#{sym}".split(/::/).last.intern
+    end
+
+    def __sym_to_mod(sym)
+        class << self; self; end.const_get(sym)
+    end
+
+    def __mod_to_sym(mod)
+        # weird case where module does not have name (i.e when a state created on the eigenclass)
+        if mod.name == "" then
+            class << self; self; end.constants.each do |v|
+                return v.to_sym if __sym_to_mod(v.to_sym) == mod
+            end
+            return :ConstantNotDefined
+        end
+
+        mod.name.to_sym
+    end
+
+    # is state_name a nested state?
+    def __nested_state?(new_state)
+
+        # test is:
+        # (1) are we currently in a state? (non nil)
+        # (2) is the new state a state? (non nil)
+        # (3) is the new state defined under the current state? (i.e it's nested)
+        __current_state &&
+            new_state &&
+            __current_state.const_defined?(__elided_class_path(__mod_to_sym(new_state)))
+    end
+
     # instance methods
-    
-    def __state_epilogue(old_state) 
-    
+    def __state_epilogue
+
+        @__SM_nesting.each do |old_state|
+            raise NameError if !old_state.instance_of?(Module) && old_state != nil
+
+            begin
+                state_exit()
+            rescue NoMethodError
+                # do nothing
+            end
+
+            if old_state then unmix(old_state) end
+        end
+        @__SM_nesting = []
+    end
+
+    def __state_prologue(new_state, state_args, &block)
+
         # ensure that the constant is a module
-        raise NameError if(!(Module === old_state) && old_state != nil)
-               
+        raise NameError if !new_state.instance_of?(Module) && new_state != nil
+
+        # only mixin if non-nil (duh)
+        if new_state then extend(new_state) end
+
         begin
-            state_exit()
+            state_entry(*state_args, &block)
         rescue NoMethodError
             # do nothing
         end
-        
-        if old_state then unmix(old_state) end
+
     end
-        
-    def __state_prologue(new_state, state_args)
-    
-        # ensure that the constant is a module
-        raise NameError if(!(Module === new_state) && new_state != nil)
-        
-        # only mixin if 
-        if new_state then mixin(new_state) end
-        
-        begin  
-            state_entry(*state_args)                
-        rescue NoMethodError
-            # do nothing
+
+    def __validate_state_name(state_name)
+        # if we receive a Symbol convert it to a constant
+        if Symbol === state_name then
+            state_name = __sym_to_mod(state_name)
         end
-        
+
+        raise NameError if state_name && !state_name.instance_of?(Module)
+
+        state_name
+    end
+
+    def __state_transition(new_state, state_args, &block)
+        # preven unnecessary state transition
+        return if __current_state == new_state
+
+        # get rid of state_name from arg list
+        state_args.shift
+
+        # exit old state only if the new state is not nested within it
+        __state_epilogue unless __nested_state?(new_state)
+        __state_prologue(new_state, state_args, &block)
+
+        @__SM_nesting.unshift(new_state)
+    end
+
+    def __state_getter
+        __current_state ? __elided_class_path(__mod_to_sym(__current_state)) : nil
+    end
+
+    def __current_state
+        @__SM_nesting ||= [nil]
+        @__SM_nesting.first
     end
-        
+
     def state(*state_args, &block)
-                                            
+
         # behave as getter
-        if(state_args.empty?) then            
-            return @__SM_cur_state ? "#{@__SM_cur_state}".split(/::/).last.intern : nil
-        end
-        
-        # behave as setter (only care about first argument)
-        state_name = state_args.shift
-        
-        # if we receive a Symbol convert it to a constant
-        if(Symbol === state_name) then
-            state_name = self.class.const_get(state_name)
+        if state_args.empty? then
+            return __state_getter
         end
-                
-        # prevent unnecessary state transitions
-        return if(@__SM_cur_state == state_name)
-          
-        # exit old state                                   
-        __state_epilogue(@__SM_cur_state)                   
-        
-                    
-        # enter new state               
-        __state_prologue(state_name, state_args)   
-                        
-        # update the current state variable    
-        @__SM_cur_state = state_name
-        
-        # if we were given a block, run it now
-        if(block) then yield end
-        
-        rescue NameError
-            raise NameError, "#{state_name} not a valid state" 
-                                        
+
+        new_state = __validate_state_name(state_args.first)
+
+        __state_transition(new_state, state_args, &block)
+
+        # return value is the current state
+        __current_state
+
+    rescue NameError
+        raise NameError, "#{new_state} not a valid state"
+
     end
-    
+
     # is the current state equal to state_name?
     def state?(state_name)
-    
-        # if we receive a Symbol convert it to a constant
-        if(Symbol === state_name) then
-            state_name = self.class.const_get(state_name)
-        end
-        
-        raise NameError if(!(Module === state_name) && state_name != nil)
-        
-        state_name == @__SM_cur_state
-        
-        rescue NameError
-            raise NameError, "#{state_name} not a valid state" 
-                                                            
+
+        state_name = __validate_state_name(state_name)
+
+        # compare
+        state_name == __current_state
+
+    rescue NameError
+        raise NameError, "#{state_name} not a valid state"
+
     end
-    
+
     # return the current state as a module
     def state_mod
-        @__SM_cur_state
+        __current_state
     end
-                   
-    private :__state_prologue, :__state_epilogue
-        
+
+    private :__state_prologue, :__state_epilogue, :__elided_class_path, :__mod_to_sym, :__sym_to_mod,
+    :__nested_state?, :__current_state, :__validate_state_name, :__state_transition, :__state_getter
+
 end
 
 

data/test/test.rb

@@ -0,0 +1,239 @@
+require 'test/unit'
+require '../lib/stateology'
+
+class Object
+    def meta
+        class << self; self; end
+    end
+end
+
+class ParentState
+    include Stateology
+    attr_reader :state_entry_check
+    attr_reader :state_exit_check
+    
+    def state_entry
+        @state_entry_check = "entry_nil"
+    end
+    
+    def state_exit
+        @state_exit_check = "exit_nil"
+    end
+    
+    state(:State1) {
+    
+        def state_entry
+            @state_entry_check = "entry_state1"
+        end
+        
+        def act
+            1
+        end
+        
+        def state1_act
+            1
+        end
+        
+        def state_exit  
+            @state_exit_check = "exit_state1"
+        end
+        
+        state(:State1_nested) {
+            def state_entry(&block) 
+                puts "balls-deep in State1_nested!"
+                if block then yield end
+            end
+            def act
+                1.5
+            end
+        }
+    }
+    
+    state(:State2) {
+        def act
+            2
+        end
+        
+        def state2_act
+            2
+        end
+    }
+    
+    
+    def act
+        0
+    end
+end
+
+class ChildState < ParentState
+    state(:State1) {
+        def act_child
+            1
+        end
+    }
+    
+    state(:State2) {
+        def act_child
+            2
+        end
+    }
+    
+    def act
+        0
+    end         
+end
+
+class StateologyTest < Test::Unit::TestCase
+    puts "testing Stateology #{Stateology::VERSION}"
+
+    def test_nil_state
+        s = ParentState.new
+        assert_equal(0, s.act)
+        assert_equal(nil, s.state_exit_check)
+        assert_equal(nil, s.state_entry_check)
+        assert_raises(NoMethodError) { s.state1_act }
+    end
+    
+    def test_transition_from_nil_state
+        s = ParentState.new
+        assert_equal(0, s.act)
+        assert_equal(nil, s.state_exit_check)
+        assert_equal(nil, s.state_entry_check)
+        s.state :State1 
+        assert_equal("exit_nil", s.state_exit_check)
+        assert_equal("entry_state1", s.state_entry_check)        
+        assert_equal(1, s.act)
+    end
+    
+    def test_transition_to_nil_state
+        s = ParentState.new
+        s.state :State1
+        assert_equal(1, s.act)                  
+        s.state nil
+        assert_equal("exit_state1", s.state_exit_check)
+        assert_equal("entry_nil", s.state_entry_check)
+        assert_equal(0, s.act)
+        assert_raises(NoMethodError) { s.state1_act }
+    end
+
+    def test_transition_from_state1_to_state2
+        s = ParentState.new
+        s.state :State1
+        assert_equal(1, s.act)
+        assert_raises(NoMethodError) { s.state2_act }
+        s.state :State2
+        assert_equal(2, s.act)
+        assert_raises(NoMethodError) { s.state1_act }
+    end
+    
+    def test_inheritance_of_state
+        s = ChildState.new
+        s.state :State1
+        
+        # testing inherited state methods
+        assert_equal(1, s.act)
+        assert_equal(1, s.state1_act)
+        
+        # testing own method
+        assert_equal(1, s.act_child)
+    end
+    
+    def test_cant_transition_to_nested_from_nil             
+      s = ParentState.new                               
+      assert_raises(NameError){  s.state(:State1_nested1) }
+    end                                                 
+
+    
+    def test_nested_state
+        s = ParentState.new
+        s.state :State1
+        s.state :State1_nested
+        assert_equal(1.5, s.act)
+        assert_equal(1, s.state1_act)
+        s.state nil
+        assert_raises(NoMethodError) { s.state1_act }
+        assert_equal(0, s.act)
+    end
+    
+    def test_state_getter
+      s = ParentState.new
+      assert_equal(nil, s.state)
+      
+      s.state :State1
+      assert_equal(:State1, s.state)
+      
+      s.state :State1_nested
+      assert_equal(:State1_nested, s.state)
+    end
+
+    def test_state_compare
+      s = ParentState.new
+      assert_equal(true, s.state?(nil))
+      
+      s.state :State1
+      assert_equal(false, s.state?(nil))
+      assert_equal(true, s.state?(:State1))
+      
+      s.state :State1_nested
+      assert_equal(false, s.state?(:State1))
+      assert_equal(true, s.state?(:State1_nested))
+      
+      s.state nil
+      assert_equal(true, s.state?(nil))
+    end
+
+    def test_state_defined_on_singleton
+      s = ParentState.new
+      
+      class << s
+        state(:Sing_state) { 
+          def state_entry
+            @state_entry_check = "sing_entry"
+          end
+          
+          def act
+            99
+          end
+
+          def state_exit
+            @state_exit_check = "sing_exit"
+          end
+        }
+      end
+
+      assert_equal(0, s.act)
+      
+      s.state :Sing_state
+      
+      # test the getter
+      assert_equal(:Sing_state, s.state)
+
+      # test state_entry
+      assert_equal("sing_entry", s.state_entry_check)
+      
+      # test the act function
+      assert_equal(99, s.act)
+
+      # test state compare
+      assert_equal(true, s.state?(:Sing_state))
+      
+      s.state nil
+
+      # test state_exit
+      assert_equal("sing_exit", s.state_exit_check)
+            
+    end
+
+end 
+        
+        
+        
+        
+        
+        
+    
+    
+    
+        
+    
+    

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: stateology
 version: !ruby/object:Gem::Version 
-  version: 0.1.3
+  version: 0.1.6
 platform: ruby
 authors: 
 - John Mair
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-11-14 00:00:00 +13:00
+date: 2008-12-03 00:00:00 +13:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -31,10 +31,12 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
-- README
+- README.markdown
 - LICENSE
 - lib/stateology.rb
 - sample.rb
+- CHANGELOG
+- test/test.rb
 has_rdoc: false
 homepage: http://banisterfiend.wordpress.com
 post_install_message: 

data/README

@@ -1,153 +0,0 @@
-Clean and fast Object state transitions in Ruby using the Mixology C extension.
-
-Supports:
-* Dynamic switching between states (mixing and unmixing modules)
-* Clean DSL-style syntax 
-* Optional state_entry() and state_exit() hooks for each state (automatically called upon state entry and exit)
-* support for subclassing of classes that include Stateology (see below)
-
-Use as in the following:
-
-class Sample
-    include Stateology
-    
-    state(:Happy) {
-        def state_entry
-            puts "entering Happy state"
-        end
-        
-        def do_something
-            puts "Pets a puppy"
-        end
-        
-        def state_exit
-            puts "exiting Happy state"
-        end
-    }
-    
-    state(:Angry) {
-        def state_entry
-            puts "entering Angry state"
-        end
-        
-        def do_something
-            puts "Kicks a puppy"
-        end
-        
-        def state_exit
-            puts "exiting Angry state"
-        end
-    }
-    
-    # methods declared outside a 'state' are not part of any state
-    
-    def state_entry
-        puts "entering Default state"
-    end
-    
-    def do_something
-        puts "stares at the ceiling"
-    end
-    
-    def state_exit
-        puts "exiting Default state"
-    end
-    
-    # if we want the state_entry to run on instantiation
-    # we must call it from the initialize method
-    def initialize
-        state_entry
-    end
-    
-end
-
-s = Sample.new
-
-# in no state
-s.do_something  #=> "stares at the ceiling"
-
-# now switch to Happy state
-s.state :Happy
-s.do_something  #=> "Pets a puppy"
-
-# now switch to Angry state
-s.state :Angry
-s.do_something  #=> "Kicks a puppy"
-
-# now switch back to no state
-s.state nil
-s.do_something  #=> "stares at the ceiling"
-
-UPDATE:
-* made it so subclasses can inherit states from their superclasses e.g
-class A
-    include Stateology
-    
-    state(:Happy) {
-        def state_entry
-            puts "entering Happy state"
-        end
-        
-        def hello
-            puts "hello from A"
-        end
-    }
-end
-
-class B < A
-    state(:Happy) {
-        def hello
-            puts "hello from B"
-        end
-    }
-end
-
-b = B.new
-
-b.state :Happy
-#=> "entering Happy state"
-
-b.hello
-#=> "hello from B"
-
-* prior behaviour was for state_entry not to exist in class B as Happy module from class A was overwritten by the new Happy module in B
-* how does this fix work? the Happy module in B just includes any extant Happy module accessible in B
-
-
-
-
----=A FEW THINGS TO NOTE=---
-
-* When an object is instantiated it begins life in no state and only ordinary instance methods are accessible (The ordinary instance methods are those defined outside of any state() {} block)
-
-* The ordinary instance methods are available to any state so long as they are not overridden by the state.
-
-* To change from any given state to 'no state' pass nil as a parameter to the state method
-e.g s.state nil
-
-* 'no state', while not a state, may nonetheless have state_entry() and state_exit() methods; and these methods will be invoked on 'entry' and exit from 'no state'
-
-* The state_entry method for 'no state' is not automatically called on object instantiation. If you wish state_entry to run when the object is instantiated invoke it in the initialize() method.
-
-* The state_entry method can also accept parameters:
-e.g s.state :Happy, "hello"
-In the above the string "hello" is passed as a parameter to the state_entry() method of the Happy state.
-
-* The #state method can accept either a Symbol (e.g :Happy) or a Module (e.g Happy or Sample::Happy). The following are equivalent:
-s.state :Happy #=> change state to Happy
-
-* The #state method can take a block; the block will be executed after the successful change of state:
-e.g s.state(:Happy) { s.hello }    #=> hello method invoked immediately after change of state as it's in the block
-
-s.state Sample::Happy #=> equivalent to above (note the fully qualified name; as Happy is a module defined under the Sample class)
-
-* alternatively; if the #state method is invoked internally by another instance method of the Sample class then a fully qualified module name is not required:
-state Happy #=> Fully qualified module name not required when #state invoked in an instance method
-
-* The #state method can also act as a 'getter' method when invoked with no parameters. It will return the current state name in Symbol form (e.g :Happy)
-
-* The #state_mod method works similarly to the #state 'getter' except it returns the Module representing the current state (e.g Sample::Happy)
-
-* The #state?(state_name) returns boolean true if the current state is equal to state_name, and false if not. state_name can be either a Module or a Symbol
-
-* One last note: state(:Name) {} is just DSL-style syntactic sugar for module Name...end