mattsnyder-stately 0.2.1

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/.ruby-gemset

@@ -0,0 +1 @@
+stately

data/.ruby-version

@@ -0,0 +1 @@
+ruby-1.8.7-p358

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.3
+  - 2.0.0
+branches:
+  only:
+    - master
+script:
+  - bundle exec rake spec

data/.yardopts

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

data/Gemfile

@@ -0,0 +1,5 @@
+source 'http://rubygems.org'
+
+gem 'rake'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,34 @@
+PATH
+  remote: .
+  specs:
+    stately (0.2.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    json (1.8.0)
+    rake (10.0.4)
+    rdoc (4.0.1)
+      json (~> 1.4)
+    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
+  rake
+  rdoc
+  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,178 @@
+# Stately
+
+[![Build Status](https://api.travis-ci.org/rtwomey/stately.png)](https://travis-ci.org/rtwomey/stately)
+
+A minimal, 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:
+
+```ruby
+class Order
+  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
+```
+
+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.
+
+## When to use stately
+
+Often, you'll find yourself writing an object that can have multiple states. Tracking these states can usually be done either:
+
+* By hand (i.e. adding a string column in the db and storing the current state there).
+* Via a state machine of some kind. [state_machine](https://github.com/pluginaweek/state_machine) is a popular one that I've used quite a bit, which has a lot of advanced features (most of which I've never used).
+
+Stately exists in a middle space between the two options. The goal of stately is to make the most common case, where you just need to track state and react appropriately when switching those states, easy.
+
+## Design goals
+
+* Minimalist. Stately tries to solve the most common use case: tracking the current state and handling transitions between states.
+
+* No magic. In other words, if you're using, say, ActiveRecord, stately won't hook in to activerecord callbacks. This requires you to be more explicit and perhaps more verbose, but I think it helps with readability and reduces surprises. See the Examples section below for what this looks like when in an ActiveRecord environment.
+
+* Syntax that is as self-documenting as possible. Someone not familiar with Stately should be able to understand what happens when an object's state is changed just by reading the DSL.
+
+## Getting started
+
+Either install locally:
+
+```shell
+gem install stately
+```
+
+or add it to your Gemfile:
+
+```ruby
+gem stately
+```
+
+Be sure to run `bundle install` afterwards.
+
+The first step is to add the following to your object:
+
+```ruby
+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:
+
+```ruby
+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`:
+
+```ruby
+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.
+
+```ruby
+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 some kind of persistence layer, sych as activerecord, you'll probably want an `after_transition` that calls `save` or the equivalent.
+
+```ruby
+class Order
+  stately :start => :processing do
+    # ...
+
+    state :completed do
+      before_transition :from => :processing, :do => :before_completed
+      before_transition :from => :invalid, :do => :cleanup_invalid
+      after_transition :do => :after_completed
+    end
+  end
+
+  private
+
+  def after_completed
+    save
+  end
+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.
+
+## Example: using Stately with ActiveRecord
+
+Let's say you are modeling a Bicycle object for your rental shop and you're using ActiveRecord. A Bicycle has two states: `available` and `rented`. Using stately, you could define this as the following:
+
+```ruby
+class Bicycle < ActiveRecord::Base
+  stately :start => :available do
+    state :rented, :action => :rent do
+      after_transition :do => :save
+    end
+  end
+end
+```
+
+When Bicycle is first instantiated, its `state` column is set to the string `available`. If you want to rent the Bicycle, you'd call `bicycle.rent`, which would update the `state` column to be the string `rented` and then call the ActiveRecord method `save`.
+
+As you can see, Stately is slightly more verbose than other state machine gems, but with the upside of being more self-documenting. Additionally, it doesn't hook into ActiveRecord's callback chains, and instead requires you to explicitely call `save`.
+
+## Requirements
+
+Stately requires Ruby 1.8.7 or newer. If you'd like to contribute to Stately, you'll need Rspec 2.0+.
+
+## License
+
+Stately is Copyright © 2013 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::Core
+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.2.1'
+end

data/lib/stately.rb

@@ -0,0 +1,196 @@
+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
+
+  module Core
+    # 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 stately_machine
+      @@stately_machine
+    end
+
+    # Set the current Stately::Machine object
+    def stately_machine=(obj)
+      @@stately_machine = obj
+    end
+  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