solid_state 1.0.0

data/.gitignore

@@ -0,0 +1 @@
+.*.swp

data/README.textile

@@ -0,0 +1,104 @@
+h2. Solid State - Stateful Ruby objects with a twist
+
+Most stateful libraries that exist for Ruby deal with keeping track of a state variable, which is a symbol or string stating what state said object is currently in. This works well with libraries like ActiveRecord where you're usually simply interested in data.  But what if you want to change the functionality according to what state the object is in?  With tools like ActsAsStateMachine, you'll still need to pepper your methods with checks on which state the object is in:
+
+<pre><code>
+  if state == :this
+  elsif state == :that
+  else
+    ...
+  end
+</code></pre>
+
+Enter *solid_state*. The Ruby state machine library that lets you define state-specific functionality.  But enough yammering, nothing can describe a system like a simple example.
+
+Please note: this library is *not* a full state machine. See the *Notes* section below.
+
+h3. Example
+
+Lets say you have a simple AI that needs to act differently according to what state it's currently in.  We'll define the states :persue, :scared, and :idle.
+
+<pre><code>
+  class AI
+    include SolidState
+
+    state :persue do
+      def update
+        # Chase the target!
+      end
+    end
+
+    state :scared do
+      def update
+        # Run away from the target!
+      end
+    end
+
+    state :idle do
+      def update
+        # Look for a new target
+      end
+    end
+
+    starting_state :idle
+  end
+</code></pre>
+
+This one example shows almost the entirity of solid_state's simple API. Include the SolidState module, define your states, and optionally set a starting state. To using this class is simple:
+
+<pre><code>
+  ai = AI.new
+  ai.current_state          # => :idle
+  ai.update                 # => looking for a target...
+
+  # Target found!
+  ai.change_state! :persue
+  ai.update                 # => Rawr! Chasing target
+
+  # I'm hurt!
+  ai.change_state! :scared
+  ai.update                 # => Run away and find help!
+
+  ai.change_state! :dead    # => InvalidStateError ... aw
+</code></pre>
+
+This also works seemlessly with subclasses. For example:
+
+<pre><code>
+  class Scavenger < AI
+
+    state :scavange do
+      def update
+        # Scavange!
+      end
+    end
+
+  end
+
+  ai = Scavanger.new
+  ai.current_state            # => :idle
+  ai.change_state! :scavange
+  ai.update                   # => Scavaging!
+
+  a.change_state! :idle
+  a.update
+</code></pre>
+
+h3. Notes
+
+To be fair, other state machine libraries do offer this functionality. I'm do this to be a learning experience and to make as bare-bones a state machine system as I can, for when you don't need a full state machine (transitions, validation, transition direction enforcement, etc).
+
+If you're looking for a fully comprehensive state machine library, "state_machine":http://github.com/pluginaweek/state_machine is the most detailed I've found yet and probably can do anything you need to do.
+
+h3. Possible Issues
+
+Individual states are implemented underneath as inner Classes that subclass the current Class. This means they get access to all public and protected methods in the outer Class, but at the same time if there are state methods with the same name as methods on the outer class, the state methods will never get called.
+
+h3. Project Info
+
+Install via gems: gem install solid_state --source http://gemcutter.org
+
+Code hosted on Github: http://github.com/jameskilton/solid_state
+
+Issues on Github: http://github.com/jameskilton/solid_state/issues
+

data/Rakefile

@@ -0,0 +1,26 @@
+require 'rake/testtask'
+
+task :default => :test
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = Dir["test/*_test.rb"]
+  t.verbose = true
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "solid_state"
+    gem.summary = %Q{Stateful Ruby objects}
+    gem.description = %Q{Add simple states to your classes with different functionality across states.}
+    gem.email = "jameskilton@gmail.com"
+    gem.homepage = "http://github.com/jameskilton/solid_state"
+    gem.authors = ["Jason Roelofs"]
+    gem.add_development_dependency "test-spec"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/lib/solid_state.rb

