Add Contracts for DSL methods

Author: nsk90

kstatemachine-coroutines/src/commonMain/kotlin/ru/nsk/kstatemachine/statemachine/CoroutinesStateMachine.kt

@@ -12,6 +12,9 @@ import ru.nsk.kstatemachine.coroutines.CoroutinesLibCoroutineAbstraction
 import ru.nsk.kstatemachine.coroutines.createStateMachine
 import ru.nsk.kstatemachine.event.Event
 import ru.nsk.kstatemachine.state.ChildMode
+import kotlin.contracts.ExperimentalContracts
+import kotlin.contracts.InvocationKind
+import kotlin.contracts.contract
 import kotlin.coroutines.CoroutineContext
 import kotlin.coroutines.EmptyCoroutineContext
 
@@ -27,15 +30,21 @@ import kotlin.coroutines.EmptyCoroutineContext
  *
  * Note that all calls to created machine instance should be done only from that thread.
  */
+@OptIn(ExperimentalContracts::class)
 suspend fun createStateMachine(
     scope: CoroutineScope,
     name: String? = null,
     childMode: ChildMode = ChildMode.EXCLUSIVE,
     start: Boolean = true,
     creationArguments: CreationArguments = buildCreationArguments {},
     init: suspend BuildingStateMachine.() -> Unit
-) = CoroutinesLibCoroutineAbstraction(scope)
-    .createStateMachine(name, childMode, start, creationArguments, init)
+): StateMachine {
+    contract {
+        callsInPlace(init, InvocationKind.EXACTLY_ONCE)
+    }
+    return CoroutinesLibCoroutineAbstraction(scope)
+        .createStateMachine(name, childMode, start, creationArguments, init)
+}
 
 /**
  * Processes event in async fashion (using launch() to start new coroutine).

kstatemachine/src/commonMain/kotlin/ru/nsk/kstatemachine/coroutines/CoroutineAbstraction.kt

@@ -10,6 +10,9 @@ package ru.nsk.kstatemachine.coroutines
 import ru.nsk.kstatemachine.state.ChildMode
 import ru.nsk.kstatemachine.statemachine.*
 import ru.nsk.kstatemachine.statemachine.StateMachineImpl
+import kotlin.contracts.ExperimentalContracts
+import kotlin.contracts.InvocationKind
+import kotlin.contracts.contract
 import kotlin.coroutines.Continuation
 import kotlin.coroutines.EmptyCoroutineContext
 import kotlin.coroutines.startCoroutine
@@ -52,18 +55,24 @@ internal class StdLibCoroutineAbstraction : CoroutineAbstraction {
     override suspend fun <R : Any> withContext(block: suspend () -> R): R = block()
 }
 
+@OptIn(ExperimentalContracts::class)
 suspend fun CoroutineAbstraction.createStateMachine(
     name: String?,
     childMode: ChildMode,
     start: Boolean,
     creationArguments: CreationArguments = buildCreationArguments {},
     init: suspend BuildingStateMachine.() -> Unit
-): StateMachine = StateMachineImpl(
-    name,
-    childMode,
-    creationArguments,
-    this,
-).apply {
-    init()
-    if (start) start()
+): StateMachine {
+    contract {
+        callsInPlace(init, InvocationKind.EXACTLY_ONCE)
+    }
+    return StateMachineImpl(
+        name,
+        childMode,
+        creationArguments,
+        this,
+    ).apply {
+        init()
+        if (start) start()
+    }
 }

kstatemachine/src/commonMain/kotlin/ru/nsk/kstatemachine/metainfo/ExportMetaInfo.kt

@@ -11,6 +11,9 @@ import ru.nsk.kstatemachine.event.Event
 import ru.nsk.kstatemachine.state.IState
 import ru.nsk.kstatemachine.state.RedirectPseudoState
 import ru.nsk.kstatemachine.transition.EventAndArgument
+import kotlin.contracts.ExperimentalContracts
+import kotlin.contracts.InvocationKind
+import kotlin.contracts.contract
 
 /**
  * Hint to be used with [ExportMetaInfo]
@@ -123,5 +126,10 @@ private data class ExportMetaInfoBuilderImpl(
     }
 }
 
-fun buildExportMetaInfo(builder: ExportMetaInfoBuilder.() -> Unit): ExportMetaInfo =
-    ExportMetaInfoBuilderImpl().apply(builder).copy()
+@OptIn(ExperimentalContracts::class)
+fun buildExportMetaInfo(builder: ExportMetaInfoBuilder.() -> Unit): ExportMetaInfo {
+    contract {
+        callsInPlace(builder, InvocationKind.EXACTLY_ONCE)
+    }
+    return ExportMetaInfoBuilderImpl().apply(builder).copy()
+}

kstatemachine/src/commonMain/kotlin/ru/nsk/kstatemachine/metainfo/MetaInfo.kt

@@ -10,6 +10,9 @@ package ru.nsk.kstatemachine.metainfo
 import ru.nsk.kstatemachine.state.IState
 import ru.nsk.kstatemachine.transition.Transition
 import kotlin.collections.single
+import kotlin.contracts.ExperimentalContracts
+import kotlin.contracts.InvocationKind
+import kotlin.contracts.contract
 
 /**
  * Additional static (designed to be immutable) info for library primitives like [IState] [Transition] etc.
@@ -57,8 +60,13 @@ private data class CompositeMetaInfoBuilderImpl(
     override var metaInfoSet: Set<MetaInfo> = emptySet()
 ) : CompositeMetaInfoBuilder
 
-fun buildCompositeMetaInfo(builder: CompositeMetaInfoBuilder.() -> Unit): CompositeMetaInfo =
-    CompositeMetaInfoBuilderImpl().apply(builder).copy()
+@OptIn(ExperimentalContracts::class)
+fun buildCompositeMetaInfo(builder: CompositeMetaInfoBuilder.() -> Unit): CompositeMetaInfo {
+    contract {
+        callsInPlace(builder, InvocationKind.EXACTLY_ONCE)
+    }
+    return CompositeMetaInfoBuilderImpl().apply(builder).copy()
+}
 
 fun buildCompositeMetaInfo(metaInfo1: MetaInfo, metaInfo2: MetaInfo, vararg infos: MetaInfo): CompositeMetaInfo =
     CompositeMetaInfoBuilderImpl(infos.toMutableSet().apply {

kstatemachine/src/commonMain/kotlin/ru/nsk/kstatemachine/metainfo/UmlMetaInfo.kt

@@ -9,6 +9,9 @@ package ru.nsk.kstatemachine.metainfo
 
 import ru.nsk.kstatemachine.state.IState
 import ru.nsk.kstatemachine.transition.Transition
+import kotlin.contracts.ExperimentalContracts
+import kotlin.contracts.InvocationKind
+import kotlin.contracts.contract
 
 /**
  * Standard [MetaInfo], to control export PlantUML and Mermaid feature visualization.
@@ -53,5 +56,10 @@ private data class UmlMetaInfoBuilderImpl(
     override var umlNotes: List<String> = emptyList(),
 ) : UmlMetaInfoBuilder
 
-fun buildUmlMetaInfo(builder: UmlMetaInfoBuilder.() -> Unit): UmlMetaInfo =
-    UmlMetaInfoBuilderImpl().apply(builder).copy()
+@OptIn(ExperimentalContracts::class)
+fun buildUmlMetaInfo(builder: UmlMetaInfoBuilder.() -> Unit): UmlMetaInfo {
+    contract {
+        callsInPlace(builder, InvocationKind.EXACTLY_ONCE)
+    }
+    return UmlMetaInfoBuilderImpl().apply(builder).copy()
+}

kstatemachine/src/commonMain/kotlin/ru/nsk/kstatemachine/state/IState.kt

@@ -5,24 +5,23 @@
  * All rights reserved.
  */
 
