hsume2-state_machine 1.0.1

data/CHANGELOG.rdoc

@@ -0,0 +1,413 @@
+== master
+
+== 1.0.1 / 2011-05-30
+
+* Add the ability to ignore method conflicts for helpers
+* Generate warnings for any helper, not just state helpers, that has a conflicting method defined in the class
+* Fix scopes in Sequel not working if the table name contains double underscores or is not a string/symbol
+* Add full support for chaining state scopes within Sequel integrations
+* Fix Rails 3.1 deprecation warnings for configuring engine locales [Stefan Penner]
+
+== 1.0.0 / 2011-05-12
+
+* Celebrate
+
+== 0.10.4 / 2011-04-14
+
+* Fix translations not being available under certain environments in Rails applications
+
+== 0.10.3 / 2011-04-07
+
+* Fix state initialization failing in ActiveRecord 3.0.2+ when using with_state scopes for the default scope
+
+== 0.10.2 / 2011-03-31
+
+* Use more integrated state initialization hooks for ActiveRecord, Mongoid, and Sequel
+* Remove mass-assignment filtering usage in all ORM integrations
+* Only support official Mongoid 2.0.0 release and up (no more RC support)
+* Fix attributes getting initialized more than once if different state machines use the same attribute
+* Only initialize states if state is blank and blank is not a valid state
+* Fix instance / class helpers failing when used with certain libraries (such as Thin)
+
+== 0.10.1 / 2011-03-22
+
+* Fix classes with multiple state machines failing to initialize in ActiveRecord / Mongoid / Sequel integrations
+
+== 0.10.0 / 2011-03-19
+
+* Support callback terminators in MongoMapper 0.9.0+
+* Fix pluralization integration on DataMapper 1.0.0 and 1.1.0
+* Allow transition guards to be bypassed for event / transition / path helpers
+* Allow state / condition requirements to be specified for all event / transition / path helpers
+* Add the ability to skip automatically initializing state machines on #initialize
+* Add #{name}_paths for walking the available paths in a state machine
+* Add Mongoid 2.0.0+ support
+* Use around hooks to improve compatibility with other libraries in ActiveModel / ActiveRecord / MongoMapper integrations
+* Add support for MassAssignmentSecurity feature in ActiveModel integrations
+* Add support for more observer hooks within MongoMapper integrations
+* Add i18n support for MongoMapper validation errors
+* Update support for MongoMapper integration based on rails3 branch
+* Fix objects not getting marked as dirty in all integrations when #{name}_event is set
+* Generate warnings when conflicting state / event names are detected
+* Allow fallback to generic state predicates when individual predicates are already defined in the owner class
+* Replace :include_failures after_transition option with new after_failure callback
+* Provide access to transition context when raising InvalidEvent / InvalidTransition exceptions
+
+== 0.9.4 / 2010-08-01
+
+* Fix validation / save hooks in Sequel 3.14.0+
+* Fix integration with dirty attribute tracking on DataMapper 1.0.1+
+* Fix DataMapper 1.0.1+ tests producing warnings
+* Fix validation error warnings in ActiveModel / ActiveRecord 3.0.0 beta5+
+* Fix mass-assignment sanitization breaking in ActiveRecord 3.0.0 beta5+ [Akira Matsuda]
+
+== 0.9.3 / 2010-06-26
+
+* Allow access to human state / event names in transitions and for the current state
+* Use human state / event names in error messages
+* Fix event names being used inconsistently in error messages
+* Allow access to the humanized version of state / event names via human_state_name / human_state_event_name
+* Allow MongoMapper 0.8.0+ scopes to be chainable
+* Fix i18n deprecation warnings in ActiveModel / ActiveRecord 3.0.0.beta4
+* Fix default error message translations overriding existing locales in ActiveModel / ActiveRecord
+
+== 0.9.2 / 2010-05-24
+
+* Fix MongoMapper integration failing in Ruby 1.9.2
+* Fix Rakefile not loading in Ruby 1.9.2 [Andrea Longhi]
+* Fix nil / false :integration configuration not being respected
+
+== 0.9.1 / 2010-05-02
+
+* Fix ActiveRecord 2.0.0 - 2.2.3 integrations failing if version info isn't already loaded
+* Fix integration with dirty attribute tracking on DataMapper 0.10.3
+* Fix observers failing in ActiveRecord 3.0.0.beta4+ integrations
+* Fix deprecation warning in Rails 3 railtie [Chris Yuan]
+
+== 0.9.0 / 2010-04-12
+
+* Use attribute-based event transitions whenever possible to ensure consistency
+* Fix action helpers being defined when the action is *only* defined in the machine's owner class
+* Disable attribute-based event transitions in DataMapper 0.9.4 - 0.9.6 when dm-validations is being used
+* Add support for DataMapper 0.10.3+
+* Add around_transition callbacks
+* Fix transition failures during save not being handled correctly in Sequel 2.12.0+
+* Fix attribute-based event transitions not hooking in properly in DataMapper 0.10.0+ and Sequel 2.12.0+
+* Fix dynamic initial states causing errors in Ruby 1.9+ if no arguments are defined in the block
+* Add MongoMapper 0.5.5+ support
+* Add ActiveModel 3.0+ support for use with integrations that implement its interface
+* Fix DataMapper integration failing when ActiveSupport is loaded in place of Extlib
+* Add version dependencies for ruby-graphviz
+* Remove app-specific rails / merb rake tasks in favor of always running state_machine:draw
+* Add Rails 3 railtie for automatically loading rake tasks when installed as a gem
+
+== 0.8.1 / 2010-03-14
+
+* Release gems via rake-gemcutter instead of rubyforge
+* Move rake tasks to lib/tasks
+* Dispatch state behavior to the superclass if it's undefined for a particular state [Sandro Turriate and Tim Pope]
+* Fix state / event names not supporting i18n in ActiveRecord
+* Fix original ActiveRecord::Observer#update not being used for non-state_machine callbacks [Jeremy Wells]
+* Add support for ActiveRecord 3.0
+* Fix without_{name} scopes not quoting columns in ActiveRecord [Jon Evans]
+* Fix without_{name} scopes not scoping columns to the table in ActiveRecord and Sequel [Jon Evans]
+* Fix custom state attributes not being marked properly as changed in ActiveRecord
+* Fix tracked attributes changes in ActiveRecord / DataMapper integrations not working correctly for non-loopbacks [Joe Lind]
+* Fix plural scope names being incorrect for DataMapper 0.9.4 - 0.9.6
+* Fix deprecation warnings for ruby-graphviz 0.9.0+
+* Add support for ActiveRecord 2.0.*
+* Fix nil states being overwritten when they're explicitly set in ORM integrations
+* Fix default states not getting set in ORM integrations if the column has a default
+* Fix event transitions being kept around while running actions/callbacks, sometimes preventing object marshalling
+
+== 0.8.0 / 2009-08-15
+
+* Add support for DataMapper 0.10.0
+* Always interpet nil return values from actions as failed attempts
+* Fix loopbacks not causing records to save in ORM integrations if no other fields were changed
+* Fix events not failing with useful errors when an object's state is invalid
+* Use more friendly NoMethodError messages for state-driven behaviors
+* Fix before_transition callbacks getting run twice when using event attributes in ORM integrations
+* Add the ability to query for the availability of specific transitions on an object
+* Allow after_transition callbacks to be explicitly run on failed attempts
+* By default, don't run after_transition callbacks on failed attempts
+* Fix not allowing multiple methods to be specified as arguments in callbacks
+* Fix initial states being set when loading records from the database in Sequel integration
+* Allow static initial states to be set earlier in the initialization of an object
+* Use friendly validation errors for nil states
+* Fix states not being validated properly when using custom names in ActiveRecord / DataMapper integrations
+
+== 0.7.6 / 2009-06-17
+
+* Allow multiple state machines on the same class to target the same attribute
+* Add support for :attribute to customize the attribute target, assuming the name is the first argument of #state_machine
+* Simplify reading from / writing to machine-related attributes on objects
+* Fix locale for ActiveRecord getting added to the i18n load path multiple times [Reiner Dieterich]
+* Fix callbacks, guards, and state-driven behaviors not always working on tainted classes [Brandon Dimcheff]
+* Use Ruby 1.9's built-in Object#instance_exec for bound callbacks when it's available
+* Improve performance of cached dynamic state lookups by 25%
+
+== 0.7.5 / 2009-05-25
+
+* Add built-in caching for dynamic state values when the value only needs to be generated once
+* Fix flawed example for using record ids as state values
+* Don't evaluate state values until they're actually used in an object instance
+* Make it easier to use event attributes for actions defined in the same class as the state machine
+* Fix #save/save! running transitions in ActiveRecord integrations even when a machine's action is not :save
+
+== 0.7.4 / 2009-05-23
+
+* Fix #save! not firing event attributes properly in ActiveRecord integrations
+* Fix log files being included in gems
+
+== 0.7.3 / 2009-04-25
+
+* Require DataMapper version be >= 0.9.4
+* Explicitly load Sequel's built-in inflector (>= 2.12.0) for scope names
+* Don't use qualified name for event attributes
+* Fix #valid? being defined for DataMapper resources when dm-validations isn't loaded
+* Add auto-validation of values allowed for the state attribute in ORM integrations
+
+== 0.7.2 / 2009-04-08
+
+* Add support for running multiple methods in a callback without using blocks
+* Add more flexibility around how callbacks are defined
+* Add security documentation around mass-assignment in ORM integrations
+* Fix event attribute transitions being publicly accessible
+
+== 0.7.1 / 2009-04-05
+
+* Fix machines failing to generate graphs when run from Merb tasks
+
+== 0.7.0 / 2009-04-04
+
+* Add #{attribute}_event for automatically firing events when the object's action is called
+* Make it easier to override state-driven behaviors
+* Rollback state changes when the action fails during transitions
+* Use :messages instead of :invalid_message for customizing validation errors
+* Use more human-readable validation errors
+* Add support for more ActiveRecord observer hooks
+* Add support for targeting multiple specific state machines in DataMapper observer hooks
+* Don't pass the result of the action as an argument to callbacks (access via Transition#result)
+* Fix incorrect results being used when running transitions in parallel
+* Fix transition args not being set when run in parallel
+* Allow callback terminators to be set on an application-wide basis
+* Only catch :halt during before / after transition callbacks
+* Fix ActiveRecord predicates being overwritten if they're already defined in the class
+* Allow machine options to be set on an integration-wide basis
+* Turn transactions off by default in DataMapper integrations
+* Add support for configuring the use of transactions
+* Simplify reading/writing of attributes
+* Simplify access to state machines via #state_machine(:attribute) without generating dupes
+* Fix assumptions that dm-validations is always available in DataMapper integration
+* Automatically define DataMapper properties for machine attributes if they don't exist
+* Add Transition#qualified_event, #qualified_from_name, and #qualified_to_name
+* Add #fire_events / #fire_events! for running events on multiple state machines in parallel
+* Rename next_#{event}_transition to #{event}_transition
+* Add #{attribute}_transitions for getting the list of transitions that can be run on an object
+* Add #{attribute}_events for getting the list of events that can be fired on an object
+* Use generated non-bang event when running bang version so that overriding one affects the other
+* Provide access to arguments passed into an event from transition callbacks via Transition#args
+
+== 0.6.3 / 2009-03-10
+
+* Add support for customizing the graph's orientation
+* Use the standard visualizations for initial (open arrow) and final (double circle) states
+* Highlight final states in GraphViz drawings
+
+== 0.6.2 / 2009-03-08
+
+* Make it easier to override generated instance / class methods
+
+== 0.6.1 / 2009-03-07
+
+* Add i18n support for ActiveRecord validation errors
+* Add a validation error when failing to transition for ActiveRecord / DataMapper / Sequel integrations
+
+== 0.6.0 / 2009-03-03
+
+* Allow multiple conditions for callbacks / class behaviors
+* Add support for state-driven class behavior with :if/:unless options
+* Alias Machine#event as Machine#on
+* Fix nil from/to states not being handled properly
+* Simplify hooking callbacks into loopbacks
+* Add simplified transition/callback requirement syntax
+
+== 0.5.2 / 2009-02-17
+
+* Improve pretty-print of events
+* Simplify state/event matching design, improving guard performance by 30%
+* Add better error notification when conflicting guard options are defined
+* Fix scope name pluralization not being applied correctly
+
+== 0.5.1 / 2009-02-11
+
+* Allow states to be drawn as ellipses to accommodate long names
+* Fix rake tasks not being registered in Rails/Merb applications
+* Never automatically define machine attribute accessors when using an integration
+
+== 0.5.0 / 2009-01-11
+
+* Add to_name and from_name to transition objects
+* Add nicely formatted #inspect for transitions
+* Fix ActiveRecord integrations failing when the database doesn't exist yet
+* Fix states not being drawn in GraphViz graphs in the correct order
+* Add nicely formatted #inspect for states and events
+* Simplify machine context-switching
+* Store events/states in enumerable node collections
+* No longer allow subclasses to change the integration
+* Move fire! action logic into the Event class (no longer calls fire action on the object)
+* Allow states in subclasses to have different values
+* Recommend that all states be referenced as symbols instead of strings
+* All states must now be named (and can be associated with other value types)
+* Add support for customizing the actual stored value for a state
+* Add compatibility with Ruby 1.9+
+
+== 0.4.3 / 2008-12-28
+
+* Allow dm-observer integration to be optional
+* Fix non-lambda callbacks not working for DataMapper/Sequel
+
+== 0.4.2 / 2008-12-28
+
+* Fix graphs not being drawn the same way consistently
+* Add support for sharing transitions across multiple events
+* Add support for state-driven behavior
+* Simplify initialize hooks, requiring super to be called instead
+* Add :namespace option for generated state predicates / event methods
+
+== 0.4.1 / 2008-12-16
+
+* Fix nil states not being handled properly in guards, known states, or visualizations
+* Fix the same node being used for different dynamic states in GraphViz output
+* Always include initial state in the list of known states even if it's dynamic
+* Use consistent naming scheme for dynamic states in GraphViz output
+* Allow blocks to be directly passed into machine class
+* Fix attribute predicates not working on attributes that represent columns in ActiveRecord
+
+== 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
+* Change how the base module is included to prevent namespacing conflicts
+
+== 0.3.0 / 2008-09-07
+
+* No longer allow additional arguments to be passed into event actions
+* Add support for can_#{event}? for checking whether an event can be fired based on the current state of the record
+* Don't use callbacks for performing transitions
+* Fix state machines in subclasses not knowing what states/events/transitions were defined by superclasses
+* Replace all before/after_exit/enter/loopback callback hooks and :before/:after options for events with before_transition/after_transition callbacks, e.g.
+  
+  before_transition :from => 'parked', :do => :lock_doors # was before_exit :parked, :lock_doors
+  after_transition :on => 'ignite', :do => :turn_on_radio # was event :ignite, :after => :turn_on_radio do
+  
+* Always save when an event is fired even if it results in a loopback [Jürgen Strobel]
+* Ensure initial state callbacks are invoked in the proper order when an event is fired on a new record
+* Add before_loopback and after_loopback hooks [Jürgen Strobel]
+
+== 0.2.1 / 2008-07-05
+
+* Add more descriptive exceptions
+* Assume the default state attribute is "state" if one is not provided
+* Add :except_from option for transitions if you want to blacklist states
+* Add PluginAWeek::StateMachine::Machine#states
+* Add PluginAWeek::StateMachine::Event#transitions
+* Allow creating transitions with no from state (effectively allowing the transition for *any* from state)
+* Reduce the number of objects created for each transition
+
+== 0.2.0 / 2008-06-29
+
+* Add a non-bang version of events (e.g. park) that will return a boolean value for success
+* Raise an exception if the bang version of events are used (e.g. park!) and no transition is successful
+* Change callbacks to act a little more like ActiveRecord
+* Avoid using string evaluation for dynamic methods
+
+== 0.1.1 / 2008-06-22
+
+* Remove log files from gems
+
+== 0.1.0 / 2008-05-05
+
+* Completely rewritten from scratch
+* Renamed to state_machine
+* Removed database dependencies
+* Removed models in favor of an attribute-agnostic design
+* Use ActiveSupport::Callbacks instead of eval_call
+* Remove dry_transaction_rollbacks dependencies
+* Added functional tests
+* Updated documentation
+
+== 0.0.1 / 2007-09-26
+
+* Add dependency on custom_callbacks
+* Move test fixtures out of the test application root directory
+* Improve documentation
+* Remove the StateExtension module in favor of adding singleton methods to the stateful class
+* Convert dos newlines to unix newlines
+* Fix error message when a given event can't be found in the database
+* Add before_#{action} and #{action} callbacks when an event is performed
+* All state and event callbacks can now explicitly return false in order to cancel the action
+* Refactor ActiveState callback creation
+* Refactor unit tests so that they use mock classes instead of themselves
+* Allow force_reload option to be set in the state association
+* Don't save the entire model when updating the state_id
+* Raise exception if a class tries to define a state more than once
+* Add tests for PluginAWeek::Has::States::ActiveState
+* Refactor active state/active event creation
+* Fix owner_type not being set correctly in active states/events of subclasses
+* Allow subclasses to override the initial state
+* Fix problem with migrations using default null when column cannot be null
+* Moved deadline support into a separate plugin (has_state_deadlines).
+* Added many more unit tests.
+* Simplified many of the interfaces for maintainability.
+* Added support for turning off recording state changes.
+* Removed the short_description and long_description columns, in favor of an optional human_name column.
+* Fixed not overriding the correct equality methods in the StateTransition class.
+* Added to_sym to State and Event.
+* State#name and Event#name now return the string version of the name instead of the symbol version.
+* Added State#human_name and Event#human_name to automatically figure out what the human name is if it isn't specified in the table.
+* Updated manual rollbacks to use the new Rails edge api (ActiveRecord::Rollback exception).
+* Moved StateExtension class into a separate file in order to help keep the has_state files clean.
+* Renamed InvalidState and InvalidEvent exceptions to StateNotFound and EventNotFound in order to follow the ActiveRecord convention (i.e. RecordNotFound).
+* Added StateNotActive and EventNotActive exceptions to help differentiate between states which don't exist and states which weren't defined in the class.
+* Added support for defining callbacks like so:
+  
+  def before_exit_parked
+  end
+  
+  def after_enter_idling
+  end
+
+* Added support for defining callbacks using class methods:
+  
+  before_exit_parked :fasten_seatbelt
+
+* Added event callbacks after the transition has occurred (e.g. after_park)
+* State callbacks no longer receive any of the arguments that were provided in the event action
+* Updated license to include our names.

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006-2011 Aaron Pfefier
+
+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.rdoc

