Fixed do notation label hack;

Updated README.md;
Updated to 1.1.0-beta-22.

Author: h0tk3y

README.md

@@ -1,18 +1,19 @@
 # kotlin-monads
 
-[![](https://jitpack.io/v/h0tk3y/kotlin-monads.svg)](https://jitpack.io/#h0tk3y/kotlin-monads) [![](https://img.shields.io/badge/kotlin-1.1--M04-blue.svg)](http://kotlinlang.org/)
+[![](https://jitpack.io/v/h0tk3y/kotlin-monads.svg)](https://jitpack.io/#h0tk3y/kotlin-monads) [![](https://img.shields.io/badge/kotlin-1.1--beta--22-blue.svg)](http://kotlinlang.org/)
 
-An attempt to implement monads in Kotlin.
+An attempt to implement monads in Kotlin, deeply inspired by Haskell monads, but restricted within the Kotlin type system.
 
-_Note: this project uses Kotlin 1.1 EAP build. Use the 1.1 EAP IDE plugin to work with it._
+_Note: this project uses Kotlin 1.1 Beta build. Use the 1.1 Beta IDE plugin to work with it._
 
 ## The monad type
 
 Monadic types are represented by the `Monad<M, T>` interface, 
-where `M` **should be the type of the implementation** with its `T` star-projected. Examples: `Maybe<T> : Monad<Maybe<*>, T>`, `State<S, T> : Monad<State<S, *>, T>`. 
+where `M` **should be the type of the implementation** with only its `T` star-projected. Examples: `Maybe<T> : Monad<Maybe<*>, T>`, `State<S, T> : Monad<State<S, *>, T>`. 
 
-The purpose is: with `Monad` defined in this way, we
-are almost able to say that a function returns the same `Monad` implementation but with a different type parameter:
+With `Monad` defined in this way, we
+are almost able to say in terms of the Kotlin type system that a function returns the same `Monad` implementation but 
+with a different type argument `R` instead of `T`:
 
     fun <T, R, M : Monad<M, *>> Monad<M, T>.map(f: (T) -> R) = bind { returns(f(it)) }
 
@@ -49,13 +50,20 @@ See the usage examples in [tests](https://github.com/h0tk3y/kotlin-monads/tree/m
 
 The monad implementation should only provide one function `bind` (Haskell: `>>=`), 
 no separate `return` is there, instead, if you look at the signature of `bind`, you'll see that the function to bind with is `f: Return<This>.(T) -> Monad<This, R>`. 
-
-It means that a monad implementation should provide the `Return<M>` as well and pass it to `f` each time, so that inside `f` its `returns` could be used:
+It means that a `Monad<M, T>` implementation should provide the `Return<M>` as well and pass it to `f` each time, so that inside `f` its `returns` could be used:
 
     just(3) bind { returns(it * it) }
 
-I found no direct equivalent to `return` in Haskell, which could be used even outside bind functions. Outside the `bind` blocks, you should either
-wrap the values into your monads manually or require a `Return<M>`, which can wrap `T` into `Monad<M, T>` for you.
+There seems to be no direct equivalent to Haskell `return`, which could be used outside any context like `bind` blocks. Outside the `bind` blocks, you should either
+wrap the values into your monads manually or require a `Return<M>`, which can wrap `T` into `Monad<M, T>` for you. 
+
+Mind the [monad laws](https://wiki.haskell.org/Monad_laws). A correct monad implementation follows these three rules (rephrased in terms of `kotlin-monads`):
+
+1. **Left identity**: `returns(x) bind { f(it) }` should be equivalent to `f(x)`
+ 
+2. **Right identity**: `m bind { returns(it) }` should be equivalent to `m`
+
+3. **Associativity**: `m bind { f(it) } bind { g(it) }` should be equivalent to `m bind { f(it) bind { g(it) } }`
 
 Also, it's good to make the return type of `bind` narrower, e.g. `bind` of `Maybe<T>` would rather return `Maybe<R>` than `Monad<Maybe<*>, R>`, it allows not to cast 
 the result of a `bind` called on a known monad type.
@@ -89,21 +97,46 @@ Example implementation:
 
 ## Do notation
 
-With the power of Kotlin coroutines, we can have a limited variant of do notation:
+With the power of Kotlin coroutines, we can even have an equivalent of the [*Haskell do notation*](https://en.wikibooks.org/wiki/Haskell/do_notation):
+
+Simple example that performs a monadic list nondeterministic expansion:
 
-    val m = doWith(monadListOf(0)) {
+    val m = doReturning(MonadListReturn) {
         val x = bind(monadListOf(1, 2, 3))
-        val y = bind(monadListOf(x, x))
-        then(monadListOf(y, y + 1))
-    } as MonadList
+        val y = bind(monadListOf(x, x + 1))
+        monadListOf(y, x * y)
+    }
 
     assertEquals(monadListOf(1, 2, 1, 2, 2, 3, 2, 3, 3, 4, 3, 4), m)
 
- The limitation is that the intermediate results in a single _do_ block are restricted to the same value type `T`. You can, however, use nested _do_ blocks to use different result types.
+Or applied to an existing monad for convenience:
+
+    val m = monadListOf(1, 2, 3).bindDo { x ->
+        val y = bind(monadListOf(x, x + 1))
+        monadListOf(y, x * y)
+    }
+    
+This is effectively equivalent to the following code written with only simple `bind`:
+
+    val m = monadListOf(1, 2, 3).bind { x ->
+        monadListOf(x, x + 1).bind { y -> 
+            monadList(y, x * y)
+        }
+    }
+    
+Note that, with simple `bind`, each *transformation* requires another inner scope if it uses the variables bound outside, 
+which would lead to some kind of callback hell. 
+This problem is effectively solved using the Kotlin coroutines: the compiler performs the CPS transformation of a plain
+ code block under the hood. However, this coroutines use case is somewhat out of conventions: it might resume the same continuation
+ several times and uses quite a dirty hack to do that.
+    
+The result type parameter (`R` in `Monad<M, R`) is usually inferred, and the compiler controls the flow inside a *do block*, but still you need to
+ downcast the `Monad<M, R>` to your actual monad type (e.g. `Monad<Maybe<*>, R>` to `Maybe<R>`), because the type system doesn't seem to allow this to be done
+ automatically (if you know a way, please tell me).
 
- **Be careful with mutable state** in _do_ blocks, since all continuation calls will share it, resulting into something unexpected:
+ **Be careful with mutable state** in _do_ blocks, since all continuation calls will share it, sometimes resulting into counter-intuitive results:
 
-     val m = doWith(monadListOf(0)) {
+     val m = doReturning(MonadListReturn) {
          for (i in 1..10)
              bind(monadListOf(0, 0))
      } as MonadList

build.gradle

@@ -1,5 +1,5 @@
 buildscript {
-    ext.kotlin_version = '1.1.0-beta-17'
+    ext.kotlin_version = '1.1.0-beta-22'
 
     repositories {
         mavenCentral()
@@ -20,7 +20,7 @@ repositories {
 dependencies {
     compile "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
     compile "org.jetbrains.kotlin:kotlin-reflect:$kotlin_version"
-    compile 'org.jetbrains.kotlinx:kotlinx-coroutines-core:0.3-beta'
+    compile 'org.jetbrains.kotlinx:kotlinx-coroutines-core:0.4-beta'
     testCompile "junit:junit:4.12"
 }
 

gradlew

@@ -161,7 +161,7 @@ function splitJvmOpts() {
 eval splitJvmOpts $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS
 JVM_OPTS[${#JVM_OPTS[*]}]="-Dorg.gradle.appname=$APP_BASE_NAME"
 
-# by default we should be in the correct project dir, but when run from Finder on Mac, the cwd is wrong
+# by default we should be in the correct project dir, but when runCont from Finder on Mac, the cwd is wrong
 if [[ "$(uname)" == "Darwin" ]] && [[ "$HOME" == "$PWD" ]]; then
   cd "$(dirname "$0")"
 fi

src/main/kotlin/com/github/h0tk3y/kotlinMonads/DoNotation.kt

@@ -2,99 +2,66 @@
 
 package com.github.h0tk3y.kotlinMonads
 
-import kotlinx.coroutines.experimental.Here
 import java.io.Serializable
-import java.util.*
 import kotlin.coroutines.Continuation
-import kotlin.coroutines.CoroutineContext
+import kotlin.coroutines.EmptyCoroutineContext
 import kotlin.coroutines.RestrictsSuspension
 import kotlin.coroutines.intrinsics.SUSPENDED_MARKER
 import kotlin.coroutines.intrinsics.suspendCoroutineOrReturn
 import kotlin.coroutines.startCoroutine
 
-fun <M : Monad<M, *>, T> doWith(m: Monad<M, T>,
-                                c: suspend DoController<M, T>.(T) -> Unit): Monad<M, T> =
-        m.bind { t -> doWith(this, t, c) }
+fun <M : Monad<M, *>, T, R> Monad<M, T>.bindDo(c: suspend DoController<M>.(T) -> Monad<M, R>): Monad<M, R> =
+        bind { t ->
+            val controller = DoController(this)
+            val f: suspend DoController<M>.() -> Monad<M, R> = { c(t) }
+            f.startCoroutine(controller, controller)
+            controller.returnedMonad as Monad<M, R>
+        }
 
-fun <M : Monad<M, *>, T> doWith(aReturn: Return<M>,
-                                defaultValue: T,
-                                c: suspend DoController<M, T>.(T) -> Unit): Monad<M, T> {
-    val controller = DoController(aReturn, defaultValue)
-    val f: suspend DoController<M, T>.() -> Unit = { c(defaultValue) }
-    f.startCoroutine(controller, object : Continuation<Unit> {
-        override fun resumeWithException(exception: Throwable) {}
-        override fun resume(value: Unit) {}
-        override val context: CoroutineContext = Here
-    })
-    return controller.lastResult
+fun <M : Monad<M, *>, R> doReturning(aReturn: Return<M>,
+                                     c: suspend DoController<M>.() -> Monad<M, R>): Monad<M, R> {
+    val controller = DoController(aReturn)
+    val f: suspend DoController<M>.() -> Monad<M, R> = { c() }
+    f.startCoroutine(controller, controller)
+    return controller.returnedMonad as Monad<M, R>
 }
 
 private val labelField by lazy {
     val jClass = Class.forName("kotlin.jvm.internal.CoroutineImpl")
     return@lazy jClass.getDeclaredField("label").apply { isAccessible = true }
 }
 
-private val innerContinuationField by lazy {
-    val jClass = Class.forName("kotlinx.coroutines.experimental.DispatchedContinuation")
-    return@lazy jClass.getDeclaredField("continuation").apply { isAccessible = true }
-}
-
 private var <T> Continuation<T>.label
-    get() = labelField.get(innerContinuationField.get(this))
-    set(value) = labelField.set(innerContinuationField.get(this@label), value)
-
-private fun <T, R> backupLabel(c: Continuation<T>, block: Continuation<T>.() -> R): R {
-    val backupLabel = c.label
-    val r = block(c)
-    c.label = backupLabel
-    return r
-}
+    get() = labelField.get(this)
+    set(value) = labelField.set(this@label, value)
 
 @RestrictsSuspension
-class DoController<M : Monad<M, *>, T>(val returning: Return<M>,
-                                       val value: T) : Serializable, Return<M> by returning {
-    var lastResult: Monad<M, T> = returning.returns(value)
-        internal set
+class DoController<M : Monad<M, *>>(private val returning: Return<M>) :
+        Serializable, Return<M> by returning, Continuation<Monad<M, *>> {
 
-    private val stackSignals = Stack<Boolean>().apply { push(false) }
+    override val context = EmptyCoroutineContext
 
-    suspend fun bind(m: Monad<M, T>): T = suspendCoroutineOrReturn { c ->
-        stackSignals.pop()
-        stackSignals.push(true)
-        var anyCont = false
-        val o = m.bind { x ->
-            stackSignals.push(false)
-            backupLabel(c) {
-                c.resume(x)
-            }
-            val contHasMonad = stackSignals.pop()
-            if (contHasMonad) {
-                anyCont = true
-                lastResult
-            } else {
-                returns(x)
-            }
-        }
-        lastResult = if (anyCont) o else m
-        SUSPENDED_MARKER
+    override fun resume(value: Monad<M, *>) {
+        returnedMonad = value //here is where the biggest magic happens
+    }
+
+    override fun resumeWithException(exception: Throwable) {
+        throw exception
     }
 
-    suspend fun then(m: Monad<M, T>) = suspendCoroutineOrReturn<Unit> { c ->
-        stackSignals.pop()
-        stackSignals.push(true)
-        var anyCont = false
-        val o = m.bind { x ->
-            stackSignals.push(false)
-            backupLabel(c) { c.resume(Unit) }
-            val contHasMonad = stackSignals.pop()
-            if (contHasMonad) {
-                anyCont = true
-                lastResult
-            } else {
-                returning.returns(x)
-            }
+    internal lateinit var returnedMonad: Monad<M, *>
+
+    suspend fun <T> bind(m: Monad<M, T>): T = suspendCoroutineOrReturn { c ->
+        val labelHere = c.label // save the label
+        returnedMonad = m.bind { x ->
+            c.label = labelHere
+            c.resume(x)
+            returnedMonad
         }
-        lastResult = if (anyCont) o else m
         SUSPENDED_MARKER
     }
+
+    suspend fun <T> then(m: Monad<M, T>): Unit {
+        bind(m)
+    }
 }

src/main/kotlin/com/github/h0tk3y/kotlinMonads/Maybe.kt

@@ -1,25 +1,25 @@
 package com.github.h0tk3y.kotlinMonads
 
 sealed class Maybe<out T> : Monad<Maybe<*>, T> {
-    data class Just<T>(val value: T) : Maybe<T>() {
-        override fun toString() = "Just $value"
-    }
-
     override fun <R> bind(f: Binder<Maybe<*>, T, R>): Maybe<R> = when (this) {
         is Just -> f(MaybeReturn, value) as Maybe
         is None -> none()
     }
+}
 
-    object None : Maybe<Nothing>() {
-        override fun toString() = "None"
-    }
+data class Just<T>(val value: T) : Maybe<T>() {
+    override fun toString() = "Just $value"
+}
+
+object None : Maybe<Nothing>() {
+    override fun toString() = "None"
 }
 
 object MaybeReturn : Return<Maybe<*>> {
-    override fun <T> returns(t: T) = just(t)
+    override fun <T> returns(t: T) = Just(t)
 }
 
 @Suppress("UNCHECKED_CAST")
-fun <T> none(): Maybe<T> = Maybe.None
+fun <T> none(): Maybe<T> = None
 
-fun <T> just(t: T) = Maybe.Just(t)
+fun <T> just(t: T) = Just(t)

src/test/kotlin/com/github/h0tk3y/kotlinMonads/DoNotationTest.kt

@@ -8,62 +8,48 @@ import org.junit.Test
 
 class DoNotationTest {
     @Test fun testLinearDo() {
-        val m = doWith(just(1)) {
-            val j = bind(returns(value * 2))
+        val m = just(1).bindDo { x ->
+            val j = bind(returns(x * 2))
             val k = bind(returns(j * 3))
-            then(returns(k + 1))
+            returns(k + 1)
         }
         assertEquals(just(7), m)
     }
 
     @Test fun testControlFlow() {
         var called = false
-        val m = doWith(just(1)) {
-            val j = bind(returns(value * 2))
+        val m = just(1).bindDo { x ->
+            val j = bind(returns(x * 2))
             val k = bind(if (j % 2 == 0) none() else just(j))
             called = true
-            then(returns(k))
+            returns(k)
         }
-        assertEquals(Maybe.None, m)
+        assertEquals(None, m)
         assertFalse(called)
     }
 
     @Test fun testMultipleBranches() {
         var iIterations = 0
         var jIterations = 0
-        var kIterations = 0
-        val m = doWith(monadListOf(0)) {
+        val m = doReturning(MonadListReturn) {
             val i = bind(monadListOf(1, 2, 3))
             ++iIterations
             val j = bind(monadListOf(i, i))
             ++jIterations
-            then(monadListOf(j, j + 1))
-            ++kIterations
+            monadListOf(j, j + 1)
         }
         assertEquals(monadListOf(1, 2, 1, 2, 2, 3, 2, 3, 3, 4, 3, 4), m)
         assertEquals(3, iIterations)
         assertEquals(6, jIterations)
-        assertEquals(12, kIterations)
     }
 
     @Test fun testMultipleApplications() {
-        val m = doWith(monadListOf(1)) {
-            then(monadListOf(1, 1))
+        val m = doReturning(MonadListReturn) {
             then(monadListOf(1, 1))
             then(monadListOf(1, 1))
             then(monadListOf(1, 1))
+            monadListOf(1, 1)
         } as MonadList
         assertEquals(16, m.size)
     }
-
-    @Test fun testBindLastStatement() {
-        val results = mutableListOf<Int>()
-        val m = doWith(monadListOf(2)) {
-            val x = bind(monadListOf(value + 1, value * value))
-            val z = bind(returns(x))
-            results.add(z)
-        }
-        assertEquals(listOf(3, 4), results)
-        assertEquals(results, m)
-    }
 }