Class: StateMachine::Transition Abstract

Inherits:
Object
  • Object
show all
Defined in:
lib/motion-state-machine/transition.rb

Overview

This class is abstract.

Subclass and override #event_description, #arm and #unarm to implement a custom Transition class.

Constant Summary collapse

@@types_to_subclasses = 
{}

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options) ⇒ Transition

Note:

This method should not be used directly. To create Transition objects, use #make instead.

Initializes a new StateMachine::Transition between two given states.

Additionally, you must also supply an event trigger value as option. Its key must be equal to the transition class’s event_type., ex. if event_type is :on, you have to supply the event value using the option key :on.

Parameters:

  • options (Hash) —

    Configuration options for the transition.

Options Hash (options):

  • :state_machine (StateMachine::Base) —

    State machine that the transition belongs to.

  • :from (Symbol) —

    State where the transition begins.

  • :to (Symbol) —

    State where the transition ends.

  • :if (Proc) — default: nil —

    Block that should return a Boolean. If the block returns false, the transition will be blocked and not executed (optional).

  • :unless (Proc) — default: nil —

    Block that should return a Boolean. If the block returns true, the transition will be blocked and not executed (optional).

  • :internal (Boolean) — default: false —

    If set to true, the transition will not leave it’s source state: Entry and Exit actions will not be called in this case. For internal transitions, :from and :to must be the same (optional).



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/motion-state-machine/transition.rb', line 98

def initialize(options)
  @options = options.dup
  @state_machine = @options.delete :state_machine
  @source_state = @state_machine.state options[:from]
  @destination_state = @state_machine.state options[:to]

  event_type = self.class.event_type
  if event_type.nil?
    raise RuntimeError, "#{self.class} has no defined event type."
  end

  [:from, :to].each do |symbol|
    unless options[symbol].is_a?(Symbol)
      raise ":#{symbol} option must be given as symbol."
    end
  end

  @event_trigger_value = options[event_type]
  if @event_trigger_value.nil?
    raise ArgumentError, "You must supply an event trigger value."
  end

  if options[:internal] && options[:from] != options[:to]
    raise ArgumentError,
      "Internal states must have same source and destination state."
  end
end

Class Attribute Details

.event_type ⇒ Symbol

Returns Metaclass attribute, contains the key that is used for generating the specific transition via #make.

Returns:

  • (Symbol) —

    Metaclass attribute, contains the key that is used for generating the specific transition via #make.



31
32
33
 
# File 'lib/motion-state-machine/transition.rb', line 31

def event_type
  @event_type
end

Instance Attribute Details

#destination_state ⇒ State (readonly)

Returns the state that the transition leads to.

Returns:

  • (State) —

    the state that the transition leads to.



21
22
23
 
# File 'lib/motion-state-machine/transition.rb', line 21

def destination_state
  @destination_state
end

#event_trigger_value ⇒ Object (readonly)

Returns a more specific object that triggers the transition.

Returns:

  • (Object) —

    a more specific object that triggers the transition.



25
26
27
 
# File 'lib/motion-state-machine/transition.rb', line 25

def event_trigger_value
  @event_trigger_value
end

#options ⇒ Hash (readonly)

Returns configuration options of the transition.

Returns:

  • (Hash) —

    configuration options of the transition.



12
13
14
 
# File 'lib/motion-state-machine/transition.rb', line 12

def options
  @options
end

#source_state ⇒ State (readonly)

Returns the state from which the transition starts.

Returns:

  • (State) —

    the state from which the transition starts.



18
19
20
 
# File 'lib/motion-state-machine/transition.rb', line 18

def source_state
  @source_state
end

#state_machine ⇒ Base (readonly)

Returns the state machine that this transition belongs to.

Returns:

  • (Base) —

    the state machine that this transition belongs to.



15
16
17
 
# File 'lib/motion-state-machine/transition.rb', line 15

def state_machine
  @state_machine
end

Class Method Details

.make(options) ⇒ Transition

Creates a new StateMachine::Transition object with the given options. The returned object’s subclass is determined by the :type option.

See #initialize for all possible options.

Examples:

StateMachine::Transition.make type: :to, ... # => #<StateMachine::Transition:...>

Parameters:

  • options (Hash) —

    Configuration options for the transition.

Options Hash (options):

  • :type (Symbol) —

    Type identifier for the transition, ex. :on, :after, :on_notification.

Returns:

  • (Transition) —

    a new object with the class that fits the given :type option.



56
57
58
59
 
# File 'lib/motion-state-machine/transition.rb', line 56

def self.make(options)
  klass = @@types_to_subclasses[options[:type]]
  klass.new options
end

.types ⇒ Array<Class<Transition>>

Returns a list of all registered transition subclasses.

Returns:

  • (Array<Class<Transition>>) —

    a list of all registered transition subclasses



38
39
40
 
# File 'lib/motion-state-machine/transition.rb', line 38

def self.types
  @@types_to_subclasses.keys
end

Instance Method Details

#allowed? ⇒ Boolean

Returns Asks the guard blocks given for :if and :unless if the transition is allowed. Returns true if the transition is allowed to be executed.

Returns:

  • (Boolean) —

    Asks the guard blocks given for :if and :unless if the transition is allowed. Returns true if the transition is allowed to be executed.



131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/motion-state-machine/transition.rb', line 131

def allowed?
  if_guard = options[:if]
  unless if_guard.nil?
    return false unless if_guard.call(@state_machine)
  end
  unless_guard = options[:unless]
  unless unless_guard.nil?
    return false if unless_guard.call(@state_machine)
  end
  true
end

#event_description ⇒ String

Returns a short description of the event. Used for debug output.

Returns:

  • (String) —

    a short description of the event. Used for debug output.



147
148
149
150
 
# File 'lib/motion-state-machine/transition.rb', line 147

def event_description
  # Implement this in a subclass.
  "after unclassified event"
end

#inspect ⇒ Object 



153
154
155
156
 
# File 'lib/motion-state-machine/transition.rb', line 153

def inspect
  "#<#{self.class.name}:0x#{object_id.to_s(16)} "\
  "#{event_description} @options=#{options.inspect}>"
end