state_machine 0.3.1 → 0.4.0

data/CHANGELOG.rdoc

@@ -1,5 +1,31 @@
 == master
 
+== 0.4.0 / 2008-12-14
+
+* Remove the PluginAWeek namespace
+* Add generic attribute predicate (e.g. "#{attribute}?(state_name)") and state predicates (e.g. "#{state}?")
+* Add Sequel support
+* Fix aliasing :initialize on ActiveRecord models causing warnings when the environment is reloaded
+* Fix ActiveRecord state machines trying to query the database on unmigrated models
+* Fix initial states not getting set when the current value is an empty string [Aaron Gibralter]
+* Add rake tasks for generating graphviz files for state machines [Nate Murray]
+* Fix initial state not being included in list of known states
+* Add other_states directive for defining additional states not referenced in transitions or callbacks [Pete Forde]
+* Add next_#{event}_transition for getting the next transition that would be performed if the event were invoked
+* Add the ability to override the pluralized name of an attribute for creating scopes
+* Add the ability to halt callback chains by: throw :halt
+* Add support for dynamic to states in transitions (e.g. :to => lambda {Time.now})
+* Add support for using real blocks in before_transition/after_transition calls instead of using the :do option
+* Add DataMapper support
+* Include states referenced in transition callbacks in the list of a machine's known states
+* Only generate the known states for a machine on demand, rather than calculating beforehand
+* Add the ability to skip state change actions during a transition (e.g. vehicle.ignite(false))
+* Add the ability for the state change action (e.g. +save+ for ActiveRecord) to be configurable
+* Allow state machines to be defined on *any* Ruby class, not just ActiveRecord (removes all external dependencies)
+* Refactor transitions, guards, and callbacks for better organization/design
+* Use a class containing the transition context in callbacks, rather than an ordered list of each individual attribute
+* Add without_#{attribute} named scopes (opposite of the existing with_#{attribute} named scopes) [Sean O'Brien]
+
 == 0.3.1 / 2008-10-26
 
 * Fix the initial state not getting set when the state attribute is mass-assigned but protected

data/README.rdoc

@@ -1,7 +1,7 @@
 == state_machine
 
-+state_machine+ adds support for creating state machines for attributes within
-a model.
++state_machine+ adds support for creating state machines for attributes on any
+Ruby class.
 
 == Resources
 
@@ -23,16 +23,29 @@ Source
 
 == Description
 
-State machines make it dead-simple to manage the behavior of a model.  Too often,
-the status of a record is kept by creating multiple boolean columns in the table
-and deciding how to behave based on the values in those columns.  This can become
-cumbersome and difficult to maintain when the complexity of your models starts to
-increase.
+State machines make it dead-simple to manage the behavior of a class.  Too often,
+the status of an object is kept by creating multiple boolean attributes and
+deciding how to behave based on the values.  This can become cumbersome and
+difficult to maintain when the complexity of your class starts to increase.
 
 +state_machine+ simplifies this design by introducing the various parts of a real
-state machine, including states, events, and transitions.  However, the api is
-designed to be similar to ActiveRecord in terms of validations and callbacks,
-making it so simple you don't even need to know what a state machine is :)
+state machine, including states, events, transitions, and callbacks.  However,
+the api is designed to be so simple you don't even need to know what a
+state machine is :)
+
+Some brief, high-level features include:
+* Defining state machines on any Ruby class
+* Multiple state machines on a single class
+* before/after transition hooks with explicit transition requirements
+* ActiveRecord integration
+* DataMapper integration
+* Sequel integration
+* States of any data type
+* State predicates
+* GraphViz visualization creator
+
+Examples of the usage patterns for some of the above features are shown below.
+You can find more detailed documentation in the actual API.
 
 == Usage
 
@@ -43,12 +56,16 @@ Below is an example of many of the features offered by this plugin, including
 * Transition callbacks
 * Conditional transitions
 
-  class Vehicle < ActiveRecord::Base
+  class Vehicle
+    attr_accessor :seatbelt_on
+    
     state_machine :state, :initial => 'parked' do
       before_transition :from => %w(parked idling), :do => :put_on_seatbelt
-      after_transition :to => 'parked', :do => lambda {|vehicle| vehicle.update_attribute(:seatbelt_on, false)}
-      after_transition :on => 'crash', :do => :tow!
-      after_transition :on => 'repair', :do => :fix!
+      after_transition :on => 'crash', :do => :tow
+      after_transition :on => 'repair', :do => :fix
+      after_transition :to => 'parked' do |vehicle, transition|
+        vehicle.seatbelt_on = false
+      end
       
       event :park do
         transition :to => 'parked', :from => %w(idling first_gear)
