state_manager 0.2.3

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,18 @@
+source "http://rubygems.org"
+
+gem 'activesupport'
+
+group :development do
+  gem "rdoc", "~> 3.12"
+  gem 'pry'
+  gem 'pry-doc'
+  gem 'pry-remote'
+  gem 'pry-nav'
+  gem 'pry-stack_explorer'
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.8.3"
+  gem 'delayed_job_active_record'
+  gem 'activerecord'
+  gem 'sqlite3'
+  gem 'timecop'
+end

data/Gemfile.lock

@@ -0,0 +1,74 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (3.2.3)
+      activesupport (= 3.2.3)
+      builder (~> 3.0.0)
+    activerecord (3.2.3)
+      activemodel (= 3.2.3)
+      activesupport (= 3.2.3)
+      arel (~> 3.0.2)
+      tzinfo (~> 0.3.29)
+    activesupport (3.2.3)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    arel (3.0.2)
+    binding_of_caller (0.6.7)
+    builder (3.0.0)
+    coderay (1.0.6)
+    delayed_job (3.0.1)
+      activesupport (~> 3.0)
+    delayed_job_active_record (0.3.2)
+      activerecord (> 2.1.0)
+      delayed_job (~> 3.0.0)
+    git (1.2.5)
+    i18n (0.6.0)
+    jeweler (1.8.3)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.7.3)
+    method_source (0.7.1)
+    multi_json (1.3.5)
+    pry (0.9.9.6)
+      coderay (~> 1.0.5)
+      method_source (~> 0.7.1)
+      slop (>= 2.4.4, < 3)
+    pry-doc (0.4.2)
+      pry (>= 0.9.0)
+      yard (~> 0.8.1)
+    pry-nav (0.2.1)
+      pry (~> 0.9.9)
+    pry-remote (0.1.4)
+      pry (~> 0.9.9)
+      slop (~> 2.1)
+    pry-stack_explorer (0.4.2)
+      binding_of_caller (~> 0.6.2)
+      pry (~> 0.9.9)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    slop (2.4.4)
+    sqlite3 (1.3.6)
+    timecop (0.3.5)
+    tzinfo (0.3.33)
+    yard (0.8.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord
+  activesupport
+  bundler (~> 1.0.0)
+  delayed_job_active_record
+  jeweler (~> 1.8.3)
+  pry
+  pry-doc
+  pry-nav
+  pry-remote
+  pry-stack_explorer
+  rdoc (~> 3.12)
+  sqlite3
+  timecop

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Gordon Hempton
+
+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.md

@@ -0,0 +1,241 @@
+# State Manager
+
+StateManager is a state machine implementation for Ruby that is heavily inspired by the FSM implementation in [Ember.js](http://emberjs.com). Compared to other FSM implementations, it has the following defining characteristics:
+
+* Sub-states are supported (e.g. 'submitted.reviewing').
+* State logic can be kept separate from model classes.
+* State definitions are modular, underlying each state is a separate class definition.
+* Supports integrations. Comes out of the box with an integration with active_record and delayed_job to support automatic delayed transtions.
+
+We believe this is an improvement over existing state machines, but just for good measure, check out [state_machine](https://github.com/pluginaweek/state_machine) and [workflow](https://github.com/geekq/workflow).
+
+## Getting Started
+
+Install the `state_manager` gem. If you are using bundler, add the following to your Gemfile:
+
+```
+gem 'state_manager'
+```
+
+After the gem is installed, create a file to contain the definition of your state manager, e.g. `app/states/post_states.rb`. Edit this file and define your states:
+
+```ruby
+class PostStates < StateManager::Base
+  state :unsubmitted do
+    event :submit, :transitions_to => 'submitted.awaiting_review'
+  end
+  state :submitted
+    event :reject, :transitions_to => 'rejected'
+    state :awaiting_review do
+      event :review, :transitions_to => 'submitted.reviewing'
+    end
+    state :reviewing do
+      event :accept, :transitions_to => 'active'
+      event :clarify, :transitions_to => 'submitted.clarifying'
+    end
+    state :clarifying do
+      event :review, :transitions_to => 'submitted.reviewing'
+    end
+  end
+  state :active
+  state :rejected
+end
+```
+
+Once your states are defined, you need to extend the `StateManager::Resource` module on your resource class and define a state managed property:
+
+```ruby
+class Post
+  attr_accessor :state
+  extend StateManager::Resource
+  state_manager
+end
+```
+
+The code above infers the existence of `PostStates` class and a `state` property. An alternate states definition and property could be specified as follows:
+
+```ruby
+class Post
+  attr_accessor :workflow_state
+  extend StateManager::Resource
+  state_manager :workflow_state, PostStates
+end
+```
+
+## Helper Methods
+
+Unless otherwise specified with `{:helpers => false}` as the third argument to the `state_manager` macro, helper methods will be added to the resource class. In the above example, some of the methods that will be available are:
+
+```ruby
+post = Post.new
+post.unsubmitted? # true, the post will initially be in the 'unsubmitted' state
+post.can_submit? # true, the 'submit' event is defined on the current state
+post.can_review? # false, the 'review' event is not defined on the current state
+post.submit! # invokes the submit event
+post.submitted_awaiting_review? # true, the post is in the 'submitted.awaiting_review' state
+post.submitted? # true, the 'submitted' state is a parent of the current state
+```
+
+## Handling Events
+
+Most applications will require special logic to be performed during state transitions. Handlers for events can be defined as follows:
+
+```ruby
+class PostStates < StateManager::Base
+  state :unsubmitted do
+    event :submit, :transitions_to => 'submitted.awaiting_review'
+  end
+  state :submitted
+    event :reject, :transitions_to => 'rejected'
+    state :awaiting_review do
+      event :review, :transitions_to => 'submitted.reviewing'
+    end
+    state :reviewing do
+      event :accept, :transitions_to => 'active'
+      event :clarify, :transitions_to => 'submitted.clarifying'
+    end
+    state :clarifying do
+      event :review, :transitions_to => 'submitted.reviewing'
+    end
+  end
+  state :active
+  state :rejected
+
+  # Under the hood, the `state` macro creates a class with the same name as the state. Here we add to the definition of that class.
+  class Unsubmitted
+    # Defines a handler for the submit event. Events can have arguments
+    def submit(reason=nil)
+      # Do something, the post is available as either the `resource` or `post` property
+    end
+  end
+
+  class Submitted
+    class AwaitingReview
+      # Handles the review event. This will *not* handle the review event for the 'submitted.clarifying' state
+      def review
+      end
+    end
+
+    # Events on parent states are available to their children.
+    def reject
+    end
+  end
+end
+```
+
+## Under the Hood
+
+As suggested in the above example, states and events really just correspond to classes and methods of the state manager. In fact, the `state` macro is really just syntactic sugar around defining a `StateManager::State` subclass to the current state--the root state manager is also a state.
+
+On the resource, the `state_manager` macro makes an instance of the specified `StateManager::Base` subclass available through the "#{property}_manager" attribute on the resource. The above examples of helper methods is essentially syntactic sugar on the following:
+
+```ruby
+post = Post.new
+post.state_manager.in_state?('unsubmitted') # true, the post will initially be in the 'unsubmitted' state
+post.state_manager.respond_to_event?('submit') # true, the 'submit' event is defined on the current state
+post.state_manager.respond_to_event?('review')? # false, the 'review' event is not defined on the current state
+post.state_manager.send_event!('submit') # invokes the submit event
+post.state_manager.in_state?('submitted.awaiting_review')? # true, the post is in the 'submitted.awaiting_review' state
+post.state_manager.in_state?('submitted')? # true, the 'submitted' state is a parent of the current state
+```
+
+Furthermore, only leaf states are valid states for a resource. The state manager can also be explicitly transitioned to a state, however this should normally only be used inside an event handler:
+
+```ruby
+post.state_manager.transition_to('submitted.awaiting_review') # puts the post is in the 'submitted.awaiting_review' state
+post.state_manager.transition_to('submitted') # throws a StateManager::InvalidState error, 'submitted' is not a leaf state
+```
+
+By default, the initial state will be the first state that was defined. This can be customized by setting the initial state:
+
+```ruby
+class PostStates < StateManager::Base
+  initial_state :rejected
+  ...
+end
+```
+
+The current state can also be accessed from the state manager:
+
+```ruby
+post.state_manager.current_state.name # 'awaiting_review'
+post.state_manager.current_state.path # 'submitted.awaiting_review'
+```
+
+## Callbacks
+
+StateManager has several callbacks that can be hooked into:
+
+```ruby
+class PostStates < StateManager::Base
+  state :unsubmitted do
+    event :submit, :transitions_to => 'submitted.awaiting_review'
+  end
+  state :submitted
+
+    # Called when the 'submitted' state is being entered
+    def enter
+    end
+
+    # Called when the 'submitted' state is being exited.
+    def exit
+    end
+
+    # After it has been entered
+    def entered
+    end
+
+    # After it has been exited
+    def exited
+    end
+
+    event :reject, :transitions_to => 'rejected'
+    state :awaiting_review do
+      event :review, :transitions_to => 'submitted.reviewing'
+    end
+
+  ...
+
+  # Called before every transition
+  def will_transition(from, to, event)
+  end
+
+  # Called after ever transition
+  def did_transition(from, to, event)
+  end
+end
+```
+
+In the above example, transitioning between 'submitted.awaiting_review' and 'submitted.reviewing' will *not* trigger the the enter/exit callbacks for the 'submitted' state, however it will be called for the two sub-states.
+
+## Delayed Job Integration
+
+StateManager comes out of the box with support for [delayed_job](https://github.com/tobi/delayed_job). If delayed_job is available, events can be defined with a `:delay` property which indicates a delay after which the event should automatically be triggered:
+
+```ruby
+class UserStates < StateManager::Base
+  state :submitted do
+    event :activate, :transitions_to => :active, :delay => 2.days
+  end
+
+  state :active
+end
+```
+
+In this example, the `activate` event will be called by delayed_job automatically after 2 days unless it is called programatically before then.
+
+## Contributing to statemanager
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+## Copyright
+
+Copyright (c) 2012 Gordon Hempton. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,45 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "state_manager"
+  gem.homepage = "http://github.com/ghempton/statemanager"
+  gem.license = "MIT"
+  gem.summary = "%Q{Finite state machine implementation.}"
+  gem.description = %Q{Finite state machine implementation that keeps logic separate from model classes and supports sub-states.}
+  gem.email = "ghempton@gmail.com"
+  gem.authors = ["Gordon Hempton"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "statemanager #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.2.3

data/lib/state_manager/adapters/active_record.rb

@@ -0,0 +1,52 @@
+module StateManager
+  module Adapters
+    module ActiveRecord
+      include Base
+
+      def self.matching_ancestors
+        %w(ActiveRecord::Base)
+      end
+
+      module ResourceMethods
+
+        def self.included(base)
+          # Make sure that the model is in a valid state before it is saved
+          base.before_validation :_validate_states
+
+          base.extend(ClassMethods)
+        end
+
+        def _validate_states
+          self.validate_states!
+        end
+
+        module ClassMethods
+          def state_manager_added(property, klass, options)
+            class_eval do
+              klass.specification.states.keys.each do |state|
+                # The connection might not be ready when defining this code is
+                # reached so we wrap in a lamda.
+                scope state, lambda {
+                  conn = ::ActiveRecord::Base.connection
+                  column = conn.quote_column_name klass._state_property
+                  query = "#{column} = ? OR #{column} LIKE ?"
+                  like_term = "#{state.to_s}.%"
+                  where(query, state, like_term)
+                }
+              end
+            end 
+          end
+        end
+
+      end
+
+      module ManagerMethods
+
+        def write_state(value)
+          resource.send :update_attribute, self.class._state_property, value.path
+        end
+
+      end
+    end
+  end
+end

data/lib/state_manager/adapters/base.rb

@@ -0,0 +1,49 @@
+module StateManager
+  module Adapters
+    module Base
+
+      module ClassMethods
+        # The name of the adapter
+        def adapter_name
+          @adapter_name ||= begin
+            name = self.name.split('::').last
+            name.gsub!(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
+            name.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+            name.downcase!
+            name.to_sym
+          end
+        end
+        
+        # Whether this adapter is available for the current library.  This
+        # is only true if the ORM that the adapter is for is currently
+        # defined.
+        def available?
+          matching_ancestors.any? && Object.const_defined?(matching_ancestors[0].split('::')[0])
+        end
+        
+        # The list of ancestor names that cause this adapter to matched.
+        def matching_ancestors
+          []
+        end
+        
+        # Whether the adapter should be used for the given class.
+        def matches?(klass)
+          matches_ancestors?(klass.ancestors.map {|ancestor| ancestor.name})
+        end
+        
+        # Whether the adapter should be used for the given list of ancestors.
+        def matches_ancestors?(ancestors)
+          (ancestors & matching_ancestors).any?
+        end
+      end
+
+      def self.included(base)
+        return if base < StateManager::Base
+        base.class_eval { extend ClassMethods }
+      end
+
+      extend ClassMethods
+      
+    end
+  end
+end

data/lib/state_manager/adapters.rb

@@ -0,0 +1,30 @@
+# Load each available adapter
+require 'state_manager/adapters/base'
+Dir["#{File.dirname(__FILE__)}/adapters/*.rb"].sort.each do |path|
+  require "state_manager/adapters/#{File.basename(path)}"
+end
+
+module StateManager
+
+  class AdapterNotFound < StandardError; end;
+
+  module Adapters
+    def self.match(klass)
+      all.detect {|adapter| adapter.matches?(klass)}
+    end
+
+    def self.match_ancestors(ancestors)
+      all.detect {|adapter| adapter.matches_ancestors?(ancestors)}
+    end
+
+    def self.find_by_name(name)
+      all.detect {|adapter| adapter.integration_name == name} || raise(AdapterNotFound.new(name))
+    end
+    
+    def self.all
+      constants = self.constants.map {|c| c.to_s}.sort
+      constants.map {|c| const_get(c)}
+    end
+  end
+
+end