state_machine 1.0.1 → 1.0.2

data/.gitignore

@@ -0,0 +1,11 @@
+*.gem
+.bundle
+coverage
+doc
+pkg
+rdoc
+test/active_record.log
+test/data_mapper.log
+test/mongo_mapper.log
+test/sequel.log
+Gemfile.lock

data/.travis.yml

@@ -0,0 +1,16 @@
+script: "bundle exec rake appraisal:integration test"
+rvm:
+  - 1.8.6
+  - 1.8.7
+  - 1.9.1
+  - 1.9.2
+env:
+  - INTEGRATION=default TRAVIS=true
+  - INTEGRATION=active_model TRAVIS=true
+  - INTEGRATION=active_record TRAVIS=true
+  - INTEGRATION=data_mapper TRAVIS=true
+  - INTEGRATION=mongoid TRAVIS=true
+  - INTEGRATION=mongo_mapper TRAVIS=true
+  - INTEGRATION=sequel TRAVIS=true
+notifications:
+  disabled: true

data/.yardopts

@@ -0,0 +1,5 @@
+--title "state_machine"
+--readme README.rdoc
+-
+CHANGELOG.rdoc
+LICENSE

data/Appraisals

@@ -0,0 +1,260 @@
+appraise "default" do
+end
+
+# ActiveRecord integrations
+if RUBY_VERSION < "1.9.1"
+  appraise "active_record-2.0.0" do
+    gem "sqlite3-ruby", "1.3.1"
+    gem "activerecord", "2.0.0"
+  end
+  
+  appraise "active_record-2.0.5" do
+    gem "sqlite3-ruby", "1.3.1"
+    gem "activerecord", "2.0.5"
+  end
+  
+  appraise "active_record-2.1.0" do
+    gem "sqlite3-ruby", "1.3.1"
+    gem "activerecord", "2.1.0"
+  end
+  
+  appraise "active_record-2.1.2" do
+    gem "sqlite3-ruby", "1.3.1"
+    gem "activerecord", "2.1.2"
+  end
+  
+  appraise "active_record-2.2.3" do
+    gem "sqlite3-ruby", "1.3.1"
+    gem "activerecord", "2.2.3"
+  end
+end
+
+appraise "active_record-2.3.12" do
+  gem "sqlite3-ruby", "1.3.1"
+  gem "activerecord", "2.3.12"
+end
+
+if RUBY_VERSION > "1.8.6"
+  appraise "active_record-3.0.0" do
+    gem "sqlite3-ruby"
+    gem "activerecord", "3.0.0"
+  end
+
+  appraise "active_record-3.0.5" do
+    gem "sqlite3-ruby"
+    gem "activerecord", "3.0.5"
+  end
+end
+
+# ActiveModel integrations
+if RUBY_VERSION > "1.8.6"
+  appraise "active_model-3.0.0" do
+    gem "activemodel", "3.0.0"
+  end
+
+  appraise "active_model-3.0.5" do
+    gem "activemodel", "3.0.5"
+  end
+end
+
+# MongoMapper integrations
+if RUBY_VERSION > "1.8.6" && RUBY_VERSION < "1.9.1"
+  appraise "mongo_mapper-0.5.5" do
+    gem "activesupport", "2.3.11"
+    gem "mongo_mapper", "0.5.5"
+  end
+end
+
+if RUBY_VERSION > "1.8.6"
+  appraise "mongo_mapper-0.5.8" do
+    gem "activesupport", "2.3.11"
+    gem "mongo_mapper", "0.5.8"
+  end
+
+  appraise "mongo_mapper-0.6.0" do
+    gem "activesupport", "2.3.11"
+    gem "mongo_mapper", "0.6.0"
+  end
+
+  appraise "mongo_mapper-0.6.10" do
+    gem "activesupport", "2.3.11"
+    gem "mongo_mapper", "0.6.10"
+  end
+
+  appraise "mongo_mapper-0.7.0" do
+    gem "activesupport", "2.3.11"
+    gem "mongo_mapper", "0.7.0"
+  end
+
+  appraise "mongo_mapper-0.7.5" do
+    gem "activesupport", "2.3.11"
+    gem "mongo_mapper", "0.7.5"
+  end
+
+  appraise "mongo_mapper-0.8.0" do
+    gem "activesupport", "2.3.11"
+    gem "mongo", "1.0.1"
+    gem "plucky", "0.3.0"
+    gem "mongo_mapper", "0.8.0"
+  end
+
+  appraise "mongo_mapper-0.8.3" do
+    gem "activesupport", "2.3.11"
+    gem "mongo", "1.0.1"
+    gem "plucky", "0.3.3"
+    gem "mongo_mapper", "0.8.3"
+  end
+
+  appraise "mongo_mapper-0.8.4" do
+    gem "activesupport", "2.3.11"
+    gem "mongo_mapper", "0.8.4"
+  end
+
+  appraise "mongo_mapper-0.8.6" do
+    gem "activesupport", "2.3.11"
+    gem "mongo_mapper", "0.8.6"
+  end
+
+  # MongoMapper 0.9.0+ breaks on Ruby 1.9.1
+  if RUBY_VERSION != "1.9.1"
+    appraise "mongo_mapper-0.9.0" do
+      gem "mongo_mapper", "0.9.0"
+    end
+  end
+end
+  
+# Mongoid integrations
+if RUBY_VERSION > "1.8.6"
+  appraise "mongoid-2.0.0" do
+    gem "mongoid", "2.0.0"
+  end
+  
+  appraise "mongoid-2.1.4" do
+    gem "mongoid", "2.1.4"
+  end
+end
+
+# Sequel integrations
+appraise "sequel-2.8.0" do
+  gem "sqlite3-ruby", "1.3.1"
+  gem "sequel", "2.8.0"
+end
+
+appraise "sequel-2.11.0" do
+  gem "sqlite3-ruby", "1.3.1"
+  gem "sequel", "2.11.0"
+end
+
+appraise "sequel-2.12.0" do
+  gem "sqlite3-ruby", "1.3.1"
+  gem "sequel", "2.12.0"
+end
+
+appraise "sequel-3.0.0" do
+  gem "sqlite3-ruby", "1.3.1"
+  gem "sequel", "3.0.0"
+end
+
+appraise "sequel-3.13.0" do
+  gem "sqlite3-ruby", "1.3.1"
+  gem "sequel", "3.13.0"
+end
+
+appraise "sequel-3.14.0" do
+  gem "sqlite3-ruby", "1.3.1"
+  gem "sequel", "3.14.0"
+end
+
+appraise "sequel-3.23.0" do
+  gem "sqlite3-ruby", "1.3.1"
+  gem "sequel", "3.23.0"
+end
+
+appraise "sequel-3.24.0" do
+  gem "sqlite3-ruby", "1.3.1"
+  gem "sequel", "3.24.0"
+end
+
+# DataMapper
+if RUBY_VERSION < "1.9.1"
+  appraise "data_mapper-0.9.4" do
+    gem "dm-core", "0.9.4"
+    gem "dm-migrations", "0.9.4"
+    gem "dm-validations", "0.9.4"
+    gem "dm-observer", "0.9.4"
+    gem "data_objects", "0.9.4"
+    gem "do_sqlite3", "0.9.4"
+  end
+
+  appraise "data_mapper-0.9.7" do
+    gem "dm-core", "0.9.7"
+    gem "dm-migrations", "0.9.7"
+    gem "dm-validations", "0.9.7"
+    gem "dm-observer", "0.9.7"
+    gem "data_objects", "0.9.7"
+    gem "do_sqlite3", "0.9.7"
+  end
+
+  appraise "data_mapper-0.9.11" do
+    gem "dm-core", "0.9.11"
+    gem "dm-migrations", "0.9.11"
+    gem "dm-validations", "0.9.11"
+    gem "dm-observer", "0.9.11"
+    gem "data_objects", "0.9.11"
+    gem "do_sqlite3", "0.9.11"
+  end
+
+  appraise "data_mapper-0.10.2" do
+    gem "dm-core", "0.10.2"
+    gem "dm-migrations", "0.10.2"
+    gem "dm-validations", "0.10.2"
+    gem "dm-observer", "0.10.2"
+    gem "data_objects", "0.10.2"
+    gem "do_sqlite3", "0.10.2"
+  end
+
+  appraise "data_mapper-0.10.2" do
+    gem "dm-core", "0.10.2"
+    gem "dm-migrations", "0.10.2"
+    gem "dm-validations", "0.10.2"
+    gem "dm-observer", "0.10.2"
+    gem "data_objects", "0.10.2"
+    gem "do_sqlite3", "0.10.2"
+  end
+end
+
+appraise "data_mapper-1.0.0" do
+  gem "dm-core", "1.0.0"
+  gem "dm-migrations", "1.0.0"
+  gem "dm-validations", "1.0.0"
+  gem "dm-observer", "1.0.0"
+  gem "dm-transactions", "1.0.0"
+  gem "dm-sqlite-adapter", "1.0.0"
+end
+
+appraise "data_mapper-1.0.1" do
+  gem "dm-core", "1.0.1"
+  gem "dm-migrations", "1.0.1"
+  gem "dm-validations", "1.0.1"
+  gem "dm-observer", "1.0.1"
+  gem "dm-transactions", "1.0.1"
+  gem "dm-sqlite-adapter", "1.0.1"
+end
+
+appraise "data_mapper-1.0.2" do
+  gem "dm-core", "1.0.2"
+  gem "dm-migrations", "1.0.2"
+  gem "dm-validations", "1.0.2"
+  gem "dm-observer", "1.0.2"
+  gem "dm-transactions", "1.0.2"
+  gem "dm-sqlite-adapter", "1.0.2"
+end
+
+appraise "data_mapper-1.1.0" do
+  gem "dm-core", "1.1.0"
+  gem "dm-migrations", "1.1.0"
+  gem "dm-validations", "1.1.0"
+  gem "dm-observer", "1.1.0"
+  gem "dm-transactions", "1.1.0"
+  gem "dm-sqlite-adapter", "1.1.0"
+end

