Class: Inquirex::Engine

Inherits:
Object
  • Object
show all
Defined in:
lib/inquirex/engine.rb,
lib/inquirex/engine/state_serializer.rb

Overview

Runtime session that drives flow navigation. Holds the definition, collected answers, and current position in the flow graph.

Collecting steps (ask, confirm): call engine.answer(value) Display steps (say, header, btw, warning): call engine.advance

Validates each answer via an optional Validation::Adapter, then advances using node transitions. Skips steps whose skip_if rule evaluates to true.

Defined Under Namespace

Modules: StateSerializer

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(definition, validator: Validation::NullAdapter.new) ⇒ Engine

Returns a new instance of Engine.

Parameters:

  • definition (Definition) —

    the flow to run

  • validator (Validation::Adapter) (defaults to: Validation::NullAdapter.new) —

    optional (default: NullAdapter)



17
18
19
20
21
22
23
24
25
26
 
# File 'lib/inquirex/engine.rb', line 17

def initialize(definition, validator: Validation::NullAdapter.new)
  @definition = definition
  @answers = {}
  @history = []
  @current_step_id = definition.start_step_id
  @validator = validator
  @totals = init_totals
  @history << @current_step_id
  skip_display_steps_if_needed
end

Instance Attribute Details

#answers ⇒ Object (readonly)

Returns the value of attribute answers.



13
14
15
 
# File 'lib/inquirex/engine.rb', line 13

def answers
  @answers
end

#current_step_id ⇒ Object (readonly)

Returns the value of attribute current_step_id.



13
14
15
 
# File 'lib/inquirex/engine.rb', line 13

def current_step_id
  @current_step_id
end

#definition ⇒ Object (readonly)

Returns the value of attribute definition.



13
14
15
 
# File 'lib/inquirex/engine.rb', line 13

def definition
  @definition
end

#history ⇒ Object (readonly)

Returns the value of attribute history.



13
14
15
 
# File 'lib/inquirex/engine.rb', line 13

def history
  @history
end

#totals ⇒ Object (readonly)

Returns the value of attribute totals.



13
14
15
 
# File 'lib/inquirex/engine.rb', line 13

def totals
  @totals
end

Class Method Details

.from_state(definition, state_hash, validator: Validation::NullAdapter.new) ⇒ Engine

Rebuilds an Engine from a previously saved state.

Parameters:

  • definition (Definition) —

    same definition used when state was captured

  • state_hash (Hash) —

    hash with state keys (may be strings from JSON)

  • validator (Validation::Adapter) (defaults to: Validation::NullAdapter.new)

Returns:



95
96
97
98
99
100
 
# File 'lib/inquirex/engine.rb', line 95

def self.from_state(definition, state_hash, validator: Validation::NullAdapter.new)
  state = StateSerializer.symbolize_state(state_hash)
  engine = allocate
  engine.send(:restore_state, definition, state, validator)
  engine
end

Instance Method Details

#advance ⇒ Object

Advances past the current non-collecting step (say/header/btw/warning).

Raises:



71
72
73
74
75
 
# File 'lib/inquirex/engine.rb', line 71

def advance
  raise Errors::AlreadyFinishedError, "Flow is already finished" if finished?

  advance_step
end

#answer(value) ⇒ Object

Submits an answer for the current collecting step (ask/confirm). Validates, stores, and advances to the next step.

Parameters:

  • value (Object) —

    user’s answer for the current step

Raises:



55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/inquirex/engine.rb', line 55

def answer(value)
  raise Errors::AlreadyFinishedError, "Flow is already finished" if finished?
  raise Errors::NonCollectingStepError, "Step #{@current_step_id} is a display step; use #advance instead" \
    unless current_step.collecting?

  result = @validator.validate(current_step, value)
  raise Errors::ValidationError, "Validation failed: #{result.errors.join(", ")}" unless result.valid?

  @answers[@current_step_id] = value
  apply_accumulations(current_step, value)
  advance_step
end

#current_step ⇒ Node?

Returns current step node, or nil if flow is finished.

Returns:

  • (Node, nil) —

    current step node, or nil if flow is finished



37
38
39
40
41
 
# File 'lib/inquirex/engine.rb', line 37

def current_step
  return nil if finished?

  @definition.step(@current_step_id)
end

#finished? ⇒ Boolean

Returns true when there is no current step (flow ended).

Returns:

  • (Boolean) —

    true when there is no current step (flow ended)



44
45
46
 
# File 'lib/inquirex/engine.rb', line 44

def finished?
  @current_step_id.nil?
end

#to_state ⇒ Hash

Serializable state snapshot for persistence or resumption.

Returns:

  • (Hash) 


80
81
82
83
84
85
86
87
 
# File 'lib/inquirex/engine.rb', line 80

def to_state
  {
    current_step_id: @current_step_id,
    answers:         @answers,
    history:         @history,
    totals:          @totals
  }
end

#total(name) ⇒ Numeric

Convenience accessor for a single accumulator’s running total.

Parameters:

  • name (Symbol) —

    accumulator name (e.g. :price)

Returns:

  • (Numeric) 


32
33
34
 
# File 'lib/inquirex/engine.rb', line 32

def total(name)
  @totals[name.to_sym] || 0
end