state_machine 0.6.3 → 0.7.0

data/CHANGELOG.rdoc

@@ -1,6 +1,36 @@
 == master
 
-== 0.6.3 / 2008-03-10
+== 0.7.0 / 2009-04-03
+
+* 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

data/README.rdoc

@@ -45,6 +45,8 @@ Some brief, high-level features include:
 * State-driven instance / class behavior
 * State values of any data type
 * Dynamically-generated state values
+* Event parallelization
+* Attribute-based event transitions
 * Inheritance
 * Internationalization
 * GraphViz visualization creator
@@ -63,6 +65,7 @@ Below is an example of many of the features offered by this plugin, including:
 * Conditional transitions
 * State-driven instance behavior
 * Customized state values
+* Parallel events
 
 Class definition:
 
@@ -125,17 +128,17 @@ Class definition:
       end
     end
     
-    state_machine :hood_state, :initial => :closed, :namespace => 'hood' do
-      event :open do
-        transition all => :opened
+    state_machine :alarm_state, :initial => :active, :namespace => 'alarm' do
+      event :enable do
+        transition all => :active
       end
       
-      event :close do
-        transition all => :closed
+      event :disable do
+        transition all => :off
       end
       
-      state :opened, :value => 1
-      state :closed, :value => 0
+      state :active, :value => 1
+      state :off, :value => 0
     end
     
     def initialize
@@ -168,7 +171,9 @@ like so:
   vehicle.state_name              # => :parked
   vehicle.parked?                 # => true
   vehicle.can_ignite?             # => true
-  vehicle.next_ignite_transition  # => #<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>
+  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
@@ -189,21 +194,28 @@ like so:
   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)         # => true
-  vehicle.state?(:invalid)        # => ArgumentError: :invalid is an invalid name
+  vehicle.state?(:parked)         # => false
+  vehicle.state?(:invalid)        # => IndexError: :invalid is an invalid name
   
   # Namespaced machines have uniquely-generated methods
-  vehicle.hood_state              # => 0
-  vehicle.hood_state_name         # => :closed
+  vehicle.alarm_state             # => 1
+  vehicle.alarm_state_name        # => :active
   
-  vehicle.can_open_hood?          # => true
-  vehicle.open_hood               # => true
-  vehicle.hood_state              # => 1
-  vehicle.hood_state_name         # => :opened
-  vehicle.can_close_hood?         # => true
+  vehicle.can_disable_alarm?      # => true
+  vehicle.disable_alarm           # => true
+  vehicle.alarm_state             # => 0
+  vehicle.alarm_state_name        # => :off
+  vehicle.can_enable_alarm?       # => true
   
-  vehicle.hood_opened?            # => true
-  vehicle.hood_closed?            # => false
+  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
 
 *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.
@@ -307,8 +319,8 @@ callbacks, validation errors, and observers.  For example,
     end
     
     # Generic transition callback *before* the transition is performed
-    after_transition do |transition, saved|
-      Audit.log(self, transition) if saved # self is the record
+    after_transition do |transition|
+      Audit.log(self, transition) # self is the record
     end
   end
 

data/Rakefile

@@ -5,11 +5,11 @@ require 'rake/contrib/sshpublisher'
 
 spec = Gem::Specification.new do |s|
   s.name              = 'state_machine'
-  s.version           = '0.6.3'
+  s.version           = '0.7.0'
   s.platform          = Gem::Platform::RUBY
   s.summary           = 'Adds support for creating state machines for attributes on any Ruby class'
   
-  s.files             = FileList['{examples,lib,test}/**/*'] + %w(CHANGELOG.rdoc init.rb LICENSE Rakefile README.rdoc) - FileList['test/app_root/{log,log/*,script,script/*}']
+  s.files             = FileList['{examples,lib,tasks,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']

data/examples/merb-rest/controller.rb

@@ -0,0 +1,51 @@
+class Users < Application
+  # GET /users
+  def index
+    @users = User.all
+    display @users
+  end
+  
+  # GET /users/1
+  def show(id)
+    @user = User.get(id)
+    raise NotFound unless @user
+    display @user
+  end
+  
+  # GET /users/new
+  def new
+    only_provides :html
+    @user = User.new
+    display @user
+  end
+  
+  # GET /users/1/edit
+  def edit(id)
+    only_provides :html
+    @user = User.get(id)
+    raise NotFound unless @user
+    display @user
+  end
+  
+  # POST /users
+  def create(user)
+    @user = User.new(user)
+    if @user.save
+      redirect resource(@user), :message => {:notice => "User was successfully created"}
+    else
+      message[:error] = "User failed to be created"
+      render :new
+    end
+  end
+  
+  # PUT /users/1
+  def update(id, user)
+    @user = User.get(id)
+    raise NotFound unless @user
+    if @user.update_attributes(user)
+       redirect resource(@user)
+    else
+      display @user, :edit
+    end
+  end
+end

data/examples/merb-rest/model.rb

@@ -0,0 +1,28 @@
+class User
+  include DataMapper::Resource
+  
+  property :id, Serial
+  property :name, String
+  
+  validates_present :name, :state, :access_state
+  
+  state_machine :initial => :unregistered do
+    event :register do
+      transition :unregistered => :registered
+    end
+    
+    event :unregister do
+      transition :registered => :unregistered
+    end
+  end
+  
+  state_machine :access_state, :initial => :enabled do
+    event :enable do
+      transition all => :enabled
+    end
+    
+    event :disable do
+      transition all => :disabled
+    end
+  end
+end

data/examples/merb-rest/view_edit.html.erb

