lib/state_machine.rb in state_machine-0.9.4 vs lib/state_machine.rb in state_machine-0.10.0

- old
+ new

@@ -13,10 +13,12 @@ # 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>:initialize</tt> - Whether to automatically initialize the attribute + # by hooking into #initialize on the owner class. Default is true. # * <tt>:action</tt> - The instance method to invoke when an object # transitions. Default is nil unless otherwise specified by the # configured integration. # * <tt>:namespace</tt> - The name to use for namespacing all generated # state / event instance methods (e.g. "heater" would generate @@ -26,14 +28,13 @@ # library-specific behavior to the machine. Built-in integrations # include :active_model, :active_record, :data_mapper, :mongo_mapper, and # :sequel. By default, this is determined automatically. # # Configuration options relevant to ORM integrations: - # * <tt>:plural</tt> - The pluralized name of the attribute. By default, - # this will attempt to call +pluralize+ on the attribute. If this - # method is not available, an "s" is appended. This is used for - # generating scopes. + # * <tt>:plural</tt> - The pluralized version of the name. By default, this + # will attempt to call +pluralize+ on the name. If this method is not + # available, an "s" is appended. This is used for generating scopes. # * <tt>:messages</tt> - The error messages to use when invalidating # objects due to failed transitions. Messages include: # * <tt>:invalid</tt> # * <tt>:invalid_event</tt> # * <tt>:invalid_transition</tt> @@ -131,18 +132,30 @@ # * <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>human_state_name</tt> - Gets the human-readable 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(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. + # * <tt>state_events(requirements = {})</tt> - Gets the list of events that + # can be fired on the current object's state (uses the *unqualified* event + # names) + # * <tt>state_transitions(requirements = {})</tt> - Gets the list of + # transitions that can be made on the current object's state + # * <tt>state_paths(requirements = {})</tt> - Gets the list of sequences of + # transitions that can be run from the current object's state # + # The <tt>state_events</tt>, <tt>state_transitions</tt>, and <tt>state_paths</tt> + # helpers all take an optional set of requirements for determining what's + # available for the current object. These requirements include: + # * <tt>:from</tt> - One or more states to transition from. If none are + # specified, then this will be the object's current state. + # * <tt>:to</tt> - One or more states to transition to. If none are + # specified, then this will match any to state. + # * <tt>:on</tt> - One or more events to transition on. If none are + # specified, then this will match any event. + # * <tt>:guard</tt> - Whether to guard transitions with the if/unless + # conditionals defined for each one. Default is true. + # # For example, # # class Vehicle # state_machine :state, :initial => :parked do # event :ignite do @@ -154,29 +167,43 @@ # end # end # end # # vehicle = Vehicle.new - # vehicle.state # => "parked" - # vehicle.state_name # => :parked - # vehicle.human_state_name # => "parked" - # vehicle.state?(:parked) # => true + # vehicle.state # => "parked" + # vehicle.state_name # => :parked + # vehicle.human_state_name # => "parked" + # vehicle.state?(:parked) # => true # # # Changing state # vehicle.state = 'idling' - # vehicle.state # => "idling" - # vehicle.state_name # => :idling - # vehicle.state?(:parked) # => false + # vehicle.state # => "idling" + # vehicle.state_name # => :idling + # vehicle.state?(:parked) # => false # # # Getting current event / transition availability - # vehicle.state_events # => [:park] - # vehicle.park # => true - # vehicle.state_events # => [:ignite] + # vehicle.state_events # => [:park] + # vehicle.park # => true + # vehicle.state_events # => [:ignite] + # vehicle.state_events(:from => :idling) # => [:park] + # vehicle.state_events(:to => :parked) # => [] # - # vehicle.state_transitions # => [#<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>] + # vehicle.state_transitions # => [#<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>] # vehicle.ignite - # vehicle.state_transitions # => [#<StateMachine::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>] + # vehicle.state_transitions # => [#<StateMachine::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>] + # + # vehicle.state_transitions(:on => :ignite) # => [] + # + # # Getting current path availability + # vehicle.state_paths # => [ + # # [#<StateMachine::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>, + # # #<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>] + # # ] + # vehicle.state_paths(:guard => false) # => + # # [#<StateMachine::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>, + # # #<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>] + # # ] # # == Attribute initialization # # For most classes, the initial values for state machine attributes are # automatically assigned when a new object is created. However, this @@ -328,10 +355,10 @@ # == Defining callbacks # # Within the +state_machine+ block, you can also define callbacks for # transitions. For more information about defining these callbacks, # see StateMachine::Machine#before_transition, StateMachine::Machine#after_transition, - # and StateMachine::Machine#around_transition. + # and StateMachine::Machine#around_transition, and StateMachine::Machine#after_failure. # # == Namespaces # # When a namespace is configured for a state machine, the name provided # will be used in generating the instance methods for interacting with