data/CHANGELOG.rdoc

@@ -1,5 +1,20 @@
 == master
 
+== 1.0.2 / 2011-08-09
+
+* Allow transitions to be defined within a state, event, or machine context
+* Use supported framework hooks for integrating Sequel 3.24.0+
+* Use appraisal for testing integrations
+* Improve documentation on the handling of method conflicts
+* Update Mongoid integration for 2.1.0+ support
+* Fix ActiveRecord machine state predicates incorrectly calling superclass implementation when using targeted attributes
+* Fix error when defining states with the same name as the state's machine in ActiveRecord, MongoMapper, and Mongoid integrations
+* Fix machine state predicate not calling superclass implementation if defined after machine definition
+* Generate warnings when defining a helper method more than once
+* Fix multiple machines not being able to target the same attribute if all possible states aren't defined in each
+* Fix ActiveModel / DataMapper integrations not overriding StateMachine::Machine#after_initialize properly
+* Improve documentation for overriding states and integration transactions
+
 == 1.0.1 / 2011-05-30
 
 * Add the ability to ignore method conflicts for helpers

data/Gemfile

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

data/README.rdoc

@@ -1,4 +1,4 @@
-== state_machine
+== state_machine http://travis-ci.org/pluginaweek/state_machine.png
 
 +state_machine+ adds support for creating state machines for attributes on any
 Ruby class.
