From 55bbbad7c7053fc5c9c79fc035e0e7ed91560f97 Mon Sep 17 00:00:00 2001 From: Nestor Ovroy Date: Sun, 17 Jan 2010 22:26:07 +0000 Subject: [PATCH] Partial Documentation for ActiveModel::StateMachine based on: http://blog.envylabs.com/2009/08/the-rails-state-machine/ --- activemodel/lib/active_model/state_machine.rb | 109 +++++++++++++++++++++++++ 1 files changed, 109 insertions(+), 0 deletions(-) diff --git a/activemodel/lib/active_model/state_machine.rb b/activemodel/lib/active_model/state_machine.rb index 527794b..0399fef 100644 --- a/activemodel/lib/active_model/state_machine.rb +++ b/activemodel/lib/active_model/state_machine.rb @@ -1,4 +1,113 @@ module ActiveModel + # ==== Examples + # + # class TrafficLight + # include ActiveModel::StateMachine + # + # state_machine do + # state :red + # state :green + # state :yellow + # state :blink + # + # event :change_color do + # transitions :to => :red, :from => [:yellow], + # :on_transition => :catch_runners + # transitions :to => :green, :from => [:red] + # transitions :to => :yellow, :from => [:green] + # end + # + # event :defect do + # transitions :to => :blink, :from => [:yellow, :red, :green] + # end + # + # event :repair do + # transitions :to => :red, :from => [:blink] + # end + # end + # + # def catch_runners + # puts "That'll be $250." + # end + # end + # + # light = TrafficLight.new + # light.current_state # => :red + # light.change_color # => true + # light.current_state # => :green + # light.green? # => true + # light.change_color! # => true + # light.current_state # => :yellow + # light.red? # => false + # light.change_color # => true + # "That'll be $250." + # + # + # * The initial state for TrafficLight is red which is the first state defined. + # + # # Want to know the initial_state? + # TrafficLight.state_machine.initial_state # => :red + # + # * On a succesful transition to red (from yellow), the local +catch_runners+ + # method is executed + # + # * The object acts differently depending on its current state, for instance, + # the change_color! method has a different action depending on the current + # color of the light + # + # * Get the possible events for a state + # + # TrafficLight.state_machine.events_for(:red) # => [:change_color, :defect] + # TrafficLight.state_machine.events_for(:blink) # => [:repair] + # + # + # The StateMachine also supports the following features : + # + # * Success callbacks on event transition + # + # event :sample, :success => :we_win do + # ... + # end + # + # * Enter and exit callbacks par state + # + # state :open, :enter => [:alert_twitter, :send_emails], :exit => :alert_twitter + # + # * Guards on transition + # + # event :close do + # # You may only close the store if the safe is locked!! + # transitions :to => :closed, :from => :open, :guard => :safe_locked? + # end + # + # * Setting the initial state + # + # state_machine :initial => :yellow do + # ... + # end + # + # * Named the state machine, to have more than one + # + # class Stated + # include ActiveModel::StateMachine + # + # strate_machine :name => :ontest do + # end + # + # state_machine do + # end + # end + # + # # Get the state of the :ontest state machine + # stat.current_state(:ontest) + # # Get the initial state + # Stated.state_machine(:ontest).initial_state + # + # * Changing the state + # + # stat.current_state(:default, :astate) # => :astate + # # But you must give the name of the state machine, here :default + # module StateMachine autoload :Event, 'active_model/state_machine/event' autoload :Machine, 'active_model/state_machine/machine' -- 1.6.6