GitHub - nsk90/kstatemachine: KStateMachine is a Kotlin DSL library for creating...

KStateMachine is a Kotlin DSL library for creating state machines and hierarchical state machines (statecharts).

Overview

Main features are:

• Zero dependency. It is written in pure Kotlin, it does not depend on any other libraries or Android SDK
• Kotlin DSL syntax for defining state machine structure. Using without DSL is also possible
• Backward compatible till Kotlin 1.4
• Event based - transitions are performed by processing incoming events
• Listeners for machine, states, state groups and transitions. Listener callbacks are shipped with information about current transition
• Guarded and Conditional transitions with dynamic target state which is calculated in a moment of event processing depending on application business logic
• Nested states - hierarchical state machines (HSMs) with cross-level transitions support
• Composed (nested) state machines. Use state machines as atomic child states
• Pseudo states for additional logic in machine behaviour
• Typesafe transitions to pass data in typesafe way from event to state
• Parallel states to avoid a combinatorial explosion of states
• Undo transitions for navigating back to previous state
• Argument passing for events and transitions
• Pending events support
• Export state machine structure to PlantUML;
• Built-in logging support
• Testable - you can run state machine from specified state
• Well tested. All features are covered by tests.

The library is currently in a development phase. You are welcome to propose useful features.

Don't forget to push the if you like this project.

SEE FULL DOCUMENTATION HERE

Quick start sample (finishing traffic light)

object SwitchEvent : Event

sealed class States : DefaultState() {
    object GreenState : States()
    object YellowState : States()
    object RedState : States(), FinalState // Machine finishes when enters final state
}

fun main() {
    // Create state machine and configure its states in a setup block
    val machine = createStateMachine {
        addInitialState(GreenState) {
            // Add state listeners
            onEntry { println("Enter green") }
            onExit { println("Exit green") }

            // Setup transition
            transition<SwitchEvent> {
                targetState = YellowState
                // Add transition listener
                onTriggered { println("Transition triggered") }
            }
        }

        addState(YellowState) {
            transition<SwitchEvent>(targetState = RedState)
        }

        addFinalState(RedState)

        onFinished { println("Finished") }
    }

    // Now we can process events
    machine.processEvent(SwitchEvent)
    machine.processEvent(SwitchEvent)
}

Samples

Install

KStateMachine is available on Maven Central and JitPack repositories.

Maven Central

Add the dependency:

dependencies {
    implementation 'io.github.nsk90:kstatemachine:<Tag>'
}

dependencies {
    implementation("io.github.nsk90:kstatemachine:<Tag>")
}

Where <Tag> is a library version.

JitPack

Add the JitPack repository to your build file. Add it in your root build.gradle at the end of repositories:

// groovy
allprojects {
    repositories {
        //  ...
        maven { url 'https://jitpack.io' }
    }
}

// kotlin
repositories {
    //  ...
    maven { url = uri("https://jitpack.io") }
}

Add the dependency:

// groovy
dependencies {
    implementation 'com.github.nsk90:kstatemachine:<Tag>'
}

// kotlin
dependencies {
    implementation("com.github.nsk90:kstatemachine:<Tag>")
}

Where <Tag> is a library version.

Build

Run ./gradlew build or build with Intellij IDEA.

To run tests from IDE download official Kotest plugin.

Licensed under permissive Boost Software License

Thanks to supporters