Merge pull request #49 from nsk90/undo

Implement Undo functionality

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,6 +280,36 @@ There are two predefined event matchers:
 
 You can define your own matchers by subclassing `EventMatcher` class.
 
+## 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.
+
+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
 
 You can enable internal state machine logging on your platform.
@@ -365,7 +407,8 @@ the state hierarchy as the source state.
 `StateMachine` is a subclass of `IState`, this allows to use it as a child of another state machine like a simple state.
 The parent state machine treats the child machine as an atomic state. It is not possible to reference states of a child
 machine from parent transitions and vise versa. Child machine is automatically started when parent enters it. Events
-from parent machine are not passed to it child machines. Child machine receives events only from its own `processEvent()`
+from parent machine are not passed to it child machines. Child machine receives events only from its
+own `processEvent()`
 calls.
 
 ## Parallel states
@@ -574,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>(
+open class DefaultDataState<out D : Any>(
     name: String? = null,
     override val defaultData: D? = null,
     childMode: ChildMode = EXCLUSIVE
@@ -22,19 +22,26 @@ open class DefaultDataState<out D>(
         }
 
     override fun onDoEnter(transitionParams: TransitionParams<*>) {
-        if (this == transitionParams.direction.targetState && transitionParams.event !is UndoEvent) {
-            @Suppress("UNCHECKED_CAST")
-            val event = transitionParams.event as? DataEvent<D>
-                ?: error("${transitionParams.event} does not contain data required by $this")
-            with(event.data) {
-                _data = this
-                _lastData = this
+        if (this == transitionParams.direction.targetState) {
+            when (val event = transitionParams.event) {
+                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
     }
@@ -51,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>(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> : 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> : 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> IState.dataState(
+fun <D : Any> IState.dataState(
     name: String? = null,
     defaultData: D? = null,
     childMode: ChildMode = ChildMode.EXCLUSIVE,
@@ -228,6 +237,16 @@ fun IState.initialState(
     init: StateBlock<State>? = null
 ) = addInitialState(DefaultState(name, childMode), init)
 
+/**
+ * @param defaultData is necessary for initial [DataState]
+ */
+fun <D : Any> IState.initialDataState(
+    name: String? = null,
+    defaultData: D,
+    childMode: ChildMode = ChildMode.EXCLUSIVE,
+    init: StateBlock<DataState<D>>? = null
+) = addInitialState(DefaultDataState(name, defaultData, childMode), init)
+
 /**
  * A shortcut for [IState.addState] and [IState.setInitialState] calls
  */
@@ -247,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> IState.finalDataState(
+fun <D : Any> IState.finalDataState(
     name: String? = null,
     defaultData: D? = null,
     init: StateBlock<FinalDataState<D>>? = null
@@ -260,5 +279,4 @@ fun IState.historyState(
     name: String? = null,
     defaultState: IState? = null,
     historyType: HistoryType = HistoryType.SHALLOW
-) =
-    addState(DefaultHistoryState(name, defaultState, historyType))
+) = addState(DefaultHistoryState(name, defaultState, historyType))

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

@@ -52,12 +52,6 @@ interface StateMachine : State {
      */
     fun processEvent(event: Event, argument: Any? = null)
 
-    /**
-     * Navigates machine to previous state.
-     * Previous states are stored in a stack, so this method mey be called multiple times if needed.
-     */
-    fun undo()
-
     /**
      * Destroys machine structure clearing all listeners, states etc.
      */
@@ -114,29 +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)
     })
+
+/**
+ * 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 alternative syntax processEvent(UndoEvent), but throws if undo feature is not enabled.
+ */
+fun StateMachine.undo(argument: Any? = null) {
+    check(isUndoEnabled) {
+        "Undo functionality is not enabled, use createStateMachine(isUndoEnabled = true) argument to enable it."
+    }
+    processEvent(UndoEvent, argument)
 }
 
 /**