@@ -0,0 +1,24 @@
+<h1>Editing User</h1>
+
+<%= form_for @user, :action => resource(@user) do %>
+  <%= error_messages %>
+  
+  <p>
+    <%= text_field :name, :label => 'Name' %>
+  </p>
+  
+  <p>
+    <%= label :state %><br />
+    <%= select :state_event, :selected => @user.state_event.to_s, :collection => @user.state_transitions, :value_method => :event, :text_method => :to_name, :prompt => @user.state_name.to_s %>
+  </p>
+  
+  <p>
+    <%= label :access_state %><br />
+    <%= select :access_state_event, :selected => @user.access_state_event.to_s, :collection => @user.access_state_transitions, :value_method => :event, :text_method => :event, :prompt => "don't change" %>
+  </p>
+  
+  <p><%= submit 'Update' %></p>
+<% end =%>
+
+<%= link_to 'Show', resource(@user) %> |
+<%= link_to 'Back', resource(:users) %>

data/examples/merb-rest/view_index.html.erb

@@ -0,0 +1,23 @@
+<h1>Listing Users</h1>
+
+<table>
+  <tr>
+    <th>Name</th>
+    <th>State</th>
+    <th>Access State</th>
+  </tr>
+  
+<% @users.each do |user| %>
+  <tr>
+    <td><%=h user.name %></td>
+    <td><%=h user.state %></td>
+    <td><%=h user.access_state %></td>
+    <td><%= link_to 'Show', resource(user) %></td>
+    <td><%= link_to 'Edit', resource(user, :edit) %></td>
+  </tr>
+<% end %>
+</table>
+
+<br />
+
+<%= link_to 'New User', resource(:users, :new) %>

data/examples/merb-rest/view_new.html.erb

@@ -0,0 +1,13 @@
+<h1>New User</h1>
+
+<%= form_for @user, :action => resource(:users) do %>
+  <%= error_messages %>
+  
+  <p>
+    <%= text_field :name, :label => 'Name' %>
+  </p>
+  
+  <p><%= submit 'Create' %></p>
+<% end =%>
+
+<%= link_to 'Back', resource(:users) %>

data/examples/merb-rest/view_show.html.erb

@@ -0,0 +1,17 @@
+<p>
+  <b>Name:</b>
+  <%=h @user.name %>
+</p>
+
+<p>
+  <b>State:</b>
+  <%=h @user.state %>
+</p>
+
+<p>
+  <b>Access State:</b>
+  <%=h @user.access_state %>
+</p>
+
+<%= link_to 'Edit', resource(@user, :edit) %> |
+<%= link_to 'Back', resource(:users) %>

data/examples/rails-rest/controller.rb

@@ -0,0 +1,43 @@
+class UsersController < ApplicationController
+  # GET /users
+  def index
+    @users = User.all
+  end
+  
+  # GET /users/1
+  def show
+    @user = User.find(params[:id])
+  end
+  
+  # GET /users/new
+  def new
+    @user = User.new
+  end
+  
+  # GET /users/1/edit
+  def edit
+    @user = User.find(params[:id])
+  end
+  
+  # POST /users
+  def create
+    @user = User.new(params[:user])
+    
+    if @user.save
+      redirect_to(@user)
+    else
+      render :action => 'new'
+    end
+  end
+  
+  # PUT /users/1
+  def update
+    @user = User.find(params[:id])
+    
+    if @user.update_attributes(params[:user])
+      redirect_to(@user)
+    else
+      render :action => 'edit'
+    end
+  end
+end

data/examples/rails-rest/migration.rb

@@ -0,0 +1,11 @@
+class CreateUsers < ActiveRecord::Migration
+  def self.up
+    create_table :users do |t|
+      t.string :name, :state, :access_state
+    end
+  end
+  
+  def self.down
+    drop_table :users
+  end
+end

data/examples/rails-rest/model.rb

@@ -0,0 +1,23 @@
+class User < ActiveRecord::Base
+  validates_presence_of :name, :state, :access_state
+  
+  state_machine :initial => :unregistered do
+    event :register do
+      transition :unregistered => :registered
+    end
+    
+    event :unregister do
+      transition :registered => :unregistered
+    end
+  end
+  
+  state_machine :access_state, :initial => :enabled do
+    event :enable do
+      transition all => :enabled
+    end
+    
+    event :disable do
+      transition all => :disabled
+    end
+  end
+end

data/examples/rails-rest/view_edit.html.erb

@@ -0,0 +1,25 @@
+<h1>Editing User</h1>
+
+<% form_for(@user) do |f| %>
+  <%= f.error_messages %>
+  
+  <p>
+    <%= f.label :name %><br />
+    <%= f.text_field :name %>
+  </p>
+  
+  <p>
+    <%= f.label :state %><br />
+    <%= f.collection_select :state_event, @user.state_transitions, :event, :to_name, :include_blank => @user.state_name.to_s %>
+  </p>
+  
+  <p>
+    <%= f.label :access_state %><br />
+    <%= f.collection_select :access_state_event, @user.access_state_transitions, :event, :event, :include_blank => "don't change" %>
+  </p>
+  
+  <p><%= f.submit 'Update' %></p>
+<% end %>
+
+<%= link_to 'Show', @user %> |
+<%= link_to 'Back', users_path %>

data/examples/rails-rest/view_index.html.erb

@@ -0,0 +1,23 @@
+<h1>Listing Users</h1>
+
+<table>
+  <tr>
+    <th>Name</th>
+    <th>State</th>
+    <th>Access State</th>
+  </tr>
+  
+<% @users.each do |user| %>
+  <tr>
+    <td><%=h user.name %></td>
+    <td><%=h user.state %></td>
+    <td><%=h user.access_state %></td>
+    <td><%= link_to 'Show', user %></td>
+    <td><%= link_to 'Edit', edit_user_path(user) %></td>
+  </tr>
+<% end %>
+</table>
+
+<br />
+
+<%= link_to 'New User', new_user_path %>