+@file:OptIn(ExperimentalContracts::class)
+
 package ru.nsk.kstatemachine.state
 
-import ru.nsk.kstatemachine.event.DataExtractor
-import ru.nsk.kstatemachine.event.defaultDataExtractor
 import ru.nsk.kstatemachine.metainfo.MetaInfo
-import ru.nsk.kstatemachine.state.pseudo.DefaultChoiceDataState
-import ru.nsk.kstatemachine.state.pseudo.DefaultChoiceState
-import ru.nsk.kstatemachine.state.pseudo.DefaultHistoryState
 import ru.nsk.kstatemachine.statemachine.StateMachine
 import ru.nsk.kstatemachine.statemachine.StateMachineDslMarker
-import ru.nsk.kstatemachine.transition.EventAndArgument
 import ru.nsk.kstatemachine.transition.TransitionDirection
 import ru.nsk.kstatemachine.transition.TransitionDirectionProducerPolicy
 import ru.nsk.kstatemachine.transition.TransitionParams
 import ru.nsk.kstatemachine.visitors.CoVisitor
 import ru.nsk.kstatemachine.visitors.GetActiveStatesVisitor
 import ru.nsk.kstatemachine.visitors.Visitor
 import ru.nsk.kstatemachine.visitors.VisitorAcceptor
+import kotlin.contracts.ExperimentalContracts
+import kotlin.contracts.InvocationKind
+import kotlin.contracts.contract
 import kotlin.reflect.KClass
 
 /**
@@ -41,6 +40,7 @@ interface IState : TransitionStateApi, VisitorAcceptor {
     val isFinished: Boolean
     val listeners: Collection<Listener>
     val childMode: ChildMode
+
     /**
      * Might be changed only during machine setup.
      */
@@ -91,9 +91,12 @@ interface IState : TransitionStateApi, VisitorAcceptor {
     }
 }
 
