lib/state_machine.rb in pluginaweek-state_machine-0.7.6 vs lib/state_machine.rb in pluginaweek-state_machine-0.8.0
- old
+ new
@@ -3,25 +3,23 @@
# A state machine is a model of behavior composed of states, events, and
# transitions. This helper adds support for defining this type of
# functionality on any Ruby class.
module StateMachine
module MacroMethods
- # Creates a new state machine for the given attribute. The default
- # attribute, if not specified, is <tt>:state</tt>.
+ # Creates a new state machine with the given name. The default name, if not
+ # specified, is <tt>:state</tt>.
#
# Configuration options:
+ # * <tt>:attribute</tt> - The name of the attribute to store the state value
+ # in. By default, this is the same as the name of the machine.
# * <tt>:initial</tt> - The initial state of the attribute. This can be a
# static state or a lambda block which will be evaluated at runtime
# (e.g. lambda {|vehicle| vehicle.speed == 0 ? :parked : :idling}).
# Default is nil.
# * <tt>:action</tt> - The instance method to invoke when an object
# transitions. Default is nil unless otherwise specified by the
# configured integration.
- # * <tt>:as</tt> - The name to use for prefixing all generated machine
- # instance / class methods (e.g. if the attribute is +state_id+, then
- # "state" would generate :state_name, :state_transitions, etc. instead of
- # :state_id_name and :state_id_transitions)
# * <tt>:namespace</tt> - The name to use for namespacing all generated
# state / event instance methods (e.g. "heater" would generate
# :turn_on_heater and :turn_off_heater for the :turn_on/:turn_off events).
# Default is nil.
# * <tt>:integration</tt> - The name of the integration to use for adding
@@ -47,32 +45,33 @@
# states, events and transitions for the state machine. *Note* that this
# block will be executed within the context of the state machine. As a
# result, you will not be able to access any class methods unless you refer
# to them directly (i.e. specifying the class name).
#
- # For examples on the types of configured state machines and blocks, see
+ # For examples on the types of state machine configurations and blocks, see
# the section below.
#
# == Examples
#
- # With the default attribute and no configuration:
+ # With the default name/attribute and no configuration:
#
# class Vehicle
# state_machine do
# event :park do
# ...
# end
# end
# end
#
- # The above example will define a state machine for the +state+ attribute
- # on the class. Every vehicle will start without an initial state.
+ # The above example will define a state machine named "state" that will
+ # store the value in the +state+ attribute. Every vehicle will start
+ # without an initial state.
#
- # With a custom attribute:
+ # With a custom name / attribute:
#
# class Vehicle
- # state_machine :status do
+ # state_machine :status, :attribute => :status_value do
# ...
# end
# end
#
# With a static initial state:
@@ -92,20 +91,24 @@
# end
#
# == Instance Methods
#
# The following instance methods will be automatically generated by the
- # state machine. Any existing methods will not be overwritten.
+ # state machine based on the *name* of the machine. Any existing methods
+ # will not be overwritten.
# * <tt>state</tt> - Gets the current value for the attribute
# * <tt>state=(value)</tt> - Sets the current value for the attribute
# * <tt>state?(name)</tt> - Checks the given state name against the current
# state. If the name is not a known state, then an ArgumentError is raised.
# * <tt>state_name</tt> - Gets the name of the state for the current value
# * <tt>state_events</tt> - Gets the list of events that can be fired on
# the current object's state (uses the *unqualified* event names)
- # * <tt>state_transitions</tt> - Gets the list of possible transitions
- # that can be made on the current object's state
+ # * <tt>state_transitions(requirements = {})</tt> - Gets the list of possible
+ # transitions that can be made on the current object's state. Additional
+ # requirements, such as the :from / :to state and :on event can be specified
+ # to restrict the transitions to select. By default, the current state
+ # will be used for the :from state.
#
# For example,
#
# class Vehicle
# state_machine :state, :initial => :parked do
@@ -251,11 +254,11 @@
#
# For example,
#
# class Vehicle
# include DataMapper::Resource
- # property :id, Integer, :serial => true
+ # property :id, Serial
#
# state_machine :initial => :parked do
# event :ignite do
# transition :parked => :idling
# end
@@ -293,59 +296,15 @@
# Within the +state_machine+ block, you can also define callbacks for
# transitions. For more information about defining these callbacks,
# see StateMachine::Machine#before_transition and
# StateMachine::Machine#after_transition.
#
- # == Attribute aliases
- #
- # When a state machine is defined, several methods are generated scoped by
- # the name of the attribute, such as (if the attribute were "state"):
- # * <tt>state_name</tt>
- # * <tt>state_event</tt>
- # * <tt>state_transitions</tt>
- # * etc.
- #
- # If the attribute for the machine were something less common, such as
- # "state_id" or "state_value", this makes for more awkward scoped methods.
- #
- # Rather than scope based on the attribute, these methods can be customized
- # using the <tt>:as</tt> option as essentially an alias.
- #
- # For example,
- #
- # class Vehicle
- # state_machine :state_id, :as => :state do
- # event :turn_on do
- # transition all => :on
- # end
- #
- # event :turn_off do
- # transition all => :off
- # end
- #
- # state :on, :value => 1
- # state :off, :value => 2
- # end
- # end
- #
- # ...will generate the following methods:
- # * <tt>state_name</tt>
- # * <tt>state_event</tt>
- # * <tt>state_transitions</tt>
- #
- # ...instead of:
- # * <tt>state_id_name</tt>
- # * <tt>state_id_event</tt>
- # * <tt>state_id_transitions</tt>
- #
- # However, it will continue to read and write to the +state_id+ attribute.
- #
# == Namespaces
#
# When a namespace is configured for a state machine, the name provided
# will be used in generating the instance methods for interacting with
- # events/states in the machine. This is particularly useful when a class
+ # states/events in the machine. This is particularly useful when a class
# has multiple state machines and it would be difficult to differentiate
# between the various states / events.
#
# For example,
#
@@ -396,11 +355,11 @@
#
# == Scopes
#
# For integrations that support it, a group of default scope filters will
# be automatically created for assisting in finding objects that have the
- # attribute set to the value for a given set of states.
+ # attribute set to one of a given set of states.
#
# For example,
#
# Vehicle.with_state(:parked) # => All vehicles where the state is parked
# Vehicle.with_states(:parked, :idling) # => All vehicles where the state is either parked or idling
@@ -410,12 +369,12 @@
#
# *Note* that if class methods already exist with those names (i.e.
# :with_state, :with_states, :without_state, or :without_states), then a
# scope will not be defined for that name.
#
- # See StateMachine::Machine for more information about using
- # integrations and the individual integration docs for information about
- # the actual scopes that are generated.
+ # See StateMachine::Machine for more information about using integrations
+ # and the individual integration docs for information about the actual
+ # scopes that are generated.
def state_machine(*args, &block)
StateMachine::Machine.find_or_create(self, *args, &block)
end
end
end