@@ -11,16 +11,24 @@ API
 
 Bugs
 
-* http://pluginaweek.lighthouseapp.com/projects/13288-state_machine
+* http://github.com/pluginaweek/state_machine/issues
 
 Development
 
 * http://github.com/pluginaweek/state_machine
 
+Testing
+
+* http://travis-ci.org/pluginaweek/state_machine
+
 Source
 
 * git://github.com/pluginaweek/state_machine.git
 
+Mailing List
+
+* http://groups.google.com/group/pluginaweek-talk
+
 == Description
 
 State machines make it dead-simple to manage the behavior of a class.  Too often,
@@ -49,6 +57,7 @@ Some brief, high-level features include:
 * Inheritance
 * Internationalization
 * GraphViz visualization creator
+* Flexible machine syntax
 
 Examples of the usage patterns for some of the above features are shown below.
 You can find much more detailed documentation in the actual API.
@@ -581,11 +590,21 @@ errors and callbacks.  For example,
 For more information about the various behaviors added for Sequel state
 machines, see StateMachine::Integrations::Sequel.
 
-== Compatibility
+== Syntax flexibility
 
 Although state_machine introduces a simplified syntax, it still remains
-backwards compatible with previous versions and other state-related libraries.
-For example, transitions and callbacks can continue to be defined like so:
+backwards compatible with previous versions and other state-related libraries by
+providing some flexibility around how transitions are defined.  See below for an
+overview of these syntaxes.
+
+=== Verbose syntax
+
+In general, it's recommended that state machines use the implicit syntax for
+transitions.  However, you can be a little more explicit and verbose about
+transitions by using the <tt>:from</tt>, <tt>:except_from</tt>, <tt>:to</tt>,
+and <tt>:except_to</tt> options.
+
+For example, transitions and callbacks can be defined like so:
 
   class Vehicle
     state_machine :initial => :parked do
@@ -600,9 +619,64 @@ For example, transitions and callbacks can continue to be defined like so:
     end
   end
 
