Add argument passing to start() and startFrom() methods

Initial states are triggered on machine start so they could not receive
argments through processEvent() method.

Author: nsk90

kstatemachine/src/main/kotlin/ru/nsk/kstatemachine/BaseStateImpl.kt

@@ -147,26 +147,27 @@ open class BaseStateImpl(override val name: String?, override val childMode: Chi
         return resolvedTransitions.singleOrNull()
     }
 
-    override fun recursiveEnterInitialStates() {
+    override fun recursiveEnterInitialStates(argument: Any?) {
         if (states.isEmpty()) return
 
         when (childMode) {
             ChildMode.EXCLUSIVE -> {
-                val initialState =
-                    checkNotNull(initialState) { "Initial state is not set, call setInitialState() first" }
-                setCurrentState(initialState, makeStartTransitionParams(initialState))
-                initialState.recursiveEnterInitialStates()
+                val initialState = checkNotNull(initialState) {
+                    "Initial state is not set, call setInitialState() first"
+                }
+                setCurrentState(initialState, makeStartTransitionParams(initialState, argument = argument))
+                initialState.recursiveEnterInitialStates(argument)
             }
             ChildMode.PARALLEL -> data.states.forEach {
-                notifyStateEntry(it, makeStartTransitionParams(it))
-                it.recursiveEnterInitialStates()
+                notifyStateEntry(it, makeStartTransitionParams(it, argument = argument))
+                it.recursiveEnterInitialStates(argument)
             }
         }
     }
 
     override fun recursiveEnterStatePath(path: MutableList<InternalState>, transitionParams: TransitionParams<*>) {
         if (path.isEmpty()) {
-            recursiveEnterInitialStates()
+            recursiveEnterInitialStates(transitionParams.argument)
         } else {
             val state = path.removeLast()
             setCurrentState(state, transitionParams)
@@ -251,7 +252,8 @@ open class BaseStateImpl(override val name: String?, override val childMode: Chi
 
     internal fun makeStartTransitionParams(
         sourceState: IState,
-        targetState: IState = sourceState
+        targetState: IState = sourceState,
+        argument: Any?
     ): TransitionParams<*> {
         val transition = DefaultTransition(
             "Starting",
@@ -264,6 +266,7 @@ open class BaseStateImpl(override val name: String?, override val childMode: Chi
             transition,
             transition.produceTargetStateDirection(TransitionDirectionProducerPolicy.DefaultPolicy(StartEvent)),
             StartEvent,
+            argument,
         )
     }
 }

kstatemachine/src/main/kotlin/ru/nsk/kstatemachine/InternalState.kt

@@ -18,7 +18,7 @@ abstract class InternalState : IState {
     internal abstract fun afterChildFinished(finishedChild: InternalState, transitionParams: TransitionParams<*>)
 
     internal abstract fun <E : Event> recursiveFindUniqueResolvedTransition(event: E): ResolvedTransition<E>?
-    internal abstract fun recursiveEnterInitialStates()
+    internal abstract fun recursiveEnterInitialStates(argument: Any?)
     internal abstract fun recursiveEnterStatePath(
         path: MutableList<InternalState>,
         transitionParams: TransitionParams<*>

kstatemachine/src/main/kotlin/ru/nsk/kstatemachine/StateMachine.kt

@@ -38,7 +38,7 @@ interface StateMachine : State {
     /**
      * Starts state machine
      */
-    fun start()
+    fun start(argument: Any? = null)
 
     /**
      * Forces state machine to stop

kstatemachine/src/main/kotlin/ru/nsk/kstatemachine/StateMachineImpl.kt

@@ -7,7 +7,7 @@ import ru.nsk.kstatemachine.visitors.CleanupVisitor
  * Defines state machine API for internal library usage.
  */
 abstract class InternalStateMachine(name: String?, childMode: ChildMode) : StateMachine, DefaultState(name, childMode) {
-    internal abstract fun startFrom(state: IState)
+    internal abstract fun startFrom(state: IState, argument: Any?)
     internal abstract fun delayListenerException(exception: Exception)
 }
 
@@ -57,21 +57,21 @@ internal class StateMachineImpl(name: String?, childMode: ChildMode, override va
         _machineListeners.remove(listener)
     }
 
-    override fun start() {
+    override fun start(argument: Any?) {
         accept(CheckUniqueNamesVisitor())
         checkBeforeRunMachine()
 
         runCheckingExceptions {
-            runMachine(makeStartTransitionParams(this))
-            recursiveEnterInitialStates()
+            runMachine(makeStartTransitionParams(this, argument = argument))
+            recursiveEnterInitialStates(argument)
         }
     }
 
-    override fun startFrom(state: IState) {
+    override fun startFrom(state: IState, argument: Any?) {
         checkBeforeRunMachine()
 
         runCheckingExceptions {
-            val transitionParams = makeStartTransitionParams(this, state)
+            val transitionParams = makeStartTransitionParams(this, state, argument)
             runMachine(transitionParams)
             switchToTargetState(state as InternalState, this, transitionParams)
         }

kstatemachine/src/main/kotlin/ru/nsk/kstatemachine/Testing.kt

@@ -4,5 +4,6 @@ object Testing {
     /**
      * Method for testing purpose. It allows starting machine from particular [state]
      */
-    fun StateMachine.startFrom(state: IState) = (this as InternalStateMachine).startFrom(state)
+    fun StateMachine.startFrom(state: IState, argument: Any? = null) =
+        (this as InternalStateMachine).startFrom(state, argument)
 }

kstatemachine/src/test/kotlin/ru/nsk/kstatemachine/ActiveStatesTest.kt

@@ -64,9 +64,6 @@ class ActiveStatesTest : StringSpec({
             }
         }
 
-        val s = DefaultState()
-        s.recursiveEnterInitialStates()
-
         machine.activeStates().shouldContainExactly(initialState, nestedMachine)
     }
 })

kstatemachine/src/test/kotlin/ru/nsk/kstatemachine/StateMachineTest.kt

@@ -202,9 +202,7 @@ class StateMachineTest : StringSpec({
 
         lateinit var first: State
         val machine = createStateMachine {
-            first = initialState {
-                onEntry { callbacks.onEntryState(this) }
-            }
+            first = initialState { callbacks.listen(this) }
             onStarted { callbacks.onStarted(this) }
         }
 

kstatemachine/src/test/kotlin/ru/nsk/kstatemachine/TransitionArgumentTest.kt

@@ -0,0 +1,50 @@
+package ru.nsk.kstatemachine
+
+import io.kotest.core.spec.style.StringSpec
+import io.kotest.matchers.shouldBe
+import io.kotest.matchers.types.shouldBeSameInstanceAs
+import io.mockk.verify
+import io.mockk.verifySequence
+import org.junit.jupiter.api.fail
+
+private const val ARGUMENT = 1
+
+class TransitionArgumentTest : StringSpec({
+    "transition argument" {
+        val callbacks = mockkCallbacks()
+
+        val second = object : DefaultState("second") {}
+
+        val machine = createStateMachine {
+            addState(second) {
+                callbacks.listen(this)
+                onEntry { it.transition.argument shouldBe ARGUMENT }
+            }
+            initialState("first") {
+                transition<SwitchEvent> {
+                    targetState = second
+                    onTriggered { it.transition.argument = ARGUMENT }
+                }
+            }
+        }
+
+        machine.processEvent(SwitchEvent)
+        verifySequence { callbacks.onEntryState(second) }
+    }
+
+    "transition argument on start" {
+        val callbacks = mockkCallbacks()
+        lateinit var state1: State
+
+        val machine = createStateMachine(start = false) {
+            state1 = initialState("first") {
+                callbacks.listen(this)
+                onEntry { it.argument shouldBe ARGUMENT }
+            }
+        }
+        machine.start(ARGUMENT)
+
+        machine.processEvent(SwitchEvent)
+        verifySequence { callbacks.onEntryState(state1) }
+    }
+})

kstatemachine/src/test/kotlin/ru/nsk/kstatemachine/TransitionTest.kt

@@ -7,35 +7,7 @@ import io.mockk.verify
 import io.mockk.verifySequence
 import org.junit.jupiter.api.fail
 
-private const val ARGUMENT = 1
-
 class TransitionTest : StringSpec({
-    "transition argument" {
-        val callbacks = mockkCallbacks()
-
-        val second = object : DefaultState("second") {}
-
-        val machine = createStateMachine {
-            addState(second) {
-                onEntry {
-                    callbacks.onEntryState(this)
-                    it.transition.argument shouldBe ARGUMENT
-                }
-            }
-            initialState("first") {
-                transition<SwitchEvent> {
-                    targetState = second
-                    onTriggered {
-                        it.transition.argument = ARGUMENT
-                    }
-                }
-            }
-        }
-
-        machine.processEvent(SwitchEvent)
-        verifySequence { callbacks.onEntryState(second) }
-    }
-
     "transition direction" {
         val callbacks = mockkCallbacks()