stateology 0.1.0

data/LICENSE

@@ -0,0 +1,14 @@
+    Copyright (c) 2008 John Mair
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 
+"Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, 
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following 
+conditions:
+
+    The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, 
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE 
+OR OTHER DEALINGS IN THE SOFTWARE.
+

data/README

@@ -0,0 +1,113 @@
+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)
+
+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"
+
+
+
+---=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
+
+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

data/lib/stateology.rb

@@ -0,0 +1,118 @@
+begin
+    require 'rubygems'
+rescue LoadError
+    # do nothing
+end
+
+require 'mixology'
+
+
+module Stateology
+    
+    # alternative to 'nil'
+    Default = nil
+
+    # bring in class methods on include
+    def self.included(c)
+        c.extend(SM_Class_Methods)
+    end
+
+    # class methods
+    module SM_Class_Methods
+        def state(name, &block)      
+         
+            const_set(name, Module.new(&block))                                    
+        end
+    end
+    
+    # instance methods
+    
+    def __state_epilogue(old_state) 
+    
+        # ensure that the constant is a module
+        raise NameError if(!(Module === old_state) && old_state != nil)
+               
+        begin
+            state_exit()
+        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
+        end
+        
+    end
+        
+    def state(*state_args)
+                                            
+        # 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)
+        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
+        
+        rescue NameError
+            raise NameError, "#{state_name} 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" 
+                                                            
+    end
+    
+    # return the current state as a module
+    def state_mod
+        @__SM_cur_state
+    end
+                   
+    private :__state_prologue, :__state_epilogue
+end
+
+

data/sample.rb

@@ -0,0 +1,80 @@
+require 'lib/stateology'
+
+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 part of the Default 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 Default state_entry to run on instantiation
+    # we must call it from the initialize method
+    def initialize
+        state_entry
+    end
+    
+end
+
+s = Sample.new
+
+# in Default 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 Sample::Angry
+s.do_something  #=> "Kicks a puppy"
+
+# now switch back to Default state
+s.state nil
+s.do_something  #=> "stares at the ceiling"
+
+s.state :Angry
+
+# what state are we in?
+puts s.state
+
+
+
+

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification 
+name: stateology
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- John Mair
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-11-14 00:00:00 +13:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: mixology
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.1.0
+    version: 
+description: Clean and fast Object state transitions in Ruby using the Mixology C extension
+email: jrmair@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README
+- LICENSE
+- lib/stateology.rb
+- sample.rb
+has_rdoc: false
+homepage: http://banisterfiend.wordpress.com
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Clean and fast Object state transitions in Ruby using the Mixology C extension.
+test_files: []
+