Class: Phronomy::Workflow::Builder

Inherits:
Object
  • Object
show all
Defined in:
lib/phronomy/workflow.rb

Overview

DSL builder for Phronomy::Workflow.define. Collects state/event/transition declarations and produces a WorkflowRunner.

Constant Summary collapse

FINISH = 
Phronomy::WorkflowRunner::FINISH

Instance Method Summary collapse

Constructor Details

#initialize(context_class) ⇒ Builder

Returns a new instance of Builder.



112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/phronomy/workflow.rb', line 112

def initialize(context_class)
  @context_class = context_class
  @initial = nil
  # { node_name => callable }
  @states = {}
  # Array of { from:, to: } — auto-transitions after a state action
  @after_transitions = []
  # Array of { name:, from:, to:, guard: } — event-driven transitions
  @event_transitions = []
  # Set of wait state names
  @wait_state_names = []
end

Instance Method Details

#after(from, to:) ⇒ Object

Declares an automatic transition that fires after a state's action completes.

Parameters:

  • from (Symbol) —

    source state name

  • to (Symbol) —

    destination state name or :finish



151
152
153
154
 
# File 'lib/phronomy/workflow.rb', line 151

def after(from, to:)
  dest = (to == :__finish__) ? FINISH : to
  @after_transitions << {from: from, to: dest}
end

#build ⇒ Object

Builds and returns a Phronomy::Workflow backed by a WorkflowRunner.



171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/phronomy/workflow.rb', line 171

def build
  nodes = @states.dup
  edges = build_edges
  conditional_edges = build_conditional_edges
  wait_states = build_wait_states

  runner = Phronomy::WorkflowRunner.new(
    state_class: @context_class,
    nodes: nodes,
    edges: edges,
    conditional_edges: conditional_edges,
    entry_point: @initial || nodes.keys.first,
    wait_states: wait_states
  )

  Workflow.new(runner)
end

#event(name, from:, to:, guard: nil) ⇒ Object

Declares an event-driven transition. When +guard:+ is provided, the transition is taken only if the guard returns truthy for the current context. Multiple events with the same name and source are evaluated in declaration order; the first passing guard wins.

Parameters:

  • name (Symbol) —

    event name

  • from (Symbol) —

    source state where this event can be fired

  • to (Symbol) —

    destination state or :finish

  • guard (Proc, nil) (defaults to: nil) —

    optional guard — receives context, returns truthy/falsy



165
166
167
168
 
# File 'lib/phronomy/workflow.rb', line 165

def event(name, from:, to:, guard: nil)
  dest = (to == :__finish__) ? FINISH : to
  @event_transitions << {name: name, from: from, to: dest, guard: guard}
end

#initial(state_name) ⇒ Object

Declares the initial (entry) state. rubocop:disable Style/TrivialAccessors

Parameters:

  • state_name (Symbol) 


128
129
130
 
# File 'lib/phronomy/workflow.rb', line 128

def initial(state_name)
  @initial = state_name
end

#state(name, action: nil) ⇒ Object

Declares an action state.

Parameters:

  • name (Symbol) —

    state name

  • action (#call, nil) (defaults to: nil) —

    callable invoked when entering the state. If nil, the state is treated as a no-op pass-through.



137
138
139
 
# File 'lib/phronomy/workflow.rb', line 137

def state(name, action: nil)
  @states[name] = action || ->(s) { s }
end

#wait_state(name) ⇒ Object

Declares a wait state that automatically halts execution when reached. No action is registered; the workflow pauses here until an event resumes it.

Parameters:

  • name (Symbol) —

    wait state name (conventionally :awaiting_something)



144
145
146
 
# File 'lib/phronomy/workflow.rb', line 144

def wait_state(name)
  @wait_state_names << name
end