README.md

Simple State Machines in Kotlin (KSSM)

What is this?

KSSM (reordered: Kotlin - Simple State Machines) provides an easy and simple DSL (Domain Specific Language) for setting up finite-state machines, and opens a clean API with built-in threading and conflation mechanisms for manipulating states. This library does not solve all state machine problems, nor does it aim to address all possible use-cases related to state machines. It currently works only in the JVM environment.

KSSM is based on the Flow API from Kotlin's coroutine package, more precisely on State Flow.

Quick Intro

Here's a short introduction on how KSSM works. Click here to go at your own pace in presentation mode.

KSSM DSL looks like this (assuming actions and states are defined):

val sm = stateMachine {
  mappings(
    Heat moves Ice to Liquid,
    Chill moves Steam to Liquid,
    Drink moves Liquid to Empty,
    Fill moves Empty to Liquid
  )
  
  transitionsDispatcher = Dispatchers.Main // optional
  
  initialState = Empty // optional
  
  transitionHandler { println("Detected change: $it\n") } // optional
  errorHandler { err.println("Invalid request: $it\n") } // optional
  
  // other config...
}

// send inputs/actions to that instance
val job = sm.transition(Fill)
job.join() // or job.cancel(), or simply ignore

Wiki

If you prefer longer documentation, check out the longer version of the docs.

You want more? There are code samples in the demo directory that showcase the most interesting features of this library.

How to install KSSM?

It's hosted on JCenter and MavenCentral, and thus easy to depend upon with Gradle:

dependencies {
  // find the latest `$kssm_version` on the top of this page
  implementation "me.angrybyte:kssm:$kssm_version"
}

Contributing & Code of Conduct

Please open a new issue with any requests, issues, complaints or any other type of communication. For sensitive or security-related topics, don't hesitate to reach out to any maintainer directly.