Class: StateMachine::State::TransitionDefinitionDSL

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

Instance Method Summary collapse

Constructor Details

#initialize(source_state, state_machine) {|state| ... } ⇒ StateMachine::State::TransitionDefinitionDSL

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Initializes a new object that provides methods for configuring state transitions.

See Base#when for an explanation how to use the DSL.

Parameters:

  • source_state (State) —

    The source state in which the transitions begin.

  • state_machine (StateMachine) —

    The state machine in which the transitions should be defined.

Yield Parameters:

See Also:

  • Base#when


124
125
126
127
128
 
# File 'lib/motion-state-machine/state.rb', line 124

def initialize(source_state, state_machine, &block)
  @state_machine = state_machine
  @state = source_state
  yield(self)
end

Instance Method Details

#die(options) ⇒ Array<StateMachine::Transition>

Defines a transition to a terminating state when a specified event happens. Works analog to #transition_to, but creates a terminating destination state automatically.

Returns:

  • (Array<StateMachine::Transition>) —

    an array of all transitions that are defined in the option array (e.g. two transitions if you define an :on and an :after option, but no :on_notification option).

See Also:

  • Base#when


230
231
232
233
234
235
236
237
238
239
240
241
242
243
 
# File 'lib/motion-state-machine/state.rb', line 230

def die(options)
  termination_states = @state_machine.states.select(&:terminating?)
  symbol = "terminated_#{termination_states.count}".to_sym

  termination_state = @state_machine.state symbol
  termination_state.terminating = true

  transitions = transition_to(symbol, options)
  event_texts = transitions.collect(&:event_log_text).join(" or ")
  termination_state.name =
    "terminated (internal state) #{event_texts}"

  transitions
end

#on_entry(&block) ⇒ Object

Defines a block that will be called without parameters when the source state is entered.

See Also:

  • Base#when


251
252
253
 
# File 'lib/motion-state-machine/state.rb', line 251

def on_entry(&block)
  @state.entry_actions << block
end

#on_exit(&block) ⇒ Object

Defines a block that will be called without parameters when the source state is exited.

See Also:

  • Base#when


261
262
263
 
# File 'lib/motion-state-machine/state.rb', line 261

def on_exit(&block)
  @state.exit_actions << block
end

#transition_to(destination_state_symbol, options) ⇒ Array<StateMachine::Transition>

Creates transitions to another state when defined events happen.

If multiple trigger events are defined, any of them will create its own Transition object.

You can specify guard blocks that can prevent a transition from happening.

Examples:

fsm.when :loading do |state|
   state.transition_to :displaying_data,
     on: :data_loaded,
     if: proc { data.valid? },
     action: proc { dismiss_loading_indicator }
end

Parameters:

  • options (Hash) —

    Configuration options for the transition.

Options Hash (options):

  • :on (Symbol) —

    Event symbol to trigger the transition via Base#event.

  • :on_notification (String) —

    NSNotification name that triggers the transition if posted via default NSNotificationCenter.

  • :after (Float) —

    Defines a timeout after which the transition occurs if the state is not left before. Given in seconds.

  • :if (Proc) — default: nil —

    Block that should return a Boolean. Return false in this block to prevent the transition from happening.

  • :unless (Proc) — default: nil —

    Block that should return a Boolean. Return true in this block to prevent the transition from happening.

  • :action (Proc) — default: nil —

    Block that is executed after exiting the source state and before entering the destination state. Will be called with the state machine as first parameter.

  • :internal (Boolean) — default: false —

    For a transition from a state to itself: If true, the transition does not call entry/exit actions on the state when executed.

Returns:

See Also:

  • Base#when


183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/motion-state-machine/state.rb', line 183

def transition_to(destination_state_symbol, options)
  unless destination_state_symbol.is_a? Symbol
    raise ArgumentError,
      "No destination state given "\
      "(got #{destination_state_symbol.inspect})"
  end

  options.merge! from: @state.symbol, to: destination_state_symbol

  defined_event_types = Transition.types.select do |type|
    !options[type].nil?
  end

  if defined_event_types.empty?
    raise ArgumentError,
      "No trigger event found in #{options}. "\
      "Valid trigger event keys: #{Transition.types}."
  end

  transitions = []

  defined_event_types.each do |type|
    event_trigger_value = options[type]
    if event_trigger_value
      options.merge! state_machine: @state_machine,
                     type: type
      transition = Transition.make options
      @state.register(transition)
      transitions << transition
    end
  end

  transitions
end