Store values for DataStates for undo() function

Make defensive copies of listeners before forEach() loops, as a user may call removeListener() from machine callback.
Add once argument to onEntry/onExit callbacks.
Add return value to onTriggered() method in DSL transition builder.

Author: nsk90

README.md

@@ -38,6 +38,7 @@ Main features are:
   from event to state
 * [Parallel states](https://nsk90.github.io/kstatemachine/#parallel-states) to avoid a combinatorial explosion of
   states
+* [Undo transitions](https://nsk90.github.io/kstatemachine/#undo-transitions) for navigating back to previous state
 * [Argument](https://nsk90.github.io/kstatemachine/#arguments) passing for events and transitions
 * Supports [pending events](https://nsk90.github.io/kstatemachine/#pending-events)
 * [Export state machine](https://nsk90.github.io/kstatemachine/#export) structure

docs/index.md

@@ -103,9 +103,19 @@ state {
 Or even shorter:
 
 ```kotlin
-state().onEntry { /*...*/ }
+state().onEntry { /* ... */ }
 ```
 
+`onEntry` and `onExit` DSL methods provide `once` argument. If it is set to `true` the listener will be removed after
+the first triggering.
+
+```kotlin
+state().onEntry(once = true) { /* ... */ }
+```
+
+_Note: it is safe to add and remove listeners from any machine callbacks, library protects its internal loops from such
+modifications._
+
 ### Listen group of states
 
 If you need to perform some actions depending on active statuses of two or more states use `onActiveAllOf()`
@@ -164,14 +174,16 @@ createStateMachine {
 }
 ```
 
-### Targetless transitions
+### Target-less transitions
 
 Transition may have no target state (`targetState` is null) which means that state machine stays in current state when
-such transition triggers:
+such transition triggers, it is useful to perform some actions without changing current state:
 
 ```kotlin
 greenState {
-    transition<YellowEvent>()
+    transition<YellowEvent> {
+        onTriggered { /* ... */ }
+    }
 }
 ```
 
@@ -268,12 +280,35 @@ There are two predefined event matchers:
 
 You can define your own matchers by subclassing `EventMatcher` class.
 
-## Undo transition
+## Undo transitions
+
+Transitions may be undone with `StateMachine.undo()` function or alternatively by sending special `UndoEvent` to machine
+like this `machine.processEvent(UndoEvent)`. State Machine will roll back last transition which is usually is switching
+to previous state (except target-less transitions).
+This API might be called as many times as needed.
+To implement this feature library stores transitions in a stack, it takes memory,
+so this feature is disabled by default and must be enabled explicitly using `createStateMachine(enableUndo = true)`
+argument.
 
-Transitions may be undone with `StateMachine::undo()` function or by sending special `UndoEvent` to machine
-like this `machine.processEvent(UndoEvent)`. State Machine will switch to previous state. To implement this feature
-library stores target states of transitions in a stack, it takes memory, so this feature is disabled by default and must
-be enabled explicitly using `createStateMachine(enableUndo = true)` argument.
+Undo functionality is implemented as `Event`, so it possible to call `undo()` from notification callbacks, if you use
+`QueuePendingEventHandler` (which is default) or its analog.
+
+For example if states of state machine represent UI screens, `undo()` acts like some kind of `navigateUp()` function.
+
+Internally every `UndoEvent` is transformed to `WrappedEvent` which stores original event and argument.
+When some state is entered as a result of undo operation you can access original event and argument with
+`unwrappedEvent` and `unwrappedArgument` extension properties of `TransitionParams` class.
+Original event is the event that triggered original transition to this state.
+
+```kotlin
+state {
+    onEntry { transitionParams -> // when called as result of undo() operation
+        transitionParams.event // is WrappedEvent
+        transitionParams.unwrappedEvent // is original event
+        (transitionParams.event as WrappedEvent).event // same as using unwrappedEvent extension
+    }
+}
+```
 
 ## Logging
 
@@ -582,7 +617,7 @@ Use `exportToPlantUml()` extension function to export state machine
 to [PlantUML state diagram](https://plantuml.com/en/state-diagram).
 
 ```kotlin
-val machine = createStateMachine { /*...*/ }
+val machine = createStateMachine { /* ... */ }
 println(machine.exportToPlantUml())
 ```
 

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

@@ -164,6 +164,7 @@ open class BaseStateImpl(override val name: String?, override val childMode: Chi
                 if (initialState !is StateMachine)  // inner state machine manages its internal state by its own
                     initialState.recursiveEnterInitialStates(transitionParams)
             }
+
             ChildMode.PARALLEL -> data.states.forEach {
                 handleStateEntry(it, transitionParams)
                 if (it !is StateMachine) // inner state machine manages its internal state by its own

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

@@ -7,7 +7,7 @@ import ru.nsk.kstatemachine.HistoryType.SHALLOW
 open class DefaultState(name: String? = null, childMode: ChildMode = EXCLUSIVE) :
     BaseStateImpl(name, childMode), State
 
-open class DefaultDataState<out D: Any>(
+open class DefaultDataState<out D : Any>(
     name: String? = null,
     override val defaultData: D? = null,
     childMode: ChildMode = EXCLUSIVE
@@ -24,22 +24,24 @@ open class DefaultDataState<out D: Any>(
     override fun onDoEnter(transitionParams: TransitionParams<*>) {
         if (this == transitionParams.direction.targetState) {
             when (val event = transitionParams.event) {
-                is DataEvent<*> -> {
-                    @Suppress("UNCHECKED_CAST")
-                    event as DataEvent<D>
-                    with(event.data) {
-                        _data = this
-                        _lastData = this
-                    }
-                }
-                is IUndoEvent -> _data = lastData
+                is DataEvent<*> -> assignEvent(event)
+                is WrappedEvent -> assignEvent(event.event)
                 else -> error("$event does not contain data required by $this")
             }
         } else { // implicit activation
             _data = lastData
         }
     }
 
+    private fun assignEvent(event: Event) {
+        @Suppress("UNCHECKED_CAST")
+        event as DataEvent<D>
+        with(event.data) {
+            _data = this
+            _lastData = this
+        }
+    }
+
     override fun onDoExit(transitionParams: TransitionParams<*>) {
         _data = null
     }
@@ -56,7 +58,7 @@ open class DefaultFinalState(name: String? = null) : DefaultState(name), FinalSt
     override fun <E : Event> addTransition(transition: Transition<E>) = super<FinalState>.addTransition(transition)
 }
 
-open class DefaultFinalDataState<out D: Any>(name: String? = null, defaultData: D? = null) :
+open class DefaultFinalDataState<out D : Any>(name: String? = null, defaultData: D? = null) :
     DefaultDataState<D>(name, defaultData), FinalDataState<D> {
     override fun <E : Event> addTransition(transition: Transition<E>) = super<FinalDataState>.addTransition(transition)
 }

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

@@ -78,7 +78,7 @@ interface State : IState
 /**
  * State which holds data while it is active
  */
-interface DataState<out D: Any> : IState {
+interface DataState<out D : Any> : IState {
     val defaultData: D?
 
     /**
@@ -103,7 +103,7 @@ interface IFinalState : IState {
 }
 
 interface FinalState : IFinalState, State
-interface FinalDataState<out D: Any> : IFinalState, DataState<D>
+interface FinalDataState<out D : Any> : IFinalState, DataState<D>
 
 /**
  * Pseudo state is a state that machine passes automatically without explicit event. It cannot be active.
@@ -184,23 +184,32 @@ inline fun <reified S : IState> IState.requireState(recursive: Boolean = true) =
 
 operator fun <S : IState> S.invoke(block: StateBlock<S>) = block()
 
-fun <S : IState> S.onEntry(block: S.(TransitionParams<*>) -> Unit) {
+/**
+ * Most common methods [onEntry] and [onExit] are shipped with [once] argument, to remove listener
+ * after it is triggered the first time.
+ * Looks that it is not necessary in other similar methods.
+ */
+fun <S : IState> S.onEntry(once: Boolean = false, block: S.(TransitionParams<*>) -> Unit) =
     addListener(object : IState.Listener {
-        override fun onEntry(transitionParams: TransitionParams<*>) = block(transitionParams)
+        override fun onEntry(transitionParams: TransitionParams<*>) {
+            block(transitionParams)
+            if (once) removeListener(this)
+        }
     })
-}
 
-fun <S : IState> S.onExit(block: S.(TransitionParams<*>) -> Unit) {
+/** See [onEntry] */
+fun <S : IState> S.onExit(once: Boolean = false, block: S.(TransitionParams<*>) -> Unit) =
     addListener(object : IState.Listener {
-        override fun onExit(transitionParams: TransitionParams<*>) = block(transitionParams)
+        override fun onExit(transitionParams: TransitionParams<*>) {
+            block(transitionParams)
+            if (once) removeListener(this)
+        }
     })
-}
 
-fun <S : IState> S.onFinished(block: S.(TransitionParams<*>) -> Unit) {
+fun <S : IState> S.onFinished(block: S.(TransitionParams<*>) -> Unit) =
     addListener(object : IState.Listener {
         override fun onFinished(transitionParams: TransitionParams<*>) = block(transitionParams)
     })
-}
 
 /**
  * @param name is optional and is useful for getting state instance after state machine setup
@@ -212,7 +221,7 @@ fun IState.state(
     init: StateBlock<State>? = null
 ) = addState(DefaultState(name, childMode), init)
 
-fun <D: Any> IState.dataState(
+fun <D : Any> IState.dataState(
     name: String? = null,
     defaultData: D? = null,
     childMode: ChildMode = ChildMode.EXCLUSIVE,
@@ -231,7 +240,7 @@ fun IState.initialState(
 /**
  * @param defaultData is necessary for initial [DataState]
  */
-fun <D: Any>  IState.initialDataState(
+fun <D : Any> IState.initialDataState(
     name: String? = null,
     defaultData: D,
     childMode: ChildMode = ChildMode.EXCLUSIVE,
@@ -257,7 +266,7 @@ fun <S : IFinalState> IState.addFinalState(state: S, init: StateBlock<S>? = null
 fun IState.finalState(name: String? = null, init: StateBlock<FinalState>? = null) =
     addFinalState(DefaultFinalState(name), init)
 
-fun <D: Any> IState.finalDataState(
+fun <D : Any> IState.finalDataState(
     name: String? = null,
     defaultData: D? = null,
     init: StateBlock<FinalDataState<D>>? = null

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

@@ -30,6 +30,10 @@ abstract class InternalState : IState {
 
     internal abstract fun recursiveExit(transitionParams: TransitionParams<*>)
     internal abstract fun recursiveStop()
+
+    /**
+     * Called after each (including initial) transition completion.
+     */
     internal abstract fun recursiveAfterTransitionComplete(transitionParams: TransitionParams<*>)
     internal abstract fun cleanup()
 }
@@ -38,7 +42,7 @@ internal fun InternalState.requireParent() = requireNotNull(internalParent) { "$
 
 internal fun InternalState.stateNotify(block: IState.Listener.() -> Unit) {
     val machine = machine as InternalStateMachine
-    listeners.forEach { machine.runDelayingException { it.block() } }
+    listeners.toList().forEach { machine.runDelayingException { it.block() } }
 }
 
 internal fun <E : Event> InternalState.findTransitionsByEvent(event: E): List<InternalTransition<E>> {

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

@@ -10,5 +10,5 @@ interface InternalTransition<E : Event> : Transition<E> {
 
 internal fun InternalTransition<*>.transitionNotify(block: Transition.Listener.() -> Unit) {
     val machine = sourceState.machine as InternalStateMachine
-    listeners.forEach { machine.runDelayingException { it.block() } }
+    listeners.toList().forEach { machine.runDelayingException { it.block() } }
 }

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

@@ -108,41 +108,37 @@ interface StateMachine : State {
 
 typealias StateMachineBlock = StateMachine.() -> Unit
 
-fun StateMachine.onStarted(block: StateMachine.() -> Unit) {
+fun StateMachine.onStarted(block: StateMachine.() -> Unit) =
     addListener(object : StateMachine.Listener {
         override fun onStarted() = block()
     })
-}
 
-fun StateMachine.onStopped(block: StateMachine.() -> Unit) {
+fun StateMachine.onStopped(block: StateMachine.() -> Unit) =
     addListener(object : StateMachine.Listener {
         override fun onStopped() = block()
     })
-}
 
-fun StateMachine.onTransition(block: StateMachine.(TransitionParams<*>) -> Unit) {
+fun StateMachine.onTransition(block: StateMachine.(TransitionParams<*>) -> Unit) =
     addListener(object : StateMachine.Listener {
         override fun onTransition(transitionParams: TransitionParams<*>) =
             block(transitionParams)
     })
-}
 
-fun StateMachine.onStateChanged(block: StateMachine.(newState: IState) -> Unit) {
+fun StateMachine.onStateChanged(block: StateMachine.(newState: IState) -> Unit) =
     addListener(object : StateMachine.Listener {
         override fun onStateChanged(newState: IState) = block(newState)
     })
-}
 
 /**
- * Navigates machine to previous state.
+ * Rolls back transition (usually it is navigating machine to previous state).
  * Previous states are stored in a stack, so this method mey be called multiple times if needed.
- * This function has same effect as calling processEvent(UndoEvent), but throws if undo feature is not enabled.
+ * This function has same effect as alternative syntax processEvent(UndoEvent), but throws if undo feature is not enabled.
  */
-fun StateMachine.undo() {
+fun StateMachine.undo(argument: Any? = null) {
     check(isUndoEnabled) {
         "Undo functionality is not enabled, use createStateMachine(isUndoEnabled = true) argument to enable it."
     }
-    processEvent(UndoEvent)
+    processEvent(UndoEvent, argument)
 }
 
 /**

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

@@ -29,7 +29,7 @@ internal class StateMachineImpl(
     init {
         if (isUndoEnabled) {
             val undoState = addState(UndoState())
-            transition<UndoEvent>("undo transition", undoState)
+            transition<WrappedEvent>("undo transition", undoState)
         }
     }
 
@@ -72,6 +72,7 @@ internal class StateMachineImpl(
                 val transitionParams = makeStartTransitionParams(this, state, argument)
                 runMachine(transitionParams)
                 switchToTargetState(state as InternalState, this, transitionParams)
+                recursiveAfterTransitionComplete(transitionParams)
             }
         }
     }
@@ -108,16 +109,27 @@ internal class StateMachineImpl(
         check(!isDestroyed) { "$this is already destroyed" }
         check(isRunning) { "$this is not started, call start() first" }
 
+        val eventAndArgument = wrapEvent(event, argument)
+
         if (isProcessingEvent) {
-            pendingEventHandler.onPendingEvent(event, argument)
+            pendingEventHandler.onPendingEvent(eventAndArgument.event, eventAndArgument.argument)
             // pending event cannot be processed while previous event is still processing
             // even if PendingEventHandler does not throw. QueuePendingEventHandler implementation stores such events
             // to be processed later.
             return
         }
 
         eventProcessingScope {
-            process(EventAndArgument(event, argument))
+            process(eventAndArgument)
+        }
+    }
+
+    private fun wrapEvent(event: Event, argument: Any?): EventAndArgument<*> {
+        return if (isUndoEnabled && event is UndoEvent) {
+            val wrapped = requireState<UndoState>().makeWrappedEvent()
+            EventAndArgument(wrapped, argument)
+        } else {
+            EventAndArgument(event, argument)
         }
     }
 
@@ -197,7 +209,7 @@ internal class StateMachineImpl(
         }
 
         log {
-            val targetText = if (targetState != null) "to $targetState" else "[targetless]"
+            val targetText = if (targetState != null) "to $targetState" else "[target-less]"
             "${event::class.simpleName} triggers $transition from ${transition.sourceState} $targetText"
         }
 
@@ -235,7 +247,7 @@ internal class StateMachineImpl(
 }
 
 internal fun InternalStateMachine.machineNotify(block: StateMachine.Listener.() -> Unit) {
-    machineListeners.forEach { runDelayingException { it.block() } }
+    machineListeners.toList().forEach { runDelayingException { it.block() } }
 }
 
 internal fun InternalStateMachine.runDelayingException(block: () -> Unit) =