Deprecate Parser.flatMap() in favor of Parser.transformEither()

tribune-core/src/main/kotlin/com/sksamuel/tribune/core/booleans/booleans.kt

@@ -3,15 +3,15 @@ package com.sksamuel.tribune.core.booleans
 import arrow.core.leftNel
 import arrow.core.right
 import com.sksamuel.tribune.core.Parser
-import com.sksamuel.tribune.core.flatMap
 import com.sksamuel.tribune.core.map
+import com.sksamuel.tribune.core.transformEither
 
 /**
  * Transforms a String producing [Parser] into a Boolean producing Parser,
  * by converting the String to a Boolean using the library function [toBoolean].
  */
 fun <I, E> Parser<I, String, E>.boolean(): Parser<I, Boolean, E> =
-   flatMap {
+   transformEither {
       val b = it.toBoolean()
       b.right()
    }
@@ -21,7 +21,7 @@ fun <I, E> Parser<I, String, E>.boolean(): Parser<I, Boolean, E> =
  * by converting the String to a Boolean using the library function [toBooleanStrict].
  */
 fun <I, E> Parser<I, String, E>.booleanStrict(ifError: (String) -> E): Parser<I, Boolean, E> =
-   flatMap { input ->
+   transformEither { input ->
       runCatching { input.toBooleanStrict() }.fold({ it.right() }, { ifError(input).leftNel() })
    }
 

tribune-core/src/main/kotlin/com/sksamuel/tribune/core/doubles/doubles.kt

@@ -4,7 +4,7 @@ import arrow.core.leftNel
 import arrow.core.right
 import com.sksamuel.tribune.core.Parser
 import com.sksamuel.tribune.core.filter
-import com.sksamuel.tribune.core.flatMap
+import com.sksamuel.tribune.core.transformEither
 
 /**
  * Extends a [Parser] of output type string to parse that string into a double.
@@ -15,18 +15,18 @@ import com.sksamuel.tribune.core.flatMap
  * and a null is considered a failing case.
  */
 fun <I, E> Parser<I, String, E>.double(ifError: (String) -> E): Parser<I, Double, E> =
-   flatMap {
+   transformEither {
       val d = it.toDoubleOrNull()
       d?.right() ?: ifError(it).leftNel()
    }
 
 fun <I, E> Parser<I, Double, E>.positive(ifError: (Double) -> E): Parser<I, Double, E> =
-   flatMap {
+   transformEither {
       if (it > 0.0) it.right() else ifError(it).leftNel()
    }
 
 fun <I, E> Parser<I, Double, E>.negative(ifError: (Double) -> E): Parser<I, Double, E> =
-   flatMap {
+   transformEither {
       if (it < 0.0) it.right() else ifError(it).leftNel()
    }
 
@@ -40,6 +40,6 @@ fun <I, E> Parser<I, Double, E>.inrange(
    range: ClosedFloatingPointRange<Double>,
    ifError: (Double) -> E,
 ): Parser<I, Double, E> =
-   flatMap {
+   transformEither {
       if (it in range) it.right() else ifError(it).leftNel()
    }

tribune-core/src/main/kotlin/com/sksamuel/tribune/core/enums/enums.kt

@@ -4,7 +4,7 @@ import arrow.core.Either
 import arrow.core.leftNel
 import arrow.core.right
 import com.sksamuel.tribune.core.Parser
-import com.sksamuel.tribune.core.flatMap
+import com.sksamuel.tribune.core.transformEither
 import kotlin.reflect.KClass
 
 /**
@@ -23,13 +23,13 @@ inline fun <I, reified ENUM : Enum<ENUM>, E> Parser<I, String, E>.enum(noinline
  * @param enumClass the KClass corresponding to the enum type.
  */
 fun <I, T : Enum<T>, E> Parser<I, String, E>.enum(
-   enumClass: KClass<T>,
-   ifError: (String) -> E,
+    enumClass: KClass<T>,
+    ifError: (String) -> E,
 ): Parser<I, T, E> {
-   return flatMap { symbol ->
-      runCatching { enumClass.java.enumConstants.first { it.name == symbol } }
-         .fold({ it.right() }, { ifError(symbol).leftNel() })
-   }
+    return transformEither { symbol ->
+        runCatching { enumClass.java.enumConstants.first { it.name == symbol } }
+            .fold({ it.right() }, { ifError(symbol).leftNel() })
+    }
 }
 
 /**
@@ -50,12 +50,12 @@ inline fun <I, reified ENUM : Enum<ENUM>, E> Parser<I, String?, E>.enum(noinline
  */
 @JvmName("enumOrNull")
 fun <I, T : Enum<T>, E> Parser<I, String?, E>.enum(
-   enumClass: KClass<T>,
-   ifError: (String) -> E
+    enumClass: KClass<T>,
+    ifError: (String) -> E
 ): Parser<I, T?, E> {
-   return flatMap { symbol ->
-      if (symbol == null) Either.Right(null)
-      else runCatching { enumClass.java.enumConstants.first { it.name == symbol } }
-         .fold({ it.right() }, { ifError(symbol).leftNel() })
-   }
+    return transformEither { symbol ->
+        if (symbol == null) Either.Right(null)
+        else runCatching { enumClass.java.enumConstants.first { it.name == symbol } }
+            .fold({ it.right() }, { ifError(symbol).leftNel() })
+    }
 }

tribune-core/src/main/kotlin/com/sksamuel/tribune/core/filter.kt

@@ -18,7 +18,7 @@ import arrow.core.right
  * @return a parser which rejects input based on the result of predicate [p]
  */
 fun <I, O, E> Parser<I, O, E>.filter(p: (O) -> Boolean, ifFalse: (O) -> E): Parser<I, O, E> {
-   return flatMap { if (p(it)) it.right() else ifFalse(it).leftNel() }
+    return transformEither { if (p(it)) it.right() else ifFalse(it).leftNel() }
 }
 
 /**
@@ -31,8 +31,8 @@ fun <I, O, E> Parser<I, O, E>.filter(p: (O) -> Boolean, ifFalse: (O) -> E): Pars
  *
  * @return a parser which rejects input based on the result of predicate [p]
  */
-fun <I, O : Any, E> Parser<I, O, E>.nullIf(fn: (O) -> Boolean): Parser<I, O?, E> =
-   this.map { if (fn(it)) null else it }
+fun <I, O : Any, E> Parser<I, O, E>.nullIf(p: (O) -> Boolean): Parser<I, O?, E> =
+   this.map { if (p(it)) null else it }
 
 /**
  * Returns a [Parser] that produces a null if the input value fails to pass the predicate [p].
@@ -47,6 +47,6 @@ fun <I, O : Any, E> Parser<I, O, E>.nullIf(fn: (O) -> Boolean): Parser<I, O?, E>
  * @return a parser which rejects input based on the result of predicate [p]
  */
 @JvmName("nullIfNullable")
-fun <I, O, E> Parser<I, O?, E>.nullIf(fn: (O) -> Boolean): Parser<I, O?, E> =
-   this.map { if (it == null || fn(it)) null else it }
+fun <I, O, E> Parser<I, O?, E>.nullIf(p: (O) -> Boolean): Parser<I, O?, E> =
+   this.map { if (it == null || p(it)) null else it }
 

tribune-core/src/main/kotlin/com/sksamuel/tribune/core/floats/floats.kt

@@ -3,7 +3,7 @@ package com.sksamuel.tribune.core.floats
 import arrow.core.leftNel
 import arrow.core.right
 import com.sksamuel.tribune.core.Parser
-import com.sksamuel.tribune.core.flatMap
+import com.sksamuel.tribune.core.transformEither
 
 /**
  * Extends a [Parser] of output type string to parse that string into a double.
@@ -14,7 +14,7 @@ import com.sksamuel.tribune.core.flatMap
  * and a null is considered a failing case.
  */
 fun <I, E> Parser<I, String, E>.float(ifError: (String) -> E): Parser<I, Float, E> =
-   flatMap {
+   transformEither {
       val f = it.toFloatOrNull()
       f?.right() ?: ifError(it).leftNel()
    }

tribune-core/src/main/kotlin/com/sksamuel/tribune/core/ints/ints.kt

@@ -5,13 +5,13 @@ import arrow.core.leftNel
 import arrow.core.right
 import com.sksamuel.tribune.core.Parser
 import com.sksamuel.tribune.core.filter
-import com.sksamuel.tribune.core.flatMap
+import com.sksamuel.tribune.core.transformEither
 
 /**
  * Chains a [Parser] to convert String -> Int.
  */
 fun <I, E> Parser<I, String, E>.int(ifError: (String) -> E): Parser<I, Int, E> =
-   flatMap {
+   transformEither {
       val i = it.toIntOrNull()
       i?.right() ?: ifError(it).leftNel()
    }
@@ -30,33 +30,33 @@ fun <I, E> Parser<I, Int, E>.nonNegative(ifError: (Int) -> E): Parser<I, Int, E>
 
 
 fun <I, E> Parser<I, Int, E>.negative(ifError: (Int) -> E): Parser<I, Int, E> =
-   flatMap {
+   transformEither {
       if (it < 0) it.right() else ifError(it).leftNel()
    }
 
 fun <I, E> Parser<I, Int, E>.inrange(range: IntRange, ifError: (Int) -> E): Parser<I, Int, E> =
-   flatMap {
+   transformEither {
       if (it in range) it.right() else ifError(it).leftNel()
    }
 
 fun <I, E> Parser<I, Int, E>.min(min: Int, ifError: (Int) -> E): Parser<I, Int, E> =
-   flatMap {
+   transformEither {
       if (it >= min) it.right() else ifError(it).leftNel()
    }
 
 @JvmName("minOrNull")
 fun <I, E> Parser<I, Int?, E>.min(min: Int, ifError: (Int) -> E): Parser<I, Int?, E> =
-   flatMap {
+   transformEither {
       if (it == null) Either.Right(null) else if (it >= min) it.right() else ifError(it).leftNel()
    }
 
 fun <I, E> Parser<I, Int, E>.max(min: Int, ifError: (Int) -> E): Parser<I, Int, E> =
-   flatMap {
+   transformEither {
       if (it >= min) it.right() else ifError(it).leftNel()
    }
 
 @JvmName("maxOrNull")
 fun <I, E> Parser<I, Int?, E>.max(min: Int, ifError: (Int) -> E): Parser<I, Int?, E> =
-   flatMap {
+   transformEither {
       if (it == null) Either.Right(null) else if (it >= min) it.right() else ifError(it).leftNel()
    }

tribune-core/src/main/kotlin/com/sksamuel/tribune/core/longs/longs.kt

@@ -4,8 +4,8 @@ import arrow.core.Either
 import arrow.core.leftNel
 import arrow.core.right
 import com.sksamuel.tribune.core.Parser
-import com.sksamuel.tribune.core.flatMap
 import com.sksamuel.tribune.core.map
+import com.sksamuel.tribune.core.transformEither
 
 /**
  * Extends a [Parser] of output type string to parse that string into a long.
@@ -16,34 +16,34 @@ import com.sksamuel.tribune.core.map
  * and a null is considered a failing case.
  */
 fun <I, E> Parser<I, String, E>.long(ifError: (String) -> E): Parser<I, Long, E> =
-   flatMap {
+   transformEither {
       val l = it.toLongOrNull()
       l?.right() ?: ifError(it).leftNel()
    }
 
 fun <I, E> Parser<I, Long, E>.inrange(range: LongRange, ifError: (Long) -> E): Parser<I, Long, E> =
-   flatMap {
+   transformEither {
       if (it in range) it.right() else ifError(it).leftNel()
    }
 
 fun <I, E> Parser<I, Long, E>.min(min: Long, ifError: (Long) -> E): Parser<I, Long, E> =
-   flatMap {
+   transformEither {
       if (it >= min) it.right() else ifError(it).leftNel()
    }
 
 fun <I, E> Parser<I, Long, E>.max(min: Long, ifError: (Long) -> E): Parser<I, Long, E> =
-   flatMap {
+   transformEither {
       if (it >= min) it.right() else ifError(it).leftNel()
    }
 
 @JvmName("minOrNull")
 fun <I, E> Parser<I, Long?, E>.min(min: Long, ifError: (Long) -> E): Parser<I, Long?, E> =
-   flatMap {
+   transformEither {
       if (it == null) Either.Right(null) else if (it >= min) it.right() else ifError(it).leftNel()
    }
 
 @JvmName("maxOrNull")
 fun <I, E> Parser<I, Long?, E>.max(min: Long, ifError: (Long) -> E): Parser<I, Long?, E> =
-   flatMap {
+   transformEither {
       if (it == null) Either.Right(null) else if (it >= min) it.right() else ifError(it).leftNel()
    }

tribune-core/src/main/kotlin/com/sksamuel/tribune/core/map.kt

@@ -36,5 +36,23 @@ fun <I, A, B, E> Parser<I, A?, E>.mapIfNotNull(f: (A) -> B): Parser<I, B?, E> =
  *
  * @return a parser which returns the modified and flattened result of this parser.
  */
+@JvmName("deprecatedFlatMap")
+@Deprecated(message = "Deprecated. Use transformEither()", replaceWith = ReplaceWith("transformEither(f)"))
 fun <I, A, B, E> Parser<I, A, E>.flatMap(f: (A) -> EitherNel<E, B>): Parser<I, B, E> =
    Parser { [email protected](it).flatMap(f) }
+
+/**
+ * Returns a [Parser] that maps the result of this parser by invoking the given function [f]
+ * and flattening the output of that function.
+ *
+ * @param f the function invoked to map the output of the underlying parser.
+ *
+ * @return a parser which returns the modified and flattened result of this parser.
+ */
+fun <I, O, E : E2, O2, E2> Parser<I, O, E>.transformEither(f: (O) -> EitherNel<E2, O2>): Parser<I, O2, E2> =
+   Parser { [email protected](it).flatMap(f) }
+
+fun <I, O, E : E2, I2 : I, O2, E2> Parser<I, O, E>.flatMap(f: (O) -> Parser<I2, O2, E2>): Parser<I2, O2, E2> =
+   Parser { i ->
+      parse(i).flatMap { o -> f(o).parse(i) }
+   }

tribune-core/src/main/kotlin/com/sksamuel/tribune/core/maps/maps.kt

@@ -2,16 +2,16 @@ package com.sksamuel.tribune.core.maps
 
 import arrow.core.sequence
 import com.sksamuel.tribune.core.Parser
-import com.sksamuel.tribune.core.flatMap
+import com.sksamuel.tribune.core.transformEither
 
 fun <I, K, V, R, E> Parser<I, Map<K, V>, E>.parseKeys(parser: Parser<K, R, E>): Parser<I, Map<R, V>, E> {
-   return this.flatMap { input ->
-      input.map { (key, value) -> parser.parse(key).map { Pair(it, value) } }.sequence().map { it.toMap() }
-   }
+    return this.transformEither { input ->
+        input.map { (key, value) -> parser.parse(key).map { Pair(it, value) } }.sequence().map { it.toMap() }
+    }
 }
 
 fun <I, K, V, R, E> Parser<I, Map<K, V>, E>.parseValues(parser: Parser<V, R, E>): Parser<I, Map<K, R>, E> {
-   return this.flatMap { input ->
-      input.map { (key, value) -> parser.parse(value).map { Pair(key, it) } }.sequence().map { it.toMap() }
-   }
+    return this.transformEither { input ->
+        input.map { (key, value) -> parser.parse(value).map { Pair(key, it) } }.sequence().map { it.toMap() }
+    }
 }

tribune-core/src/main/kotlin/com/sksamuel/tribune/core/strings/lengths.kt

@@ -4,7 +4,7 @@ import arrow.core.Either
 import arrow.core.leftNel
 import arrow.core.right
 import com.sksamuel.tribune.core.Parser
-import com.sksamuel.tribune.core.flatMap
+import com.sksamuel.tribune.core.transformEither
 
 /**
  * Narrows an existing String -> String [Parser] by enforcing an exact length on the input string.
@@ -18,7 +18,7 @@ import com.sksamuel.tribune.core.flatMap
  * @return valid if the input string is less than or equal to [len] or an invalid otherwise.
  */
 fun <I, E> Parser<I, String, E>.length(len: Int, ifError: (String) -> E): Parser<I, String, E> =
-   flatMap {
+   transformEither {
       when (it.length) {
          len -> it.right()
          else -> ifError(it).leftNel()
@@ -38,7 +38,7 @@ fun <I, E> Parser<I, String, E>.length(len: Int, ifError: (String) -> E): Parser
  */
 @JvmName("lengthOrNull")
 fun <I, E> Parser<I, String?, E>.length(len: Int, ifError: (String) -> E): Parser<I, String?, E> =
-   flatMap {
+   transformEither {
       when {
          it == null -> Either.Right(null)
          it.length == len -> it.right()
@@ -58,7 +58,7 @@ fun <I, E> Parser<I, String?, E>.length(len: Int, ifError: (String) -> E): Parse
  * @return valid if the input string has acceptable length or an invalid otherwise.
  */
 fun <I, E> Parser<I, String, E>.length(f: (Int) -> Boolean, ifError: (String) -> E): Parser<I, String, E> =
-   flatMap { if (f(it.length)) it.right() else ifError(it).leftNel() }
+   transformEither { if (f(it.length)) it.right() else ifError(it).leftNel() }
 
 /**
  * Narrows an existing I -> String? [Parser] by enforcing a max length on the input string.
@@ -73,7 +73,7 @@ fun <I, E> Parser<I, String, E>.length(f: (Int) -> Boolean, ifError: (String) ->
  */
 @JvmName("maxlenOrNull")
 fun <I, E> Parser<I, String?, E>.maxlen(len: Int, ifError: (String) -> E): Parser<I, String?, E> =
-   flatMap {
+   transformEither {
       when {
          it == null -> Either.Right(null)
          it.length > len -> ifError(it).leftNel()
@@ -93,7 +93,7 @@ fun <I, E> Parser<I, String?, E>.maxlen(len: Int, ifError: (String) -> E): Parse
  * @return valid if the input string is less than or equal to [len] or an invalid otherwise.
  */
 fun <I, E> Parser<I, String, E>.maxlen(len: Int, ifError: (String) -> E): Parser<I, String, E> =
-   flatMap {
+   transformEither {
       when {
          it.length > len -> ifError(it).leftNel()
          else -> it.right()
@@ -113,7 +113,7 @@ fun <I, E> Parser<I, String, E>.maxlen(len: Int, ifError: (String) -> E): Parser
  * @return valid if the input string is greater than or equal to [len] or an invalid otherwise.
  */
 fun <I, E> Parser<I, String, E>.minlen(len: Int, ifError: (String) -> E): Parser<I, String, E> =
-   flatMap {
+   transformEither {
       when {
          it.length < len -> ifError(it).leftNel()
          else -> it.right()
@@ -133,7 +133,7 @@ fun <I, E> Parser<I, String, E>.minlen(len: Int, ifError: (String) -> E): Parser
  */
 @JvmName("minlenOrNull")
 fun <I, E> Parser<I, String?, E>.minlen(len: Int, ifError: (String) -> E): Parser<I, String?, E> =
-   flatMap {
+   transformEither {
       when {
          it == null -> Either.Right(null)
          it.length < len -> ifError(it).leftNel()