@@ -0,0 +1,717 @@
+== state_machine
+
++state_machine+ adds support for creating state machines for attributes on any
+Ruby class.
+
+== Resources
+
+API
+
+* http://rdoc.info/github/pluginaweek/state_machine/master/frames
+
+Bugs
+
+* http://pluginaweek.lighthouseapp.com/projects/13288-state_machine
+
+Development
+
+* http://github.com/pluginaweek/state_machine
+
+Source
+
+* git://github.com/pluginaweek/state_machine.git
+
+== Description
+
+State machines make it dead-simple to manage the behavior of a class.  Too often,
+the state 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, 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
+* Namespaced state machines
+* before/after/around/failure transition hooks with explicit transition requirements
+* Integration with ActiveModel, ActiveRecord, DataMapper, Mongoid, MongoMapper, and Sequel
+* State predicates
+* State-driven instance / class behavior
+* State values of any data type
+* Dynamically-generated state values
+* Event parallelization
+* Attribute-based event transitions
+* Path analysis
+* Inheritance
+* Internationalization
+* GraphViz visualization creator
+
+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.
+
+== Usage
+
+=== Example
+
+Below is an example of many of the features offered by this plugin, including:
+* Initial states
+* Namespaced states
+* Transition callbacks
+* Conditional transitions
+* State-driven instance behavior
+* Customized state values
+* Parallel events
+* Path analysis
+
+Class definition:
+
+  class Vehicle
+    attr_accessor :seatbelt_on, :time_used
+    
+    state_machine :state, :initial => :parked do
+      before_transition :parked => any - :parked, :do => :put_on_seatbelt
+      
+      after_transition :on => :crash, :do => :tow
+      after_transition :on => :repair, :do => :fix
+      after_transition any => :parked do |vehicle, transition|
+        vehicle.seatbelt_on = false
+      end
+      
+      after_failure :on => :ignite, :do => :log_start_failure
+      
+      around_transition do |vehicle, transition, block|
+        start = Time.now
+        block.call
+        vehicle.time_used += Time.now - start
+      end
+      
+      event :park do
+        transition [:idling, :first_gear] => :parked
+      end
+      
+      event :ignite do
+        transition :stalled => same, :parked => :idling
+      end
+      
+      event :idle do
+        transition :first_gear => :idling
+      end
+      
+      event :shift_up do
+        transition :idling => :first_gear, :first_gear => :second_gear, :second_gear => :third_gear
+      end
+      
+      event :shift_down do
+        transition :third_gear => :second_gear, :second_gear => :first_gear
+      end
+      
+      event :crash do
+        transition all - [:parked, :stalled] => :stalled, :unless => :auto_shop_busy?
+      end
+      
+      event :repair do
+        # The first transition that matches the state and passes its conditions
+        # will be used
+        transition :stalled => :parked, :if => :auto_shop_busy?
+        transition :stalled => same
+      end
+      
+      state :parked do
+        def speed
+          0
+        end
+      end
+      
+      state :idling, :first_gear do
+        def speed
+          10
+        end
+      end
+      
+      state :second_gear do
+        def speed
+          20
+        end
+      end
+    end
+    
+    state_machine :alarm_state, :initial => :active, :namespace => 'alarm' do
+      event :enable do
+        transition all => :active
+      end
+      
+      event :disable do
+        transition all => :off
+      end
+      
+      state :active, :value => 1
+      state :off, :value => 0
+    end
+    
+    def initialize
+      @seatbelt_on = false
+      @time_used = 0
+      super() # NOTE: This *must* be called, otherwise states won't get initialized
+    end
+    
+    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
+    
+    def log_start_failure
+      # log a failed attempt to start the vehicle
+    end
+  end
+
+*Note* the comment made on the +initialize+ method in the class.  In order for
+state machine attributes to be properly initialized, <tt>super()</tt> must be called.
+See StateMachine::MacroMethods for more information about this.
+
+Using the above class as an example, you can interact with the state machine
+like so:
+
+  vehicle = Vehicle.new           # => #<Vehicle:0xb7cf4eac @state="parked", @seatbelt_on=false>
+  vehicle.state                   # => "parked"
+  vehicle.state_name              # => :parked
+  vehicle.human_state_name        # => "parked"
+  vehicle.parked?                 # => true
+  vehicle.can_ignite?             # => true
+  vehicle.ignite_transition       # => #<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>
+  vehicle.state_events            # => [:ignite]
+  vehicle.state_transitions       # => [#<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
+  vehicle.speed                   # => 0
+  
+  vehicle.ignite                  # => true
+  vehicle.parked?                 # => false
+  vehicle.idling?                 # => true
+  vehicle.speed                   # => 10
+  vehicle                         # => #<Vehicle:0xb7cf4eac @state="idling", @seatbelt_on=true>
+  
+  vehicle.shift_up                # => true
+  vehicle.speed                   # => 10
+  vehicle                         # => #<Vehicle:0xb7cf4eac @state="first_gear", @seatbelt_on=true>
+  
+  vehicle.shift_up                # => true
+  vehicle.speed                   # => 20
+  vehicle                         # => #<Vehicle:0xb7cf4eac @state="second_gear", @seatbelt_on=true>
+  
+  # The bang (!) operator can raise exceptions if the event fails
+  vehicle.park!                   # => StateMachine::InvalidTransition: Cannot transition state via :park from :second_gear
+  
+  # Generic state predicates can raise exceptions if the value does not exist
+  vehicle.state?(:parked)         # => false
+  vehicle.state?(:invalid)        # => IndexError: :invalid is an invalid name
+  
+  # Namespaced machines have uniquely-generated methods
+  vehicle.alarm_state             # => 1
+  vehicle.alarm_state_name        # => :active
+  
+  vehicle.can_disable_alarm?      # => true
+  vehicle.disable_alarm           # => true
+  vehicle.alarm_state             # => 0
+  vehicle.alarm_state_name        # => :off
+  vehicle.can_enable_alarm?       # => true
+  
+  vehicle.alarm_off?              # => true
+  vehicle.alarm_active?           # => false
+  
+  # Events can be fired in parallel
+  vehicle.fire_events(:shift_down, :enable_alarm) # => true
+  vehicle.state_name                              # => :first_gear
+  vehicle.alarm_state_name                        # => :active
+  
+  vehicle.fire_events!(:ignite, :enable_alarm)    # => StateMachine::InvalidTransition: Cannot run events in parallel: ignite, enable_alarm
+  
+  # Human-friendly names can be accessed for states/events
+  Vehicle.human_state_name(:first_gear)               # => "first gear"
+  Vehicle.human_alarm_state_name(:active)             # => "active"
+  
+  Vehicle.human_state_event_name(:shift_down)         # => "shift down"
+  Vehicle.human_alarm_state_event_name(:enable)       # => "enable"
+  
+  # Available transition paths can be analyzed for an object
+  vehicle.state_paths                                       # => [[#<StateMachine::Transition ...], [#<StateMachine::Transition ...], ...]
+  vehicle.state_paths.to_states                             # => [:parked, :idling, :first_gear, :stalled, :second_gear, :third_gear]
+  vehicle.state_paths.events                                # => [:park, :ignite, :shift_up, :idle, :crash, :repair, :shift_down]
+  
+  # Find all paths that start and end on certain states
+  vehicle.state_paths(:from => :parked, :to => :first_gear) # => [[
+                                                            #       #<StateMachine::Transition attribute=:state event=:ignite from="parked" ...>,
+                                                            #       #<StateMachine::Transition attribute=:state event=:shift_up from="idling" ...>
+                                                            #    ]]
+
+== 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:
+* ActiveModel classes
+* ActiveRecord models
+* DataMapper resources
+* Mongoid models
+* MongoMapper models
+* Sequel models
+
+A brief overview of these integrations is described below.
+
+=== ActiveModel
+
+The ActiveModel integration is useful for both standalone usage and for providing
+the base implementation for ORMs which implement the ActiveModel API.  This
+integration adds support for validation errors, dirty attribute tracking, and
+observers.  For example,
+
+  class Vehicle
+    include ActiveModel::Dirty
+    include ActiveModel::Validations
+    include ActiveModel::Observing
+    
+    attr_accessor :state
+    define_attribute_methods [:state]
+    
+    state_machine :initial => :parked do
+      before_transition :parked => any - :parked, :do => :put_on_seatbelt
+      after_transition any => :parked do |vehicle, transition|
+        vehicle.seatbelt = 'off'
+      end
+      around_transition :benchmark
+      
+      event :ignite do
+        transition :parked => :idling
+      end
+      
+      state :first_gear, :second_gear do
+        validates_presence_of :seatbelt_on
+      end
+    end
+    
+    def put_on_seatbelt
+      ...
+    end
+    
+    def benchmark
+      ...
+      yield
+      ...
+    end
+  end
+  
+  class VehicleObserver < ActiveModel::Observer
+    # Callback for :ignite event *before* the transition is performed
+    def before_ignite(vehicle, transition)
+      # log message
+    end
+    
+    # Generic transition callback *after* the transition is performed
+    def after_transition(vehicle, transition)
+      Audit.log(vehicle, transition)
+    end
+    
+    # Generic callback after the transition fails to perform
+    def after_failure_to_transition(vehicle, transition)
+      Audit.error(vehicle, transition)
+    end
+  end
+
+For more information about the various behaviors added for ActiveModel state
+machines and how to build new integrations that use ActiveModel, see
+StateMachine::Integrations::ActiveModel.
+
+=== ActiveRecord
+
+The ActiveRecord integration adds support for database transactions, automatically
+saving the record, named scopes, validation errors, and observers.  For example,
+
+  class Vehicle < ActiveRecord::Base
+    state_machine :initial => :parked do
+      before_transition :parked => any - :parked, :do => :put_on_seatbelt
+      after_transition any => :parked do |vehicle, transition|
+        vehicle.seatbelt = 'off'
+      end
+      around_transition :benchmark
+      
+      event :ignite do
+        transition :parked => :idling
+      end
+      
+      state :first_gear, :second_gear do
+        validates_presence_of :seatbelt_on
+      end
+    end
+    
+    def put_on_seatbelt
+      ...
+    end
+    
+    def benchmark
+      ...
+      yield
+      ...
+    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 *after* the transition is performed
+    def after_transition(vehicle, transition)
+      Audit.log(vehicle, transition)
+    end
+  end
+
+For more information about the various behaviors added for ActiveRecord state
+machines, see StateMachine::Integrations::ActiveRecord.
+
+=== DataMapper
+
+Like the ActiveRecord integration, the DataMapper integration adds support for
+database transactions, automatically saving the record, named scopes, Extlib-like
+callbacks, validation errors, and observers.  For example,
+
+  class Vehicle
+    include DataMapper::Resource
+    
+    property :id, Serial
+    property :state, String
+    
+    state_machine :initial => :parked do
+      before_transition :parked => any - :parked, :do => :put_on_seatbelt
+      after_transition any => :parked do |transition|
+        self.seatbelt = 'off' # self is the record
+      end
+      around_transition :benchmark
+      
+      event :ignite do
+        transition :parked => :idling
+      end
+      
+      state :first_gear, :second_gear do
+        validates_presence_of :seatbelt_on
+      end
+    end
+    
+    def put_on_seatbelt
+      ...
+    end
+    
+    def benchmark
+      ...
+      yield
+      ...
+    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 *after* the transition is performed
+    after_transition do |transition|
+      Audit.log(self, transition) # self is the record
+    end
+    
+    around_transition do |transition, block|
+      # mark start time
+      block.call
+      # mark stop time
+    end
+    
+    # Generic callback after the transition fails to perform
+    after_transition_failure do |transition|
+      Audit.log(self, transition) # self is the record
+    end
+  end
+
+*Note* that the DataMapper::Observer integration is optional and only available
+when the dm-observer library is installed.
+
+For more information about the various behaviors added for DataMapper state
+machines, see StateMachine::Integrations::DataMapper.
+
+=== Mongoid
+
+The Mongoid integration adds support for automatically saving the record,
+basic scopes, validation errors, and observers.  For example,
+
+  class Vehicle
+    include Mongoid::Document
+    
+    state_machine :initial => :parked do
+      before_transition :parked => any - :parked, :do => :put_on_seatbelt
+      after_transition any => :parked do |vehicle, transition|
+        vehicle.seatbelt = 'off' # self is the record
+      end
+      around_transition :benchmark
+      
+      event :ignite do
+        transition :parked => :idling
+      end
+      
+      state :first_gear, :second_gear do
+        validates_presence_of :seatbelt_on
+      end
+    end
+    
+    def put_on_seatbelt
+      ...
+    end
+    
+    def benchmark
+      ...
+      yield
+      ...
+    end
+  end
+  
+  class VehicleObserver < Mongoid::Observer
+    # Callback for :ignite event *before* the transition is performed
+    def before_ignite(vehicle, transition)
+      # log message
+    end
+    
+    # Generic transition callback *after* the transition is performed
+    def after_transition(vehicle, transition)
+      Audit.log(vehicle, transition)
+    end
+  end
+
+For more information about the various behaviors added for Mongoid state
+machines, see StateMachine::Integrations::Mongoid.
+
+=== MongoMapper
+
+The MongoMapper integration adds support for automatically saving the record,
+basic scopes, validation errors and callbacks.  For example,
+
+  class Vehicle
+    include MongoMapper::Document
+    
+    state_machine :initial => :parked do
+      before_transition :parked => any - :parked, :do => :put_on_seatbelt
+      after_transition any => :parked do |vehicle, transition|
+        vehicle.seatbelt = 'off' # self is the record
+      end
+      around_transition :benchmark
+      
+      event :ignite do
+        transition :parked => :idling
+      end
+      
+      state :first_gear, :second_gear do
+        validates_presence_of :seatbelt_on
+      end
+    end
+    
+    def put_on_seatbelt
+      ...
+    end
+    
+    def benchmark
+      ...
+      yield
+      ...
+    end
+  end
+
+For more information about the various behaviors added for MongoMapper state
+machines, see StateMachine::Integrations::MongoMapper.
+
+=== Sequel
+
+Like the ActiveRecord integration, the Sequel integration adds support for
+database transactions, automatically saving the record, named scopes, validation
+errors and callbacks.  For example,
+
+  class Vehicle < Sequel::Model
+    state_machine :initial => :parked do
+      before_transition :parked => any - :parked, :do => :put_on_seatbelt
+      after_transition any => :parked do |transition|
+        self.seatbelt = 'off' # self is the record
+      end
+      around_transition :benchmark
+      
+      event :ignite do
+        transition :parked => :idling
+      end
+      
+      state :first_gear, :second_gear do
+        validates_presence_of :seatbelt_on
+      end
+    end
+    
+    def put_on_seatbelt
+      ...
+    end
+    
+    def benchmark
+      ...
+      yield
+      ...
+    end
+  end
+
+For more information about the various behaviors added for Sequel state
+machines, see StateMachine::Integrations::Sequel.
+
+== Compatibility
+
+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:
+
+  class Vehicle
+    state_machine :initial => :parked do
+      before_transition :from => :parked, :except_to => :parked, :do => :put_on_seatbelt
+      after_transition :to => :parked do |transition|
+        self.seatbelt = 'off' # self is the record
+      end
+      
+      event :ignite do
+        transition :from => :parked, :to => :idling
+      end
+    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.
+
+== 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 / orientation:
+
+  rake state_machine:draw FILE=vehicle.rb CLASS=Vehicle FORMAT=jpg ORIENTATION=landscape
+
+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 generated files will use an output filename of the format
+#{class_name}_#{machine_name}.#{format}.
+
+For examples of actual images generated using this task, see those under the
+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 CLASS=Vehicle
+
+If you are using this library as a gem in Rails 2.x, the following must be added
+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 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 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
+
+Test specific versions of integrations like so:
+
+  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
+
+== Caveats
+
+The following caveats should be noted when using state_machine:
+
+* DataMapper: Attribute-based event transitions are disabled when dm-validations 0.9.4 - 0.9.6 is in use
+* Overridden event methods won't get invoked when using attribute-based event transitions
+* around_transition callbacks in ORM integrations won't work on JRuby since it doesn't support continuations
+
+== Dependencies
+
+* Ruby 1.8.6 or later
+
+If using specific integrations:
+
+* ActiveModel[http://rubyonrails.org] integration: 3.0.0 or later
+* ActiveRecord[http://rubyonrails.org] integration: 2.0.0 or later
+* DataMapper[http://datamapper.org] integration: 0.9.4 or later
+* Mongoid[http://mongoid.org] integration: 2.0.0 or later
+* MongoMapper[http://mongomapper.com] integration: 0.5.5 or later
+* Sequel[http://sequel.rubyforge.org] integration: 2.8.0 or later
+
+If graphing state machine:
+
+* ruby-graphviz[http://github.com/glejeune/Ruby-Graphviz]: 0.9.0 or later