@@ -83,44 +100,112 @@ Below is an example of many of the features offered by this plugin, including
       end
     end
     
-    def tow!
-      # do something here
+    def initialize
+      @seatbelt_on = false
     end
     
-    def fix!
-      # do something here
+    def put_on_seatbelt
+      @seatbelt_on = true
     end
     
     def auto_shop_busy?
       false
     end
+    
+    def tow
+      # tow the vehicle
+    end
+    
+    def fix
+      # get the vehicle fixed by a mechanic
+    end
   end
 
-Using the above model as an example, you can interact with the state machine
+Using the above class as an example, you can interact with the state machine
 like so:
 
-  vehicle = Vehicle.create  # => #<Vehicle id: 1, seatbelt_on: false, state: "parked">
-  vehicle.ignite            # => true
-  vehicle                   # => #<Vehicle id: 1, seatbelt_on: true, state: "idling">
-  vehicle.shift_up          # => true
-  vehicle                   # => #<Vehicle id: 1, seatbelt_on: true, state: "first_gear">
-  vehicle.shift_up          # => true
-  vehicle                   # => #<Vehicle id: 1, seatbelt_on: true, state: "second_gear">
+  vehicle = Vehicle.new           # => #<Vehicle:0xb7cf4eac @state="parked", @seatbelt_on=false>
+  vehicle.parked?                 # => true
+  vehicle.can_ignite?             # => true
+  vehicle.next_ignite_transition  # => #<StateMachine::Transition:0xb7c34cec ...>
+  vehicle.ignite                  # => true
+  vehicle.parked?                 # => false
+  vehicle.idling?                 # => true
+  vehicle                         # => #<Vehicle:0xb7cf4eac @state="idling", @seatbelt_on=true>
+  vehicle.shift_up                # => true
+  vehicle                         # => #<Vehicle:0xb7cf4eac @state="first_gear", @seatbelt_on=true>
+  vehicle.shift_up                # => true
+  vehicle                         # => #<Vehicle:0xb7cf4eac @state="second_gear", @seatbelt_on=true>
   
   # The bang (!) operator can raise exceptions if the event fails
-  vehicle.park!             # => PluginAWeek::StateMachine::InvalidTransition: Cannot transition via :park from "second_gear"
+  vehicle.park!                   # => StateMachine::InvalidTransition: Cannot transition via :park from "second_gear"
+  
+  # Generic state predicates can raise exceptions if the value does not exist
+  vehicle.state?('parked')        # => true
+  vehicle.state?('invalid')       # => ArgumentError: "parked" is not a known state value
+
+== Integrations
+
+In addition to being able to define state machines on all Ruby classes, a set of
+out-of-the-box integrations are available for some of the more popular Ruby
+libraries.  These integrations add library-specific behavior, allowing for state
+machines to work more tightly with the conventions defined by those libraries.
+
+The integrations currently available include:
+* ActiveRecord models
+* DataMapper resources
+* Sequel models
+
+A brief overview of these integrations is described below.
+
+=== ActiveRecord
+
+The ActiveRecord integration adds support for database transactions, automatically
+saving the record, named scopes, and observers.  For example,
+
+  class Vehicle < ActiveRecord::Base
+    state_machine :initial => 'parked' do
+      before_transition :to => 'idling', :do => :put_on_seatbelt
+      after_transition :to => 'parked' do |vehicle, transition|
+        vehicle.seatbelt = 'off'
+      end
+      
+      event :ignite do
+        transition :to => 'idling', :from => 'parked'
+      end
+    end
+    
+    def put_on_seatbelt
+      ...
+    end
+  end
+  
+  class VehicleObserver < ActiveRecord::Observer
+    # Callback for :ignite event *before* the transition is performed
+    def before_ignite(vehicle, transition)
+      # log message
+    end
+    
+    # Generic transition callback *before* the transition is performed
+    def after_transition(vehicle, transition)
+      Audit.log(vehicle, transition)
+    end
+  end
 