@@ -0,0 +1,83 @@
+module SolidState
+
+  class InvalidStateError < RuntimeError; end
+
+  # On include, setup all required methods
+  def self.included(base)
+    base.extend(ClassMethods)
+    base.send(:include, InstanceMethods)
+  end
+
+  module ClassMethods
+
+    # Define a state
+    def state(name, &block)
+      klass = const_set("State_#{name}", Class.new(self))
+      klass.send(:define_method, :state_name) { name }
+      klass.class_eval(&block)
+    end
+
+    # Define the starting state
+    def starting_state(name)
+      self.send(:define_method, :__start_state) { name }
+    end
+
+  end
+
+  module InstanceMethods
+
+    # What's the current state
+    def current_state
+      got = @__current_state ||= (self.respond_to?(:__start_state) ?
+                                  self._find_state(self.__start_state) : nil)
+      got ? got.state_name : nil
+    end
+
+    # Change the current state
+    def change_state!(name)
+      found = _find_state(name)
+      raise InvalidStateError.new("No state defined with name #{name}") if found.nil?
+      @__current_state = found
+    end
+
+    # Proxy off any unknown method into the current state object
+    def method_missing(name, *args)
+      current_state
+
+      if @__current_state.respond_to?(name)
+        @__current_state.send(name, *args)
+      else
+        super
+      end
+    end
+
+    protected
+
+    def _known_states
+      @__known_states ||= {}
+    end
+
+    def _find_state(name)
+      const_name = "State_#{name}"
+      self._known_states ||= {}
+
+      self._known_states[name] ||= _get_state_const(const_name)
+    end
+
+    # To allow for subclasses to use superclass states, we need
+    # to traverse up the heirarchy looking for the constants
+    # defined. This works because klass.ancectors[0] == klass,
+    # so if the const is defined on this klass, we get it quickly.
+    def _get_state_const(const_name)
+      self.class.ancestors.each do |klass|
+        if klass.const_defined?(const_name)
+          return klass.const_get(const_name).new
+        end
+      end
+
+      nil
+    end
+
+  end
+
+end

data/test/solid_state_test.rb

@@ -0,0 +1,151 @@
+$:.unshift File.expand_path(File.join(File.dirname(__FILE__), "..", "lib"))
+
+require 'rubygems'
+require 'test/spec'
+
+require "solid_state"
+
+class Stateful
+  include SolidState
+
+  def helper
+    14
+  end
+
+  def outer
+    10
+  end
+
+  state :start do
+
+    def add(a, b)
+      a + b
+    end
+
+    def use_helper
+      helper
+    end
+    
+  end
+
+  state :next do
+
+    def add(a, b)
+      a - b
+    end
+
+    # This method will never get called
+    # because of #outer defined outside
+    # of this state
+    def outer
+      20
+    end
+
+  end
+
+  state :last do 
+
+    def add(a, b)
+      a * b
+    end
+
+  end
+end 
+
+class SubState < Stateful
+
+  state :another do
+
+    def add(a, b)
+      a % b
+    end
+
+  end
+
+  starting_state :another
+
+end
+
+context "SolidState" do
+
+  before do
+    @stateful = Stateful.new
+  end
+
+  context "Query and changing state" do
+
+    specify "can get current state" do
+      @stateful.current_state.should.be nil
+      @stateful.change_state! :start
+      @stateful.current_state.should.equal :start
+    end
+
+    specify "can change states" do
+      @stateful.change_state! :next
+      @stateful.current_state.should.equal :next
+    end
+
+    specify "errors out on invalid state choice" do
+      should.raise SolidState::InvalidStateError do
+        @stateful.change_state! :fail_state
+      end
+
+      @stateful.current_state.should.not.equal :fail_state
+    end
+
+    specify "can have a start state" do
+      Stateful.starting_state :start
+      Stateful.new.current_state.should.equal :start
+    end
+
+  end
+
+  context "Per-state functionality" do
+
+    specify "properly uses methods defined in the current state" do
+      @stateful.change_state! :start
+      @stateful.add(2, 4).should.equal 6
+
+      @stateful.change_state! :next
+      @stateful.add(2, 4).should.equal -2
+
+      @stateful.change_state! :last
+      @stateful.add(2, 4).should.equal 8
+    end
+
+    specify "states have access to methods defined outside of states" do
+      @stateful.change_state! :start
+      @stateful.use_helper.should.equal 14
+      @stateful.helper.should.equal 14
+    end
+
+    specify "state's don't have to have the same methods defined across" do
+      @stateful.change_state! :next
+      should.raise NoMethodError do
+        @stateful.use_helper
+      end
+      @stateful.helper.should.equal 14
+    end
+
+    specify "WARNING: helper methods named the same as state methods use helper methods" do
+      @stateful.change_state! :next
+      @stateful.outer.should.equal 10
+    end
+
+  end
+
+  context "Subclassing" do
+
+    specify "subclasses can use parent class states" do
+      state = SubState.new
+      state.current_state.should.equal :another
+      state.add(5, 2).should.equal 1
+
+      should.not.raise SolidState::InvalidStateError do
+        state.change_state! :next
+      end
+    end
+
+  end
+
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: solid_state
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Jason Roelofs
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-09-12 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: test-spec
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: Add simple states to your classes with different functionality across states.
+email: jameskilton@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.textile
+files: 
+- .gitignore
+- README.textile
+- Rakefile
+- VERSION
+- lib/solid_state.rb
+- test/solid_state_test.rb
+has_rdoc: true
+homepage: http://github.com/jameskilton/solid_state
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+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.3.5
+signing_key: 
+specification_version: 3
+summary: Stateful Ruby objects
+test_files: 
+- test/solid_state_test.rb