Coverage Summary for Class: SolutionIterator (it.unibo.tuprolog.argumentation.core.engine)

 // Forked from 2p-kt's solve-prolog 3.0.2 (Apache License 2.0): see README.md in this package
 package it.unibo.tuprolog.argumentation.core.engine
 
 import it.unibo.tuprolog.argumentation.core.engine.fsm.State
 import it.unibo.tuprolog.argumentation.core.engine.impl.SimpleSolutionIterator
 import it.unibo.tuprolog.solve.Solution
 import kotlin.js.JsName
 import kotlin.jvm.JvmStatic
 
 /**
  * Drives the `:solve-prolog` finite-state machine, one [State.next] step at a time, and turns every visited
  * end-state (see [it.unibo.tuprolog.argumentation.core.engine.fsm.EndState]) into an emitted [Solution].
  *
  * This is the piece [AbstractPrologSolver.solveImpl] wraps into a lazy [Sequence]: [hasNext] answers whether
  * the current [state] is (or can, via backtracking, resume being) an end-state, and [next] steps the machine
  * forward until it reaches one, returning its [it.unibo.tuprolog.argumentation.core.engine.fsm.EndState.solution]. Because
  * this is a genuine [Iterator] over an explicit state value rather than host-language recursion, resolution can
  * be driven incrementally -- one solution, or even one FSM transition, at a time -- without unwinding a call
  * stack, and [onStateTransition] gives a hook to observe (e.g. log, trace, or count) every step as it happens.
  *
  * tuProlog's classic solver also has a `MutableSolutionIterator`, which can additionally *hijack* which state comes
  * next.
  */
 interface SolutionIterator : Iterator<Solution> {
     /** The state the machine is currently in (before the next call to [next] advances it). */
     @JsName("state")
     val state: State
 
     /** How many transitions the underlying state machine has performed so far. */
     @JsName("step")
     val step: Long
 
     override fun hasNext(): Boolean
 
     override fun next(): Solution
 
     /** Invoked after every transition from [source] to [destination] (the `index`-th transition overall). */
     @JsName("onStateTransition")
     fun onStateTransition(
         source: State,
         destination: State,
         index: Long,
     )
 
     companion object {
         /**
          * Creates a plain [SolutionIterator] that starts from [initialState] and reports every transition to
          * [onStateTransition] (a no-op by default).
          */
         @JsName("of")
         @JvmStatic
         fun of(
             initialState: State,
             onStateTransition: (State, State, Long) -> Unit = { _, _, _ -> },
         ): SolutionIterator = SimpleSolutionIterator(initialState, onStateTransition)
     }
 }