Class: StateMachines::Branch

Inherits:
Object
  • Object
show all
Includes:
EvalHelpers
Defined in:
lib/state_machines/branch.rb

Overview

Represents a set of requirements that must be met in order for a transition or callback to occur. Branches verify that the event, from state, and to state of the transition match, in addition to if/unless conditionals for an object’s state.

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from EvalHelpers

#evaluate_method

Constructor Details

#initialize(options = {}) ⇒ Branch

Creates a new branch



32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/state_machines/branch.rb', line 32

def initialize(options = {}) #:nodoc:
  # Build conditionals
  @if_condition = options.delete(:if)
  @unless_condition = options.delete(:unless)

  # Build event requirement
  @event_requirement = build_matcher(options, :on, :except_on)

  if (options.keys - [:from, :to, :on, :except_from, :except_to, :except_on]).empty?
    # Explicit from/to requirements specified
    @state_requirements = [{from: build_matcher(options, :from, :except_from), to: build_matcher(options, :to, :except_to)}]
  else
    # Separate out the event requirement
    options.delete(:on)
    options.delete(:except_on)

    # Implicit from/to requirements specified
    @state_requirements = options.collect do |from, to|
      from = WhitelistMatcher.new(from) unless from.is_a?(Matcher)
      to = WhitelistMatcher.new(to) unless to.is_a?(Matcher)
      {from: from, to: to}
    end
  end

  # Track known states.  The order that requirements are iterated is based
  # on the priority in which tracked states should be added.
  @known_states = []
  @state_requirements.each do |state_requirement|
    [:from, :to].each { |option| @known_states |= state_requirement[option].values }
  end
end

Instance Attribute Details

#event_requirement ⇒ Object (readonly)

The requirement for verifying the event being matched



19
20
21
 
# File 'lib/state_machines/branch.rb', line 19

def event_requirement
  @event_requirement
end

#if_condition ⇒ Object (readonly)

The condition that must be met on an object



13
14
15
 
# File 'lib/state_machines/branch.rb', line 13

def if_condition
  @if_condition
end

#known_states ⇒ Object (readonly)

A list of all of the states known to this branch. This will pull states from the following options (in the same order):

  • from / except_from

  • to / except_to



29
30
31
 
# File 'lib/state_machines/branch.rb', line 29

def known_states
  @known_states
end

#state_requirements ⇒ Object (readonly)

One or more requirements for verifying the states being matched. All requirements contain a mapping of => matcher, :to => matcher.



23
24
25
 
# File 'lib/state_machines/branch.rb', line 23

def state_requirements
  @state_requirements
end

#unless_condition ⇒ Object (readonly)

The condition that must not be met on an object



16
17
18
 
# File 'lib/state_machines/branch.rb', line 16

def unless_condition
  @unless_condition
end

Instance Method Details

#draw(graph, event, valid_states, io = $stdout) ⇒ Object 



124
125
126
 
# File 'lib/state_machines/branch.rb', line 124

def draw(graph, event, valid_states, io = $stdout)
  machine.renderer.draw_branch(self, graph, event, valid_states, io)
end

#match(object, query = {}) ⇒ Object

Attempts to match the given object / query against the set of requirements configured for this branch. In addition to matching the event, from state, and to state, this will also check whether the configured :if/:unless conditions pass on the given object.

If a match is found, then the event/state requirements that the query passed successfully will be returned. Otherwise, nil is returned if there was no match.

Query options:

  • :from - One or more states being transitioned from. If none are specified, then this will always match.

  • :to - One or more states being transitioned to. If none are specified, then this will always match.

  • :on - One or more events that fired the transition. If none are specified, then this will always match.

  • :guard - Whether to guard matches with the if/unless conditionals defined for this branch. Default is true.

Examples

branch = StateMachines::Branch.new(:parked => :idling, :on => :ignite)

branch.match(object, :on => :ignite)  # => {:to => ..., :from => ..., :on => ...}
branch.match(object, :on => :park)    # => nil



116
117
118
119
120
121
122
 
# File 'lib/state_machines/branch.rb', line 116

def match(object, query = {})
  query.assert_valid_keys(:from, :to, :on, :guard)

  if (match = match_query(query)) && matches_conditions?(object, query)
    match
  end
end

#matches?(object, query = {}) ⇒ Boolean

Determines whether the given object / query matches the requirements configured for this branch. In addition to matching the event, from state, and to state, this will also check whether the configured :if/:unless conditions pass on the given object.

Examples

branch = StateMachines::Branch.new(:parked => :idling, :on => :ignite)

# Successful
branch.matches?(object, :on => :ignite)                                   # => true
branch.matches?(object, :from => nil)                                     # => true
branch.matches?(object, :from => :parked)                                 # => true
branch.matches?(object, :to => :idling)                                   # => true
branch.matches?(object, :from => :parked, :to => :idling)                 # => true
branch.matches?(object, :on => :ignite, :from => :parked, :to => :idling) # => true

# Unsuccessful
branch.matches?(object, :on => :park)                                     # => false
branch.matches?(object, :from => :idling)                                 # => false
branch.matches?(object, :to => :first_gear)                               # => false
branch.matches?(object, :from => :parked, :to => :first_gear)             # => false
branch.matches?(object, :on => :park, :from => :parked, :to => :idling)   # => false

Returns:

  • (Boolean) 


87
88
89
 
# File 'lib/state_machines/branch.rb', line 87

def matches?(object, query = {})
  !match(object, query).nil?
end