stately 0.1.0

data/.gitignore

@@ -0,0 +1,11 @@
+.bundle/
+log/*.log
+pkg/
+rdoc/
+.DS_Store
+.yardoc/
+doc/
+test/dummy/db/*.sqlite3
+test/dummy/log/*.log
+test/dummy/tmp/
+test/dummy/.sass-cache

data/.rspec

@@ -0,0 +1,2 @@
+--format progress
+--color

data/.yardopts

@@ -0,0 +1,4 @@
+lib/**/*.rb
+-
+README.md
+MIT-LICENSE

data/Gemfile

@@ -0,0 +1,3 @@
+source 'http://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,28 @@
+PATH
+  remote: .
+  specs:
+    stately (0.0.1)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    redcarpet (2.2.2)
+    rspec (2.11.0)
+      rspec-core (~> 2.11.0)
+      rspec-expectations (~> 2.11.0)
+      rspec-mocks (~> 2.11.0)
+    rspec-core (2.11.1)
+    rspec-expectations (2.11.3)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.11.3)
+    yard (0.8.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  redcarpet (~> 2.2.2)
+  rspec (~> 2.0)
+  stately!
+  yard (~> 0.8.3)

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 Ryan Twomey
+
+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,112 @@
+# Stately
+
+An elegant state machine for your ruby objects.
+
+![A stately fellow.](https://dl.dropbox.com/u/2754528/exquisite_cat.jpg "A stately fellow.")
+
+## Making a stately start
+
+Stately is a state machine for ruby objects, with an elegant, easy-to-read DSL. Here's an example showing off what Stately can do:
+
+    Class Order do
+      stately start: :processing do
+        state :completed do
+          prevent_from :refunded
+
+          before_transition from: :processing, do: :calculate_total
+          after_transition do: :email_receipt
+
+          validate :validates_credit_card
+        end
+
+        state :invalid do
+          prevent_from :completed, :refunded
+        end
+
+        state :refunded do
+          allow_from :completed
+
+          after_transition do: :email_receipt
+        end
+      end
+
+Stately tries hard not to surprise you. When you transition to a new state, you're responsible for taking whatever actions that means using `before_transition` and `after_transition`. Stately also has no dependencies on things like DataMapper or ActiveModel, so it will never surprise you with an implicit `save` after transitioning states.
+
+## Getting started
+
+Either install locally:
+
+    gem install stately
+
+or add it to your Gemfile:
+
+    gem stately
+
+Be sure to run `bundle install` afterwards.
+
+The first step is to add the following to your object:
+
+    stately start: :initial_state, attr: :my_state_attr do
+      # ...
+    end
+
+This sets up Stately to look for an attribute named `my_state_attr`, and initially set it to `initial_state`. If you omit `attr: :my_state_attr`, Stately will automatically look for an attribute named `state`.
+
+## Defining a state
+
+States make up the core of Stately and define two things: the name of the state (i.e. "completed"), and a verb as the name of the method to call to begin a transition into that state (i.e. "complete"). Stately has support for some common state/verb combinations, but you can always use your own:
+
+    Class Order
+      stately start: :processing do
+        state :my_state, action: transition_to_my_state
+      end
+    end
+
+    order = Order.new
+    order.transition_to_my_state
+
+## Transitions
+
+A "transition" is the process of moving from one state to another. You can define legal transitions using `allow_from` and `prevent_from`:
+
+    state :completed do
+      allow_from :processing
+      prevent_from :refunded
+    end
+
+In the above example, if you try to transition to `completed` (by calling `complete` on the object) from `refunded`, you'll see a `Stately::InvalidTransition` is raised. By default, all transitions are allowed.
+
+## Validations
+
+While transitioning from one state to another, you can define validations to be run. If any validation returns `false`, the transition is halted.
+
+    state :completed do
+      validate :validates_amount
+      validate :validates_credit_card
+    end
+
+Each validation is also called in order, so first `validates_amount` will be called, and if it doesn't return `false`, then `validates_credit_card` will be called and checked.
+
+## Callbacks
+
+Callbacks can be defined to run either before or after a transition occurs. A `before_transition` is run after validations are checked, but before the `state_attr` has been written to with the new state. An `after_transition` is called after the `state_attr` has been written to.
+
+If you're using Stately with a database, you'll almost always want an `after_transition` that calls `save` or the equivalent.
+
+    state :completed do
+      before_transition from: :processing, do: :before_completed
+      before_transition from: :invalid, do: :cleanup_invalid
+      after_transition do: :after_completed
+    end
+
+A callback can include an optional `from` state name, which is only called when transitioning from the named state. Omitting it means the callback is always called.
+
+Additionally, each callback is executed in the order in which it's defined.
+
+## Requirements
+
+Stately requires Ruby 1.9+. If you'd like to contribute to Stately, you'll need Rspec 2.0+.
+
+## License
+
+Stately is Copyright © 2012 Ryan Twomey. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.

data/Rakefile

@@ -0,0 +1,38 @@
+#!/usr/bin/env rake
+
+require 'bundler'
+require 'rspec/core/rake_task'
+
+Bundler::GemHelper.install_tasks
+
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Stately'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+namespace :spec do
+  desc 'Run unit specs'
+  RSpec::Core::RakeTask.new('unit') do |t|
+    t.pattern = 'spec/unit/**/*_spec.rb'
+  end
+
+  desc 'Run functional specs'
+  RSpec::Core::RakeTask.new('functional') do |t|
+    t.pattern = 'spec/functional/**/*_spec.rb'
+  end
+end
+
+desc 'Run unit and functional specs'
+task :spec => ['spec:unit', 'spec:functional']
+
+task :default => :spec

data/lib/stately/core_ext.rb

@@ -0,0 +1,5 @@
+# Includes Stately on Ruby's Object.
+
+Object.class_eval do
+  include Stately
+end

data/lib/stately/machine.rb

@@ -0,0 +1,26 @@
+module Stately
+  # A Stately::Machine is a container for Stately::States.
+  class Machine
+    attr_reader :start, :state_attr, :states
+
+    # Sets up a new instance of Stately::Machine
+    def initialize(attr_name, start)
+      @state_attr = attr_name
+      @start = start
+      @states = [State.new(@start)]
+    end
+
+    # Define a new Stately::State and add it to this Stately::Machine.
+    #
+    # @param [String] name The name of the state. This is also stored in the instance object's
+    #   state attribute.
+    # @param [Hash] opts Optionally, a method name can be defined as this state's action, if it
+    #   can't be inferred from the name.
+    def state(name, opts={}, &block)
+      @states.delete_if { |s| s.name == name }
+
+      action = opts ? opts[:action] : nil
+      @states << State.new(name, action, &block)
+    end
+  end
+end

data/lib/stately/state.rb

@@ -0,0 +1,96 @@
+module Stately
+  # A Stately::State object contains the configuration and other information about a defined
+  # state.
+  #
+  # It's made up of a name (which is saved to the parent instance's state attribute), the
+  # name of an action (which is a method called to transition into this state), and a DSL to
+  # define allowed transitions, callbacks, and validations.
+
+  class State
+    attr_reader :action, :name
+    attr_reader :allow_from_states, :prevent_from_states
+    attr_reader :after_transitions, :before_transitions, :validations
+
+    # Sets up and returns a new Stately::State object.
+    #
+    # @param [String] name The name of the state
+    # @param [String] action The method name that's called to transition to this state. Some method
+    #   names can be inferred based on the state's name.
+    def initialize(name, action=nil, &block)
+      @action = (action || guess_action_for(name)).to_s
+      @name = name
+
+      @allow_from_states = []
+      @prevent_from_states = []
+
+      @before_transitions = []
+      @after_transitions = []
+      @validations = []
+
+      if block_given?
+        configuration = StateConfigurator.new(&block)
+
+        @allow_from_states = configuration.allow_from_states || []
+        @prevent_from_states = configuration.prevent_from_states || []
+
+        @after_transitions = configuration.after_transitions || []
+        @before_transitions = configuration.before_transitions || []
+        @validations = configuration.validations || []
+      end
+    end
+
+    # @return [String] The state name as a string
+    def to_s
+      @name.to_s
+    end
+
+    # @return [Symbol] The state name as a string
+    def to_sym
+      @name.to_sym
+    end
+
+    private
+
+    ACTIONS = { completed: :complete, converting: :convert, invalid: :invalidate,
+      preparing: :prepare, processing: :process, refunded: :refund, reticulating: :reticulate,
+      saving: :save, searching: :search, started: :start, stopped: :stop }
+
+    def guess_action_for(name)
+      ACTIONS[name.to_sym]
+    end
+
+    class StateConfigurator
+      attr_reader :after_transitions, :before_transitions, :validations
+      attr_reader :allow_from_states, :prevent_from_states
+
+      def initialize(&block)
+        instance_eval(&block)
+      end
+
+      def allow_from(*states)
+        @allow_from_states ||= []
+        @allow_from_states |= states.map(&:to_sym)
+      end
+
+      def before_transition(options={})
+        @before_transitions ||= []
+        @before_transitions << options
+      end
+
+      def after_transition(options={})
+        @after_transitions ||= []
+        @after_transitions << options
+      end
+
+      def prevent_from(*states)
+        @prevent_from_states ||= []
+        @prevent_from_states |= states.map(&:to_sym)
+      end
+
+      def validate(options={})
+        @validations ||= []
+        @validations << options
+      end
+    end
+  end
+end

data/lib/stately/version.rb

@@ -0,0 +1,3 @@
+module Stately
+  VERSION = '0.1.0'
+end

data/lib/stately.rb

@@ -0,0 +1,204 @@
+require 'stately/machine'
+require 'stately/state'
+
+module Stately
+  # An InvalidTransition is an error that is raised when attempting to transition from a state
+  # that's not allowable, based on the Stately::State DSL definitions allow_from and prevent_from.
+  class InvalidTransition < StandardError
+  end
+
+  # Define a new Stately state machine.
+  #
+  # As an example, let's say you have an Order object and you'd like an elegant state machine for
+  # it. Here's one way you might set it up:
+  #
+  #     Class Order do
+  #       stately start: :processing do
+  #         state :completed do
+  #           prevent_from :refunded
+  #
+  #           before_transition from: :processing, do: :calculate_total
+  #           after_transition do: :email_receipt
+  #
+  #           validate :validates_credit_card
+  #         end
+  #
+  #         state :invalid do
+  #           prevent_from :completed, :refunded
+  #         end
+  #
+  #         state :refunded do
+  #           allow_from :completed
+  #
+  #           after_transition do: :email_receipt
+  #         end
+  #       end
+  #     end
+  #
+  # This example is doing quite a few things, paraphrased as:
+  #
+  #   * It sets up a new state machine using the default state attribute on Order to store the
+  #     current state. It also indicates the initial state should be :processing.
+  #   * It defines three states: :completed, :refunded, and :invalid
+  #   * Order can transition to the completed state from all but the refunded state. Similar
+  #     definitions are setup for the other two states.
+  #   * Callbacks are setup using before_transition and after_transition
+  #   * Validations are added. If a validation fails, it prevents the transition.
+  #
+  # Stately tries hard not to surprise you. In a typical Stately implementation, you'll always have
+  # an after_transition, primarily to call save (or whatever the equivalent is to store the
+  # instance's current state).
+  def stately(*opts, &block)
+    options = opts.last.is_a?(Hash) ? opts.last : {}
+    options[:attr] ||= :state
+
+    self.stately_machine = Stately::Machine.new(options[:attr], options[:start])
+    self.stately_machine.instance_eval(&block) if block_given?
+
+    include Stately::InstanceMethods
+  end
+
+  # Get the current Stately::Machine object
+  def self.stately_machine
+    @@stately_machine
+  end
+
+  # Get the current Stately::Machine object
+  def stately_machine
+    @@stately_machine
+  end
+
+  # Set the current Stately::Machine object
+  def self.stately_machine=(obj)
+    @@stately_machine = obj
+  end
+
+  # Set the current Stately::Machine object
+  def stately_machine=(obj)
+    @@stately_machine = obj
+  end
+
+  module InstanceMethods
+    # Sets up an object with Stately. The DSL is parsed and the Stately::Machine is initialized.
+    #
+    # When an object is first initialized, Stately automatically sets the state attribute to the
+    # start state.
+    #
+    # Additionally, a method is defined for each of the state's actions. These methods are used to
+    # transition between states. If you have a state named 'completed', Stately will infer the
+    # action to be 'complete' and define a method named 'complete'. You can then call 'complete' on
+    # the object to transition into the completed state.
+
+    def InstanceMethods.included(klass)
+      klass.class_eval do
+        alias_method :init_instance, :initialize
+        def initialize(*args)
+          init_instance(*args)
+          initialize_stately
+        end
+
+        stately_machine.states.each do |state|
+          define_method(state.action) do
+            transition_to(state)
+          end
+        end
+      end
+    end
+
+    # @return [Array<String>] a list of state names.
+    def states
+      stately_machine.states.map(&:name)
+    end
+
+    private
+
+    def allowed_state_transition?(to_state)
+      if current_state == to_state.to_s
+        raise InvalidTransition,
+          "Prevented transition from #{current_state} to #{state.to_s}."
+      end
+
+      allowed_from_states(to_state).include?(current_state.to_sym)
+    end
+
+    def allowed_from_states(state)
+      if state.allow_from_states.empty?
+        stately_machine.states.map(&:to_sym) - state.prevent_from_states
+      else
+        state.allow_from_states
+      end
+    end
+
+    def current_state
+      (self.send(stately_machine.state_attr) || stately_machine.start).to_s
+    end
+
+    def eligible_callback?(callback)
+      if (callback.has_key?(:from) && callback[:from].to_s == current_state) ||
+        (!callback.has_key?(:from))
+        true
+      else
+        false
+      end
+    end
+
+    def initialize_stately
+      set_initial_state
+    end
+
+    def run_before_transition_callbacks(state)
+      state.before_transitions.each do |callback|
+        if eligible_callback?(callback)
+          self.send callback[:do]
+        end
+      end
+    end
+
+    def run_after_transition_callbacks(state)
+      state.after_transitions.each do |callback|
+        self.send callback[:do]
+      end
+    end
+
+    def state_named(state_name)
+      stately_machine.states.find { |s| s.to_s == state_name.to_s }
+    end
+
+    def transition_to(state_name)
+      state = state_named(state_name)
+
+      if valid_transition_to?(state)
+        run_before_transition_callbacks(state)
+        write_attribute(stately_machine.state_attr, state.to_s)
+        run_after_transition_callbacks(state)
+      end
+    end
+
+    def set_initial_state
+      write_attribute(stately_machine.state_attr, stately_machine.start.to_s)
+    end
+
+    def write_attribute(attr, val)
+      send("#{attr}=", val)
+    end
+
+    def valid_transition_to?(state)
+      if allowed_state_transition?(state)
+        if state.validations.nil? || state.validations.empty?
+          true
+        else
+          results = state.validations.collect do |validation|
+            self.send validation
+          end
+
+          results.detect { |r| r == false }.nil?
+        end
+      else
+        raise InvalidTransition,
+          "Prevented transition from #{current_state} to #{state.to_s}."
+      end
+    end
+  end
+end
+
+require 'stately/core_ext'

data/lib/tasks/stately_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :stately do
+#   # Task goes here
+# end

data/spec/functional/stately_spec.rb

@@ -0,0 +1,305 @@
+require 'ostruct'
+require 'spec_helper'
+
+describe Stately do
+  before do
+    @order_class = Class.new(OpenStruct) do
+      stately start: :processing do
+        state :completed do
+          prevent_from :refunded
+
+          before_transition from: :processing, do: :before_completed
+          before_transition from: :invalid, do: :cleanup_invalid
+          after_transition do: :after_completed
+
+          validate :validates_amount
+          validate :validates_credit_card
+        end
+
+        state :invalid do
+          prevent_from :completed, :refunded
+        end
+
+        state :processing do
+          prevent_from :completed, :invalid, :refunded
+        end
+
+        state :refunded do
+          allow_from :completed
+
+          before_transition from: :completed, do: :before_refunded
+          after_transition from: :completed, do: :after_refunded
+        end
+      end
+
+      private
+
+      def before_completed
+        self.serial_number = Time.now.usec
+      end
+
+      def after_completed
+      end
+
+      def before_refunded
+        self.refunded_reason = 'Overcharged'
+      end
+
+      def after_refunded
+      end
+
+      def cleanup_invalid
+        self.serial_number = nil
+      end
+
+      def validates_amount
+        amount > 0.0 && amount < 100.0
+      end
+
+      def validates_credit_card
+        self.cc_number == 123
+      end
+    end
+  end
+
+  def self.should_call_callbacks_on_complete(order)
+    @order = order
+
+    describe 'callbacks' do
+      it 'calls callbacks in order' do
+        @order.should_receive(:before_completed).ordered
+        @order.should_receive(:after_completed).ordered
+        @order.should_not_receive :cleanup_invalid
+
+        @order.complete
+      end
+
+      it 'sets serial_number' do
+        @order.serial_number.should be_nil
+        @order.complete
+        @order.serial_number.should_not be_nil
+      end
+    end
+  end
+
+  def self.should_call_validations_on_complete(order)
+    @order = order
+
+    describe 'validations' do
+      it 'calls validations in order' do
+        @order.should_receive(:validates_amount).ordered
+        @order.should_receive(:validates_credit_card).ordered
+
+        @order.complete
+      end
+
+      describe 'return values' do
+        before do
+          @order.stub :validates_amount => false
+        end
+
+        it 'should halt on false' do
+          @order.should_receive :validates_amount
+          @order.should_receive :validates_credit_card
+          @order.should_not_receive :before_completed
+          @order.should_not_receive :after_completed
+          @order.should_not_receive :cleanup_invalid
+
+          current_state = @order.state
+          @order.complete
+          @order.state.should == current_state
+        end
+      end
+    end
+  end
+
+  def self.should_prevent_transition(from, to, action)
+    before do
+      @order = @order_class.new(amount: 99, cc_number: 123)
+      @order.state = from
+    end
+
+    it 'should be prevented' do
+      lambda { @order.send(action) }.should raise_error(Stately::InvalidTransition,
+        "Prevented transition from #{from} to #{to}.")
+    end
+  end
+
+  def self.should_set_state(new_state, order, action)
+    @order = order
+
+    describe 'on success' do
+      before do
+        @order.send action
+      end
+
+      it 'sets state' do
+        @order.state.should == new_state
+      end
+    end
+  end
+
+  describe 'initial state' do
+    before do
+      @order = @order_class.new(amount: 99, cc_number: 123)
+    end
+
+    it 'creates actions for each state' do
+      @order_class.method_defined?(:complete).should be_true
+      @order_class.method_defined?(:process).should be_true
+      @order_class.method_defined?(:refund).should be_true
+    end
+
+    it 'finds all states' do
+      @order.states.should == [:completed, :invalid, :processing, :refunded]
+    end
+
+    it 'sets initial state to processing' do
+      @order.state.should == 'processing'
+    end
+  end
+
+  describe '#process' do
+    describe 'from processing' do
+      should_prevent_transition('processing', 'processing', :process)
+    end
+
+    describe 'from completed' do
+      should_prevent_transition('completed', 'processing', :process)
+    end
+
+    describe 'from invalid' do
+      should_prevent_transition('invalid', 'processing', :process)
+    end
+
+    describe 'from refunded' do
+      should_prevent_transition('refunded', 'processing', :process)
+    end
+  end
+
+  describe '#complete' do
+    before do
+      @order = @order_class.new(amount: 99, cc_number: 123)
+    end
+
+    describe 'from processing' do
+      should_call_validations_on_complete(@order)
+
+      describe 'callbacks' do
+        it 'calls callbacks in order' do
+          @order.should_receive(:before_completed).ordered
+          @order.should_receive(:after_completed).ordered
+          @order.should_not_receive :cleanup_invalid
+
+          @order.complete
+        end
+
+        it 'sets serial_number' do
+          @order.serial_number.should be_nil
+          @order.complete
+          @order.serial_number.should_not be_nil
+        end
+      end
+
+      should_set_state('completed', @order, :complete)
+    end
+
+    describe 'from completed' do
+      should_prevent_transition('completed', 'completed', :complete)
+    end
+
+    describe 'from invalid' do
+      before do
+        @order.serial_number = Time.now.usec
+        @order.state = 'invalid'
+      end
+
+      should_call_validations_on_complete(@order)
+
+      describe 'callbacks' do
+        it 'calls callbacks in order' do
+          @order.should_receive(:cleanup_invalid).ordered
+          @order.should_receive(:after_completed).ordered
+          @order.should_not_receive :before_completed
+
+          @order.complete
+        end
+
+        it 'sets serial_number to nil' do
+          @order.serial_number.should_not be_nil
+          @order.complete
+          @order.serial_number.should be_nil
+        end
+      end
+
+      should_set_state('completed', @order, :complete)
+    end
+
+    describe 'from refunded' do
+      should_prevent_transition('refunded', 'completed', :complete)
+    end
+  end
+
+  describe '#invalidate' do
+    describe 'from processing' do
+      before do
+        @order = @order_class.new(amount: 99, cc_number: 123)
+        @order.invalidate
+      end
+
+      it 'sets state' do
+        @order.state.should == 'invalid'
+      end
+    end
+
+    describe 'from completed' do
+      should_prevent_transition('completed', 'invalid', :invalidate)
+    end
+
+    describe 'from invalid' do
+      should_prevent_transition('invalid', 'invalid', :invalidate)
+    end
+
+    describe 'from refunded' do
+      should_prevent_transition('refunded', 'invalid', :invalidate)
+    end
+  end
+
+  describe '#refund' do
+    describe 'from processing' do
+      should_prevent_transition('processing', 'refunded', :refund)
+    end
+
+    describe 'from completed' do
+      before do
+        @order = @order_class.new(amount: 99, cc_number: 123)
+        @order.state = 'completed'
+      end
+
+      describe 'callbacks' do
+        it 'calls callbacks in order' do
+          @order.should_receive(:before_refunded).ordered
+          @order.should_receive(:after_refunded).ordered
+
+          @order.refund
+        end
+
+        it 'sets refunded_reason' do
+          @order.refunded_reason.should be_nil
+          @order.refund
+          @order.refunded_reason.should_not be_nil
+        end
+      end
+
+      should_set_state('refunded', @order, :refund)
+    end
+
+    describe 'from invalid' do
+      should_prevent_transition('invalid', 'refunded', :refund)
+    end
+
+    describe 'from refunded' do
+      should_prevent_transition('refunded', 'refunded', :refund)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'lib')
+$LOAD_PATH << File.join(File.dirname(__FILE__))
+
+require 'rspec'
+require 'stately'

data/spec/unit/stately/machine_spec.rb

@@ -0,0 +1,119 @@
+require 'spec_helper'
+
+describe Stately::Machine do
+  before do
+    @machine = Stately::Machine.new(:state, :processing)
+  end
+
+  describe 'initialize' do
+    it 'sets initial vars' do
+      @machine.start.should == :processing
+      @machine.state_attr.should == :state
+      @machine.states.map(&:to_s).should == ['processing']
+    end
+
+    it 'guesses the initial action' do
+      @machine.states.first.action.should == 'process'
+    end
+  end
+
+  describe '#state' do
+    describe 'with name only' do
+      describe 'of a new state' do
+        before do
+          @machine.state(:completed)
+        end
+
+        it 'adds a new state' do
+          @machine.states.map(&:to_s).should == ['processing', 'completed']
+        end
+      end
+
+      describe 'of a previously defined state' do
+        before do
+          @machine.state(:processing)
+        end
+
+        it "doesn't add a new state" do
+          @machine.states.map(&:to_s).should == ['processing']
+        end
+      end
+    end
+
+    describe 'with name and action' do
+      describe 'of a new state' do
+        before do
+          @machine.state(:new_state, action: :transition_to_new_state)
+        end
+
+        it 'adds a new state' do
+          @machine.states.map(&:to_s).should == ['processing', 'new_state']
+        end
+
+        it 'adds the correct action to the new state' do
+          @machine.states.last.action.should == 'transition_to_new_state'
+        end
+      end
+
+      describe 'of a previously defined state' do
+        before do
+          @machine.state(:processing, action: :transition_to_processing)
+        end
+
+        it "doesn't add a new state" do
+          @machine.states.map(&:to_s).should == ['processing']
+        end
+
+        it 'adds the correct action to the existing state' do
+          @machine.states.first.action.should == 'transition_to_processing'
+        end
+      end
+    end
+
+    describe 'with name, action, and block' do
+      describe 'of a new state' do
+        before do
+          @machine.state(:new_state, action: :transition_to_new_state) do
+            allow_from :completed
+          end
+
+          @new_state = @machine.states.last
+        end
+
+        it 'adds a new state' do
+          @machine.states.map(&:to_s).should == ['processing', 'new_state']
+        end
+
+        it 'adds the correct action to the new state' do
+          @new_state.action.should == 'transition_to_new_state'
+        end
+
+        it 'includes the allow_from param' do
+          @new_state.allow_from_states.should == [:completed]
+        end
+      end
+
+      describe 'of a previously defined state' do
+        before do
+          @machine.state(:processing, action: :transition_to_processing) do
+            allow_from :completed
+          end
+
+          @new_state = @machine.states.last
+        end
+
+        it "doesn't add a new state" do
+          @machine.states.map(&:to_s).should == ['processing']
+        end
+
+        it 'adds the correct action to the new state' do
+          @new_state.action.should == 'transition_to_processing'
+        end
+
+        it 'includes the allow_from param' do
+          @new_state.allow_from_states.should == [:completed]
+        end
+      end
+    end
+  end
+end

data/spec/unit/stately/state_spec.rb

@@ -0,0 +1,101 @@
+require 'spec_helper'
+
+describe Stately::State do
+  describe 'initialize' do
+    describe 'with a block given' do
+      describe 'new' do
+        before do
+          @state = Stately::State.new(:invalid, nil) do
+            allow_from :completed
+            prevent_from :completed, :refunded
+
+            before_transition do: :prepare
+            before_transition from: :processing, do: :before_completed
+            after_transition do: :cleanup
+            after_transition from: :processing, do: :after_processing
+
+            validate :validates_amount
+            validate :validates_credit_card
+          end
+        end
+
+        it 'should set initial values' do
+          @state.name.should == :invalid
+
+          @state.allow_from_states.should == [:completed]
+          @state.prevent_from_states.should == [:completed, :refunded]
+
+          @state.before_transitions.should == [{do: :prepare}, {from: :processing,
+            do: :before_completed}]
+          @state.after_transitions.should == [{do: :cleanup}, {from: :processing,
+            do: :after_processing}]
+          @state.validations.should == [:validates_amount, :validates_credit_card]
+        end
+      end
+    end
+
+    describe 'without a block given' do
+      describe 'new' do
+        before do
+          @state = Stately::State.new(:test_state)
+        end
+
+        it 'should set initial values' do
+          @state.name.should == :test_state
+
+          @state.allow_from_states.should == []
+          @state.prevent_from_states.should == []
+
+          @state.before_transitions.should == []
+          @state.after_transitions.should == []
+          @state.validations.should == []
+        end
+      end
+
+      describe 'with a given action' do
+        before do
+          @state = Stately::State.new(:test_state, :test_action)
+        end
+
+        it 'should set the given action name' do
+          @state.action.should == 'test_action'
+        end
+      end
+
+      describe 'without a given action' do
+        before do
+          @actions = { completed: :complete, converting: :convert, invalid: :invalidate,
+            preparing: :prepare, processing: :process, refunded: :refund, reticulating: :reticulate,
+            saving: :save, searching: :search, started: :start, stopped: :stop }
+        end
+
+        it 'should set the correct action verb' do
+          @actions.map do |state_name, action_name|
+            state = Stately::State.new(state_name)
+            state.action.should == action_name.to_s
+          end
+        end
+      end
+    end
+  end
+
+  describe '#to_s' do
+    before do
+      @state = Stately::State.new(:test_state)
+    end
+
+    it 'should return a string' do
+      @state.to_s.should == 'test_state'
+    end
+  end
+
+  describe '#to_sym' do
+    before do
+      @state = Stately::State.new('test_state')
+    end
+
+    it 'should return a symbol' do
+      @state.to_sym.should == :test_state
+    end
+  end
+end

data/spec/unit/stately_spec.rb

@@ -0,0 +1,58 @@
+require 'ostruct'
+require 'spec_helper'
+
+describe Stately::InstanceMethods do
+  before do
+    @test_class = Class.new(Object) do
+      attr_accessor :state
+
+      stately start: :processing do
+        state :completed
+      end
+    end
+
+    @object = @test_class.new
+  end
+
+  describe 'initialize' do
+    it 'creates a new Stately::Machine' do
+      @object.stately_machine.class.should == Stately::Machine
+      @object.stately_machine.should == @test_class.stately_machine
+    end
+
+    it 'sets initial state' do
+      @object.state.should == 'processing'
+    end
+  end
+
+  describe '#states' do
+    it 'returns known state names in order' do
+      @object.states.should == [:processing, :completed]
+    end
+  end
+
+  describe 'actions' do
+    it 'defines action methods' do
+      @test_class.method_defined?(:complete).should be_true
+      @test_class.method_defined?(:process).should be_true
+    end
+  end
+
+  describe 'stately_machine' do
+    it 'defines a class-level accessor called stately_machine' do
+      @test_class.respond_to?(:stately_machine).should be_true
+    end
+
+    it 'defines an instance-level accessor called stately_machine' do
+      @test_class.method_defined?(:stately_machine).should be_true
+    end
+
+    it 'defines a class-level setter called stately_machine=' do
+      @test_class.respond_to?(:stately_machine=).should be_true
+    end
+
+    it 'defines an instance-level setter called stately_machine=' do
+      @test_class.method_defined?(:stately_machine=).should be_true
+    end
+  end
+end

data/stately.gemspec

@@ -0,0 +1,22 @@
+$LOAD_PATH << File.expand_path('../lib', __FILE__)
+require 'stately/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'stately'
+  s.version     = Stately::VERSION
+  s.authors     = ['Ryan Twomey']
+  s.email       = ['rtwomey@gmail.com']
+  s.homepage    = 'http://github.com/rtwomey/stately'
+  s.summary     = 'A simple, elegant state machine for Ruby'
+  s.description = 'Add an elegant state machine to your ruby objects with a simple DSL'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {spec}/*`.split("\n")
+
+  s.add_development_dependency 'redcarpet', '~> 2.2.2'
+  s.add_development_dependency 'rspec', '~> 2.0'
+  s.add_development_dependency 'yard', '~> 0.8.3'
+
+  s.required_ruby_version = Gem::Requirement.new('>= 1.9.2')
+  s.require_paths = ['lib']
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: stately
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Ryan Twomey
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-11-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.2.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.2.2
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.3
+description: Add an elegant state machine to your ruby objects with a simple DSL
+email:
+- rtwomey@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .yardopts
+- Gemfile
+- Gemfile.lock
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/stately.rb
+- lib/stately/core_ext.rb
+- lib/stately/machine.rb
+- lib/stately/state.rb
+- lib/stately/version.rb
+- lib/tasks/stately_tasks.rake
+- spec/functional/stately_spec.rb
+- spec/spec_helper.rb
+- spec/unit/stately/machine_spec.rb
+- spec/unit/stately/state_spec.rb
+- spec/unit/stately_spec.rb
+- stately.gemspec
+homepage: http://github.com/rtwomey/stately
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: A simple, elegant state machine for Ruby
+test_files: []
+has_rdoc: