Merge pull request #92 from nsk90/mermaid-export

Add Mermaid export feature

Author: nsk90

README.md

@@ -128,11 +128,12 @@ fun main() = runBlocking {
       <img src="https://github.com/nsk90/android-kstatemachine-sample/blob/main/images/android-app-sample.gif"
           alt="Android sample app" width="30%" height="30%"/>
   </p>
-
+* [Finished state sample](./samples/src/commonMain/kotlin/ru/nsk/samples/FinishedStateSample.kt)
 * [Transition on FinishedEvent sample](./samples/src/commonMain/kotlin/ru/nsk/samples/FinishedEventSample.kt)
 * [FinishedEvent using with DataState sample](./samples/src/commonMain/kotlin/ru/nsk/samples/FinishedEventDataStateSample.kt)
 * [Undo transition sample](./samples/src/commonMain/kotlin/ru/nsk/samples/UndoTransitionSample.kt)
 * [PlantUML nested states export sample](./samples/src/commonMain/kotlin/ru/nsk/samples/PlantUmlExportSample.kt)
+* [Mermaid nested states export sample](./samples/src/commonMain/kotlin/ru/nsk/samples/MermaidExportSample.kt)
 * [Inherit transitions by grouping states sample](./samples/src/commonMain/kotlin/ru/nsk/samples/InheritTransitionsSample.kt)
 * [Minimal sealed classes sample](./samples/src/commonMain/kotlin/ru/nsk/samples/MinimalSealedClassesSample.kt)
 * [Usage without Kotlin Coroutines sample](./samples/src/commonMain/kotlin/ru/nsk/samples/StdLibMinimalSealedClassesSample.kt)

docs/index.md

@@ -45,6 +45,7 @@
     * [Migration guide from versions older than v0.20.0](#migration-guide-from-versions-older-than-v0200)
 * [Export](#export)
     * [PlantUML](#plantuml)
+    * [Mermaid](#mermaid)
 * [Testing](#testing)
 * [Multiplatform](#multiplatform)
 * [Consider using Kotlin sealed classes](#consider-using-kotlin-sealed-classes)
@@ -433,7 +434,7 @@ createStateMachine(scope) {
 Some of state machines and states are infinite, but other ones may finish.
 
 * In `ChildMode.EXCLUSIVE` state or state machine finishes when enters top-level final state.
-* In `ChildMode.PARALLEL` state or state machine finishes when all its children has finished.
+* In `ChildMode.PARALLEL` state or state machine finishes when all its direct children has finished.
 
 To make a state final, it must implement `FinalState` marker interface.
 Built-in implementation of such state is `DefaultFinalState`.
@@ -447,6 +448,8 @@ sealed class States : DefaultState() {
 }
 ```
 
+See [Finished state sample](https://github.com/nsk90/kstatemachine/tree/master/samples/src/commonMain/kotlin/ru/nsk/samples/FinishedStateSample.kt)
+
 Finishing of states and state machines is treated little differently.
 State machine that was finished stops processing incoming events.
 But when some nested state is finished its transitions are still active,
@@ -596,12 +599,12 @@ choiceState {
 }
 ```
 
-There is also `choiceDataState()` function available for choosing between `DataState`s. You can define `dataTransition` 
+There is also `choiceDataState()` function available for choosing between `DataState`s. You can define `dataTransition`
 to target such pseudo data state.
 
 You can use `choiceState` even on initial state branch.
-Note that `choiceState` can not be active, so if the library performs a transition and finds that `choiceState` is 
-going to be activated, it executes its lambda argument and navigates to the resulting state. 
+Note that `choiceState` can not be active, so if the library performs a transition and finds that `choiceState` is
+going to be activated, it executes its lambda argument and navigates to the resulting state.
 If the resulting state is also a `PseudoState` instance, further redirections might be applied.
 
 ### History state
@@ -652,7 +655,7 @@ createStateMachine(scope) {
 is activated it requires data value from a `DataEvent`. You can use `lastData` field to access last data value even
 after state exit, it falls back to `defaultData` if provided or throws.
 
-### Target-less data transitions 
+### Target-less data transitions
 
 You can define target-less transitions for `DataState`. Please, note that if you want such transition to change state's
 `data` field, it should be `EXTERNAL` type. If target-less transition is `LOCAL` it does not change states data.
@@ -871,9 +874,14 @@ Contains additional functions to work with KStateMachine depending on Kotlin Cor
 ## Export
 
 > [!NOTE]
-> Currently transitions that use lambdas like `transitionConditionally()` and`transitionOn()` are not exported.
-> User defined lambdas that are passed to calculate next state could not be correctly
-> called during export process as they may touch application data that is not valid when export is running.
+> Transitions that use lambdas like `transitionConditionally()` and`transitionOn()` are not exported by default.
+> You can enable their export with `unsafeCallConditionalLambdas` flag of `exportToPlantUml()` function.
+> With `unsafeCallConditionalLambdas` flag set, user defined lambdas that are passed to the library to calculate next
+> state would be called during export process. This will give more complete (still not full) export output,
+> but may cause runtime errors depending on what the lambda actually do. As it may touch application data that is not
+> valid when export is running, also `event` argument will be faked by unsafe cast, so touching it 
+> will cause `ClassCastException`
+> That is why `unsafeCallConditionalLambdas` flag should be considered as debug/development tool only.
 
 ### PlantUML
 
@@ -889,6 +897,25 @@ Copy/paste resulting output to [Plant UML online editor](http://www.plantuml.com
 
 See [PlantUML nested states export sample](https://github.com/nsk90/kstatemachine/tree/master/samples/src/commonMain/kotlin/ru/nsk/samples/PlantUmlExportSample.kt)
 
+### Mermaid
+
+`Mermaid` uses almost the same text format as `PlantUML`.
+
+Use `exportToMermaid()`/`exportToToMermaidBlocking()` extension function to export state machine
+to [Mermaid state diagram](https://mermaid.js.org/syntax/stateDiagram.html).
+
+```kotlin
+val machine = createStateMachine(scope) { /* ... */ }
+println(machine.exportToPlantUml())
+```
+
+`Intellij IDEA` users may use official [Mermaid plugin](https://plugins.jetbrains.com/plugin/20146-mermaid) 
+to view diagrams directly in IDE for file types: `.mmd` and `.mermaid`.
+
+Copy/paste resulting output to [Mermaid live editor](https://mermaid.live/)
+
+See [Mermaid nested states export sample](https://github.com/nsk90/kstatemachine/tree/master/samples/src/commonMain/kotlin/ru/nsk/samples/MermaidExportSample.kt)
+
 ## Testing
 
 For testing, it might be useful to check how state machine reacts on events from particular state. There

kstatemachine/src/commonMain/kotlin/ru/nsk/kstatemachine/TransitionBuilder.kt

@@ -1,7 +1,6 @@
 package ru.nsk.kstatemachine
 
-import ru.nsk.kstatemachine.TransitionDirectionProducerPolicy.CollectTargetStatesPolicy
-import ru.nsk.kstatemachine.TransitionDirectionProducerPolicy.DefaultPolicy
+import ru.nsk.kstatemachine.TransitionDirectionProducerPolicy.*
 
 @StateMachineDslMarker
 abstract class TransitionBuilder<E : Event>(protected val name: String?, protected val sourceState: IState) {
@@ -24,12 +23,13 @@ abstract class GuardedTransitionBuilder<E : Event, S : IState>(name: String?, so
     override fun build(): Transition<E> {
         val direction: TransitionDirectionProducer<E> = {
             when (it) {
-                is DefaultPolicy<E> ->
+                is DefaultPolicy ->
                     if (it.eventAndArgument.guard())
                         it.targetStateOrStay(targetState)
                     else
                         noTransition()
-                is CollectTargetStatesPolicy<E> -> it.targetStateOrStay(targetState)
+                is CollectTargetStatesPolicy,
+                is UnsafeCollectTargetStatesPolicy -> it.targetStateOrStay(targetState)
             }
         }
 
@@ -44,14 +44,15 @@ abstract class GuardedTransitionOnBuilder<E : Event, S : IState>(name: String?,
     lateinit var targetState: suspend EventAndArgument<E>.() -> S
 
     override fun build(): Transition<E> {
-        val direction: TransitionDirectionProducer<E> = {
-            when (it) {
-                is DefaultPolicy<E> ->
-                    if (it.eventAndArgument.guard())
-                        it.targetState(it.eventAndArgument.targetState())
+        val direction: TransitionDirectionProducer<E> = { policy ->
+            when (policy) {
+                is DefaultPolicy ->
+                    if (policy.eventAndArgument.guard())
+                        policy.targetState(policy.eventAndArgument.targetState())
                     else
                         noTransition()
-                is CollectTargetStatesPolicy<E> -> noTransition()
+                is CollectTargetStatesPolicy -> noTransition()
+                is UnsafeCollectTargetStatesPolicy -> policy.targetState(policy.eventAndArgument.targetState())
             }
         }
 
@@ -66,10 +67,11 @@ class ConditionalTransitionBuilder<E : Event>(name: String?, sourceState: IState
     lateinit var direction: suspend EventAndArgument<E>.() -> TransitionDirection
 
     override fun build(): Transition<E> {
-        val direction: TransitionDirectionProducer<E> = {
-            when (it) {
-                is DefaultPolicy<E> -> it.eventAndArgument.direction()
-                is CollectTargetStatesPolicy<E> -> noTransition()
+        val direction: TransitionDirectionProducer<E> = { policy ->
+            when (policy) {
+                is DefaultPolicy -> policy.eventAndArgument.direction()
+                is CollectTargetStatesPolicy -> noTransition()
+                is UnsafeCollectTargetStatesPolicy -> policy.eventAndArgument.direction()
             }
         }
 
@@ -98,14 +100,15 @@ class DataGuardedTransitionBuilder<E : DataEvent<D>, D : Any>(name: String?, sou
 
     override fun build(): Transition<E> {
         require(this::targetState.isInitialized) { "targetState should be set in this transition builder" }
-        val direction: TransitionDirectionProducer<E> = {
-            when (it) {
-                is DefaultPolicy<E> ->
-                    if (it.eventAndArgument.guard())
-                        it.targetState(targetState)
+        val direction: TransitionDirectionProducer<E> = { policy ->
+            when (policy) {
+                is DefaultPolicy ->
+                    if (policy.eventAndArgument.guard())
+                        policy.targetState(targetState)
                     else
                         noTransition()
-                is CollectTargetStatesPolicy<E> -> it.targetState(targetState)
+                is CollectTargetStatesPolicy,
+                is UnsafeCollectTargetStatesPolicy -> policy.targetState(targetState)
             }
         }
 

kstatemachine/src/commonMain/kotlin/ru/nsk/kstatemachine/TransitionDirection.kt

@@ -114,16 +114,30 @@ typealias ResolvedTransition<E> = Pair<InternalTransition<E>, TransitionDirectio
 internal typealias TransitionDirectionProducer<E> = suspend (TransitionDirectionProducerPolicy<E>) -> TransitionDirection
 
 sealed class TransitionDirectionProducerPolicy<E : Event> {
+    /**
+     * Standard behaviour, calls all lambdas and resolves target states
+     */
     internal class DefaultPolicy<E : Event>(val eventAndArgument: EventAndArgument<E>) :
         TransitionDirectionProducerPolicy<E>() {
         override suspend fun targetState(targetState: IState) = eventAndArgument.targetState(targetState)
         override suspend fun targetStateOrStay(targetState: IState?) = targetState?.let { targetState(it) } ?: stay()
     }
 
     /**
-     * TODO find the way to collect target states of conditional transitions
+     * Does not call conditional lambdas, gets only non-conditional target states
+     */
+    internal class CollectTargetStatesPolicy<E : Event> :
+        TransitionDirectionProducerPolicy<E>() {
+        override suspend fun targetState(targetState: IState) = unresolvedTargetState(targetState)
+        override suspend fun targetStateOrStay(targetState: IState?) = targetState?.let { targetState(it) } ?: stay()
+    }
+
+    /**
+     * Calls lambdas to get unresolved target states,
+     * this may fail in runtime depending on user defined lambda behaviour
      */
-    internal class CollectTargetStatesPolicy<E : Event> : TransitionDirectionProducerPolicy<E>() {
+    internal class UnsafeCollectTargetStatesPolicy<E : Event>(val eventAndArgument: EventAndArgument<E>) :
+        TransitionDirectionProducerPolicy<E>() {
         override suspend fun targetState(targetState: IState) = unresolvedTargetState(targetState)
         override suspend fun targetStateOrStay(targetState: IState?) = targetState?.let { targetState(it) } ?: stay()
     }

kstatemachine/src/commonMain/kotlin/ru/nsk/kstatemachine/visitors/ExportPlantUmlVisitor.kt

@@ -2,35 +2,65 @@ package ru.nsk.kstatemachine.visitors
 
 import ru.nsk.kstatemachine.*
 import ru.nsk.kstatemachine.TransitionDirectionProducerPolicy.CollectTargetStatesPolicy
+import ru.nsk.kstatemachine.TransitionDirectionProducerPolicy.UnsafeCollectTargetStatesPolicy
+import ru.nsk.kstatemachine.visitors.CompatibilityFormat.MERMAID
+import ru.nsk.kstatemachine.visitors.CompatibilityFormat.PLANT_UML
+
+/**
+ * This object will be unsafely cast to any kind of [Event],
+ * causing runtime failures if user defined (conditional) lambdas will touch this object.
+ */
+internal object ExportPlantUmlEvent : Event
+
+internal enum class CompatibilityFormat { PLANT_UML, MERMAID }
 
 /**
  * Export state machine to Plant UML language format.
  * @see <a href="https://plantuml.com/ru/state-diagram">Plant UML state diagram</a>
  *
- * Conditional transitions currently are not supported.
+ * Conditional transitions are partly supported with [unsafeCallConditionalLambdas] flag.
  */
-internal class ExportPlantUmlVisitor(private val showEventLabels: Boolean) : CoVisitor {
+internal class ExportPlantUmlVisitor(
+    private val format: CompatibilityFormat,
+    private val showEventLabels: Boolean,
+    private val unsafeCallConditionalLambdas: Boolean,
+) : CoVisitor {
     private val builder = StringBuilder()
     private var indent = 0
     private val crossLevelTransitions = mutableListOf<String>()
 
     fun export() = builder.toString()
 
     override suspend fun visit(machine: StateMachine) {
-        line("@startuml")
-        line("hide empty description")
+        when (format) {
+            PLANT_UML -> {
+                line("@startuml")
+                line("hide empty description")
+            }
+            MERMAID -> line("stateDiagram-v2")
+        }
 
         processStateBody(machine)
         crossLevelTransitions.forEach { line(it) }
 
-        line("@enduml")
+        if (format == PLANT_UML)
+            line("@enduml")
     }
 
     override suspend fun visit(state: IState) {
         if (state.states.isEmpty()) {
             when (state) {
                 is HistoryState, is UndoState -> return
-                is RedirectPseudoState -> line("state ${state.graphName()} $CHOICE")
+                is RedirectPseudoState -> {
+                    val stateName = state.graphName()
+                    line("state $stateName $CHOICE")
+                    if (unsafeCallConditionalLambdas) {
+                        val targetState = state.resolveTargetState(
+                            EventAndArgument(ExportPlantUmlEvent, null)
+                        ) as InternalState
+                        crossLevelTransitions += "$stateName --> ${targetState.targetGraphName()}"
+                    }
+                }
                 else -> line("state ${state.graphName()}")
             }
         } else {
@@ -57,26 +87,25 @@ internal class ExportPlantUmlVisitor(private val showEventLabels: Boolean) : CoV
         val sourceState = transition.sourceState.graphName()
 
         @Suppress("UNCHECKED_CAST")
-        val targetStates = transition.produceTargetStateDirection(CollectTargetStatesPolicy()).targetStates
+        val targetStates = transition.produceTargetStateDirection(makeDirectionProducerPolicy()).targetStates
                 as Set<InternalState>
-        val targetState = targetStates.firstOrNull() ?: return // fixme iterate over all
+        targetStates.forEach { targetState -> // actually plantUml may not understand multiple transitions
+            val transitionString = "$sourceState --> ${targetState.targetGraphName()}${transitionLabel(transition)}"
 
-        val graphName = if (targetState is HistoryState) {
-            val prefix = targetState.requireInternalParent().graphName()
-            when (targetState.historyType) {
-                HistoryType.SHALLOW -> "$prefix$SHALLOW_HISTORY"
-                HistoryType.DEEP -> "$prefix$DEEP_HISTORY"
-            }
-        } else {
-            targetState.graphName()
+            if (transition.sourceState.isNeighbor(targetState))
+                line(transitionString)
+            else
+                crossLevelTransitions += transitionString
         }
+    }
 
-        val transitionString = "$sourceState --> $graphName${transitionLabel(transition)}"
-
-        if (transition.sourceState.isNeighbor(targetState))
-            line(transitionString)
-        else
-            crossLevelTransitions.add(transitionString)
+    private fun <E : Event> makeDirectionProducerPolicy(): TransitionDirectionProducerPolicy<E> {
+        return if (unsafeCallConditionalLambdas) {
+            @Suppress("UNCHECKED_CAST") // this is unsafe by design
+            UnsafeCollectTargetStatesPolicy(EventAndArgument(ExportPlantUmlEvent as E, null))
+        } else {
+            CollectTargetStatesPolicy()
+        }
     }
 
     private suspend fun processStateBody(state: IState) {
@@ -119,23 +148,49 @@ internal class ExportPlantUmlVisitor(private val showEventLabels: Boolean) : CoV
         const val SHALLOW_HISTORY = "[H]"
         const val DEEP_HISTORY = "[H*]"
         const val CHOICE = "<<choice>>"
+
         fun IState.graphName(): String {
             val name = name?.replace(" ", "_") ?: "State${hashCode()}"
             return if (this !is StateMachine) name else "${name}_StateMachine"
         }
 
+        fun InternalState.targetGraphName(): String {
+            return if (this is HistoryState) {
+                val prefix = requireInternalParent().graphName()
+                when (historyType) {
+                    HistoryType.SHALLOW -> "$prefix$SHALLOW_HISTORY"
+                    HistoryType.DEEP -> "$prefix$DEEP_HISTORY"
+                }
+            } else {
+                graphName()
+            }
+        }
+
         fun label(text: String?) = if (!text.isNullOrBlank()) " : $text" else ""
     }
 }
 
-suspend fun StateMachine.exportToPlantUml(showEventLabels: Boolean = false) =
-    with(ExportPlantUmlVisitor(showEventLabels)) {
-        accept(this)
-        export()
-    }
+/**
+ * Export [StateMachine] to PlantUML state diagram
+ * @see <a href="https://plantuml.com/">PlantUML</a>
+ *
+ * [unsafeCallConditionalLambdas] will call conditional lambdas which can touch application data,
+ * this may give more complete output, but may be not safe.
+ */
+suspend fun StateMachine.exportToPlantUml(
+    showEventLabels: Boolean = false,
+    unsafeCallConditionalLambdas: Boolean = false,
+) = with(ExportPlantUmlVisitor(PLANT_UML, showEventLabels, unsafeCallConditionalLambdas)) {
+    accept(this)
+    export()
+}
 
-fun StateMachine.exportToPlantUmlBlocking(showEventLabels: Boolean = false) = coroutineAbstraction.runBlocking {
-    with(ExportPlantUmlVisitor(showEventLabels)) {
+/** Blocking analog for [exportToPlantUml] */
+fun StateMachine.exportToPlantUmlBlocking(
+    showEventLabels: Boolean = false,
+    unsafeCallConditionalLambdas: Boolean = false,
+) = coroutineAbstraction.runBlocking {
+    with(ExportPlantUmlVisitor(PLANT_UML, showEventLabels, unsafeCallConditionalLambdas)) {
         accept(this)
         export()
     }