-=== With enumerations
+For more information about the various behaviors added for ActiveRecord state
+machines, see StateMachine::Integrations::ActiveRecord.
+
+==== With enumerations
 
 Using the acts_as_enumeration[http://github.com/pluginaweek/acts_as_enumeration] plugin
-states can be transparently stored using record ids in the database like so:
+with an ActiveRecord integration, states can be transparently stored using
+record ids in the database like so:
 
   class VehicleState < ActiveRecord::Base
     acts_as_enumeration
     
     create :id => 1, :name => 'parked'
     create :id => 2, :name => 'idling'
-    create :id => 3, :name => 'first_gear'
     ...
   end
   
@@ -133,31 +218,151 @@ states can be transparently stored using record ids in the database like so:
       event :park do
         transition :to => 'parked', :from => %w(idling first_gear)
       end
-      
-      event :ignite do
-        transition :to => 'stalled', :from => 'stalled'
-        transition :to => 'idling', :from => 'parked'
-      end
     end
     
     ...
   end
 
-Notice in the above example, the state machine definition remains *exactly* the
-same.  However, when interacting with the records, the actual state will be
-stored using the identifiers defined for the enumeration:
+Notice that the state machine definition remains *exactly* the same.  However,
+when interacting with the records, the actual state will be stored using the
+identifiers defined for the enumeration:
 
   vehicle = Vehicle.create  # => #<Vehicle id: 1, seatbelt_on: false, state_id: 1>
   vehicle.ignite            # => true
   vehicle                   # => #<Vehicle id: 1, seatbelt_on: true, state_id: 2>
-  vehicle.shift_up          # => true
-  vehicle                   # => #<Vehicle id: 1, seatbelt_on: true, state_id: 3>
 
 This allows states to take on more complex functionality other than just being
 a string value.
 
+=== DataMapper
+
+Like the ActiveRecord integration, the DataMapper integration adds support for
+database transactions, automatically saving the record, named scopes, Extlib-like
+callbacks, and observers.  For example,
+
+  class Vehicle
+    include DataMapper::Resource
+    
+    property :id, Serial
+    property :state, String
+    
+    state_machine :initial => 'parked' do
+      before_transition :to => 'idling', :do => :put_on_seatbelt
+      after_transition :to => 'parked' do |transition|
+        self.seatbelt = 'off' # self is the record
+      end
+      
+      event :ignite do
+        transition :to => 'idling', :from => 'parked'
+      end
+    end
+    
+    def put_on_seatbelt
+      ...
+    end
+  end
+  
+  class VehicleObserver
+    include DataMapper::Observer
+    
+    observe Vehicle
+    
+    # Callback for :ignite event *before* the transition is performed
+    before_transition :on => :ignite do |transition|
+      # log message (self is the record)
+    end
+    
+    # Generic transition callback *before* the transition is performed
+    after_transition do |transition, saved|
+      Audit.log(self, transition) if saved # self is the record
+    end
+  end
+
+For more information about the various behaviors added for DataMapper state
+machines, see StateMachine::Integrations::DataMapper.
+
+=== Sequel
+
+Like the ActiveRecord integration, the Sequel integration adds support for
+database transactions, automatically saving the record, named scopes, and
+callbacks.  For example,
+
+  class Vehicle < Sequel::Model
+    state_machine :initial => 'parked' do
+      before_transition :to => 'idling', :do => :put_on_seatbelt
+      after_transition :to => 'parked' do |transition|
+        self.seatbelt = 'off' # self is the record
+      end
+      
+      event :ignite do
+        transition :to => 'idling', :from => 'parked'
+      end
+    end
+    
+    def put_on_seatbelt
+      ...
+    end
+  end
+
+For more information about the various behaviors added for Sequel state
+machines, see StateMachine::Integrations::Sequel.
+
 == Tools
 
+=== Generating graphs
+
+This library comes with built-in support for generating di-graphs based on the
+events, states, and transitions defined for a state machine using GraphViz[http://www.graphviz.org].
+This requires that both the <tt>ruby-graphviz</tt> gem and graphviz library be
+installed on the system.
+
+==== Examples
+
+To generate a graph for a specific file / class:
+
+  rake state_machine:draw FILE=vehicle.rb CLASS=Vehicle
+
+To save files to a specific path:
+
+  rake state_machine:draw FILE=vehicle.rb CLASS=Vehicle TARGET=files
+
+To customize the image format:
+
+  rake state_machine:draw FILE=vehicle.rb CLASS=Vehicle FORMAT=jpg
+
+To generate multiple state machine graphs:
+
+  rake state_machine:draw FILE=vehicle.rb,car.rb CLASS=Vehicle,Car
+
+*Note* that this will generate a different file for every state machine defined
+in the class.  The generates files will an output filename of the format #{class_name}_#{attribute}.#{format}.
+
+For examples of actual images generated using this task, see those under the
+test/examples folder.
+
+==== Ruby on Rails Integration
+
+There is a special integration Rake task for generating state machines for
+classes used in a Ruby on Rails application.  This task will load the application
+environment, meaning that it's unnecessary to specify the actual file to load.
+
+For example,
+
+  rake state_machine:draw:rails CLASS=Vehicle
+
+==== Merb Integration
+
+Like Ruby on Rails, there is a special integration Rake task for generating
+state machines for classes used in a Merb application.  This task will load the
+application environment, meaning that it's unnecessary to specify the actual
+files to load.
+
+For example,
+
+  rake state_machine:draw:merb CLASS=Vehicle
+
+=== Interactive graphs
+
 Jean Bovet - {Visual Automata Simulator}[http://www.cs.usfca.edu/~jbovet/vas.html].
 This is a great tool for "simulating, visualizing and transforming finite state
 automata and Turing Machines".  This tool can help in the creation of states and
@@ -165,16 +370,19 @@ events for your models.  It is cross-platform, written in Java.
 
 == Testing
 
-Before you can run any tests, the following gem must be installed:
-* plugin_test_helper[http://github.com/pluginaweek/plugin_test_helper]
-
-To run against a specific version of Rails:
+To run the entire test suite (will test ActiveRecord, DataMapper, and Sequel
+integrations if available):
 
-  rake test RAILS_FRAMEWORK_ROOT=/path/to/rails
+  rake test
 
 == Dependencies
 
-* Rails 2.1 or later
+By default, there are no dependencies.  If using specific integrations, those
+dependencies are listed below.
+
+* ActiveRecord[http://rubyonrails.org] integration: 2.1.0 or later
+* DataMapper[http://datamapper.org] integration: 0.9.0 or later
+* Sequel[http://sequel.rubyforge.org] integration: 2.8.0 or later
 
 == References
 

data/Rakefile

@@ -5,11 +5,11 @@ require 'rake/contrib/sshpublisher'
 
 spec = Gem::Specification.new do |s|
   s.name              = 'state_machine'
-  s.version           = '0.3.1'
+  s.version           = '0.4.0'
   s.platform          = Gem::Platform::RUBY
-  s.summary           = 'Adds support for creating state machines for attributes within a model'
+  s.summary           = 'Adds support for creating state machines for attributes on any Ruby class'
   
-  s.files             = FileList['{lib,test}/**/*'] + %w(CHANGELOG.rdoc init.rb LICENSE Rakefile README.rdoc) - FileList['test/app_root/{log,log/*,script,script/*}']
+  s.files             = FileList['{examples,lib,test}/**/*'] + %w(CHANGELOG.rdoc init.rb LICENSE Rakefile README.rdoc) - FileList['test/app_root/{log,log/*,script,script/*}']
   s.require_path      = 'lib'
   s.has_rdoc          = true
   s.test_files        = Dir['test/**/*_test.rb']
@@ -86,3 +86,29 @@ task :release => [:gem, :package] do
     ruby_forge.add_release(spec.rubyforge_project, spec.name, spec.version, file)
   end
 end
+
+namespace :state_machine do
+  desc 'Draws a set of state machines using GraphViz. Target files to load with FILE=x,y,z; Machine class with CLASS=x,y,z; Font name with FONT=x; Image format with FORMAT=x'
+  task :draw do
+    # Load the library
+    $:.unshift(File.dirname(__FILE__) + '/lib')
+    require 'state_machine'
+    
+    # Build drawing options
+    options = {}
+    options[:file] = ENV['FILE'] if ENV['FILE']
+    options[:path] = ENV['TARGET'] if ENV['TARGET']
+    options[:format] = ENV['FORMAT'] if ENV['FORMAT']
+    options[:font] = ENV['FONT'] if ENV['FONT']
+    
+    StateMachine::Machine.draw(ENV['CLASS'], options)
+  end
+  
+  namespace :draw do
+    desc 'Draws a set of state machines using GraphViz for a Ruby on Rails application.  Target class with CLASS=x,y,z; Font name with FONT=x; Image format with FORMAT=x'
+    task :rails => [:environment, 'state_machine:draw']
+    
+    desc 'Draws a set of state machines using GraphViz for a Merb application.  Target class with CLASS=x,y,z; Font name with FONT=x; Image format with FORMAT=x'
+    task :merb => [:merb_env, 'state_machine:draw']
+  end
+end