-Although this verbose syntax will most likely always be supported, it is
-recommended that any state machines eventually migrate to the syntax introduced
-in version 0.6.0.
+=== Transition context
+
+Some flexibility is provided around the context in which transitions can be
+defined.  In almost all examples throughout the documentation, transitions are
+defined within the context of an event.  If you prefer to have state machines
+defined in the context of a *state* either out of preference or in order to
+easily migrate from a different library, you can do so as shown below:
+
+  class Vehicle
+    state_machine :initial => :parked do
+      ...
+      
+      state :parked do
+        transition :to => :idling, :on => [:ignite, :shift_up], :if => :seatbelt_on?
+        
+        def speed
+          0
+        end
+      end
+      
+      state :first_gear do
+        transition :to => :second_gear, :on => :shift_up
+        
+        def speed
+          10
+        end
+      end
+      
+      state :idling, :first_gear do
+        transition :to => :parked, :on => :park
+      end
+    end
+  end
+
+In the above example, there's no need to specify the +from+ state for each
+transition since it's inferred from the context.
+
+You can also define transitions completely outside the context of a particular
+state / event.  This may be useful in cases where you're building a state
+machine from a data store instead of part of the class definition.  See the
+example below:
+
+  class Vehicle
+    state_machine :initial => :parked do
+      ...
+      
+      transition :parked => :idling, :on => [:ignite, :shift_up]
+      transition :first_gear => :second_gear, :second_gear => :third_gear, :on => :shift_up
+      transition [:idling, :first_gear] => :parked, :on => :park
+      transition [:idling, :first_gear] => :parked, :on => :park
+      transition all - [:parked, :stalled] => :stalled, :unless => :auto_shop_busy?
+    end
+  end
+
+Notice that in these alternative syntaxes:
+* You can continue to configure <tt>:if</tt> and <tt>:unless</tt> conditions
+* You can continue to define +from+ states (when in the machine context) using
+the +all+, +any+, and +same+ helper methods
 
 == Tools
 
@@ -638,7 +712,63 @@ in the class.  The generated files will use an output filename of the format
 For examples of actual images generated using this task, see those under the
 examples folder.
 
-==== Ruby on Rails Integration
+=== Interactive graphs
+
+Jean Bovet's {Visual Automata Simulator}[http://www.cs.usfca.edu/~jbovet/vas.html]
+is a great tool for "simulating, visualizing and transforming finite state
+automata and Turing Machines".  It can help in the creation of states and events
+for your models.  It is cross-platform, written in Java.
+
+== Web Frameworks
+
+=== Ruby on Rails
+
+Integrating state_machine into your Ruby on Rails application is straightforward
+and provides a few additional features specific to the framework.  To get
+started, following the steps below.
+
+==== 1. Install the gem
+
+If using Rails 2.x:
+
+  # In config/environment.rb
+  ...
+  Rails::Initializer.run do |config|
+    ...
+    config.gem 'state_machine', :version => '~> 1.0'
+    ...
+  end
+
+If using Rails 3.x or up:
+
+  # In Gemfile
+  ...
+  gem 'state_machine'
+  gem 'ruby-graphviz', :require => 'graphviz' # Optional: only required for graphing
+
+As usual, run <tt>bundle install</tt> to load the gems.
+
+==== 2. Create a model
+
+Create a model with a field to store the state, along with other any other
+fields your application requires:
+
+  $ rails generate model Vehicle state:string
+  $ rake db:migrate
+
+==== 3. Configure the state machine
+
+Add the state machine to your model.  Following the examples above,
++app/models/vehicle.rb+ might become:
+
+  class Vehicle < ActiveRecord::Base
+    state_machine :initial => :parked do
+      before_transition :parked => any - :parked, :do => :put_on_seatbelt
+      ...
+    end
+  end
+
+==== Rake tasks
 
 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
@@ -653,12 +783,9 @@ to the end of your application's Rakefile in order for the above task to work:
 
   require 'tasks/state_machine'
 
-If you are using Rails 3.0+, you must also add the following to your
-application's Gemfile:
-
-  gem 'ruby-graphviz', :require => 'graphviz'
+=== Merb
 
-==== Merb Integration
+==== Rake tasks
 
 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
@@ -669,27 +796,27 @@ For example,
 
   rake state_machine:draw CLASS=Vehicle
 
-=== Interactive graphs
-
-Jean Bovet's {Visual Automata Simulator}[http://www.cs.usfca.edu/~jbovet/vas.html]
-is a great tool for "simulating, visualizing and transforming finite state
-automata and Turing Machines".  It can help in the creation of states and events
-for your models.  It is cross-platform, written in Java.
-
 == Testing
 
 To run the core test suite (does *not* test any of the integrations):
 
-  rake test
+  bundle install
+  bundle exec rake test
+
+To run integration tests:
+
+  bundle install
+  rake appraisal:install
+  rake appraisal:test
 
-Test specific versions of integrations like so:
+You can also test a specific version:
 
-  rake test INTEGRATION=active_model VERSION=3.0.0
-  rake test INTEGRATION=active_record VERSION=2.0.0
-  rake test INTEGRATION=data_mapper VERSION=0.9.4
-  rake test INTEGRATION=mongoid VERSION=2.0.0
-  rake test INTEGRATION=mongo_mapper VERSION=0.5.5
-  rake test INTEGRATION=sequel VERSION=2.8.0
+  rake appraisal:active_model-3.0.0 test
+  rake appraisal:active_record-2.0.0 test
+  rake appraisal:data_mapper-0.9.4 test
+  rake appraisal:mongoid-2.0.0 test
+  rake appraisal:mongo_mapper-0.5.5 test
+  rake appraisal:sequel-2.8.0 test
 
 == Caveats