class StateMachine::State::TransitionDefinitionDSL

Public Class Methods

new(source_state, state_machine) { |self| ... } click to toggle source

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

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

@param [State] source_state

The source state in which the transitions begin.

@param [StateMachine] state_machine

The state machine in which the transitions should be defined.

@yieldparam [TransitionDefinitionDSL] state

The DSL object. Call methods on this object to define
transitions.

@return [StateMachine::State::TransitionDefinitionDSL]

the initialized object.

@api private @see Base#when

# 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

Public Instance Methods

die(options) click to toggle source

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

@return [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 Base#when

# 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) click to toggle source

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

@see Base#when

# File lib/motion-state-machine/state.rb, line 251
def on_entry(&block)
  @state.entry_actions << block
end
on_exit(&block) click to toggle source

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

@see Base#when

# File lib/motion-state-machine/state.rb, line 261
def on_exit(&block)
  @state.exit_actions << block
end
transition_to(destination_state_symbol, options) click to toggle source

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.

@param options [Hash]

Configuration options for the transition.

@option options [Symbol] :on

Event symbol to trigger the transition via {Base#event}.

@option options [String] :on_notification

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

@option options [Float] :after

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

@option options [Proc] :if (nil)

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

@option options [Proc] :unless (nil)

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

@option options [Proc] :action (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.

@option options [Boolean] :internal (false)

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

@example

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

@return [Array<StateMachine::Transition>] an array of all

created transitions.

@see Base#when

# 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