-suspend fun <S : IState> IState.addState(state: S, init: StateBlock<S>? = null): S {
+suspend inline fun <S : IState> IState.addState(state: S, init: StateBlock<S>): S {
+    contract {
+        callsInPlace(init, InvocationKind.EXACTLY_ONCE)
+    }
     addState(state)
-    if (init != null) state.init()
+    state.init()
     return state
 }
 
@@ -238,104 +241,4 @@ inline fun <reified S : IState> IState.requireState(recursive: Boolean = true) =
 
 suspend operator fun <S : IState> S.invoke(block: StateBlock<S>) = block()
 
-fun IState.machineOrNull(): StateMachine? = if (this is StateMachine) this else parent?.machineOrNull()
-
-/**
- * @param name is optional and is useful for getting state instance after state machine setup
- * with [IState.findState] and for debugging.
- */
-suspend fun IState.state(
-    name: String? = null,
-    childMode: ChildMode = ChildMode.EXCLUSIVE,
-    init: StateBlock<State>? = null
-) = addState(DefaultState(name, childMode), init)
-
-suspend inline fun <reified D : Any> IState.dataState(
-    name: String? = null,
-    defaultData: D? = null,
-    childMode: ChildMode = ChildMode.EXCLUSIVE,
-    dataExtractor: DataExtractor<D> = defaultDataExtractor(),
-    noinline init: StateBlock<DataState<D>>? = null
-) = addState(defaultDataState(name, defaultData, childMode, dataExtractor), init)
-
-/**
- * A shortcut for [state] and [IState.setInitialState] calls
- */
-suspend fun IState.initialState(
-    name: String? = null,
-    childMode: ChildMode = ChildMode.EXCLUSIVE,
-    init: StateBlock<State>? = null
-) = addInitialState(DefaultState(name, childMode), init)
-
-/**
- * @param defaultData is necessary for initial [DataState]
- */
-suspend inline fun <reified D : Any> IState.initialDataState(
-    name: String? = null,
-    defaultData: D,
-    childMode: ChildMode = ChildMode.EXCLUSIVE,
-    dataExtractor: DataExtractor<D> = defaultDataExtractor(),
-    noinline init: StateBlock<DataState<D>>? = null
-) = addInitialState(defaultDataState(name, defaultData, childMode, dataExtractor), init)
-
-/**
- * A shortcut for [IState.addState] and [IState.setInitialState] calls
- */
-suspend fun <S : IState> IState.addInitialState(state: S, init: StateBlock<S>? = null): S {
-    addState(state, init)
-    setInitialState(state)
-    return state
-}
-
-/**
- * Helper dsl method for adding final states. This is exactly the same as simply call [IState.addState] but makes
- * code more self expressive.
- */
-suspend fun <S : IFinalState> IState.addFinalState(state: S, init: StateBlock<S>? = null) =
-    addState(state, init)
-
-suspend fun IState.finalState(name: String? = null, init: StateBlock<FinalState>? = null) =
-    addFinalState(DefaultFinalState(name), init)
-
-suspend fun IState.initialFinalState(name: String? = null, init: StateBlock<FinalState>? = null) =
-    addInitialState(DefaultFinalState(name), init)
-
-suspend inline fun <reified D : Any> IState.finalDataState(
-    name: String? = null,
-    defaultData: D? = null,
-    dataExtractor: DataExtractor<D> = defaultDataExtractor(),
-    noinline init: StateBlock<FinalDataState<D>>? = null
-) = addFinalState(defaultFinalDataState(name, defaultData, dataExtractor), init)
-
-suspend inline fun <reified D : Any> IState.initialFinalDataState(
-    name: String? = null,
-    defaultData: D? = null,
-    dataExtractor: DataExtractor<D> = defaultDataExtractor(),
-    noinline init: StateBlock<FinalDataState<D>>? = null
-) = addInitialState(defaultFinalDataState(name, defaultData, dataExtractor), init)
-
-fun IState.choiceState(
-    name: String? = null,
-    choiceAction: suspend EventAndArgument<*>.() -> State
-) = addState(DefaultChoiceState(name, choiceAction = choiceAction))
-
-suspend fun IState.initialChoiceState(
-    name: String? = null,
-    choiceAction: suspend EventAndArgument<*>.() -> State
-) = addInitialState(DefaultChoiceState(name, choiceAction = choiceAction))
-
-inline fun <reified D : Any> IState.choiceDataState(
-    name: String? = null,
-    noinline choiceAction: suspend EventAndArgument<*>.() -> DataState<D>
-) = addState(DefaultChoiceDataState(name, D::class, choiceAction = choiceAction))
-
-suspend inline fun <reified D : Any> IState.initialChoiceDataState(
-    name: String? = null,
-    noinline choiceAction: suspend EventAndArgument<*>.() -> DataState<D>
-) = addInitialState(DefaultChoiceDataState(name, D::class, choiceAction = choiceAction))
-
-fun IState.historyState(
-    name: String? = null,
-    defaultState: IState? = null,
-    historyType: HistoryType = HistoryType.SHALLOW,
-) = addState(DefaultHistoryState(name, defaultState, historyType))
+fun IState.machineOrNull(): StateMachine? = this as? StateMachine ?: parent?.machineOrNull()