Add spec method to Exact (#20)

* Change Exact to abstract class

* Fix README

* Turn Exact back to interface but keep spec function

* Change the position of example with delegation

* Fix documentation

* Pass ExactError on ensure

Co-authored-by: Simon Vergauwen <nomisRev@users.noreply.github.com>

---------

Co-authored-by: Simon Vergauwen <nomisRev@users.noreply.github.com>

README.md

@@ -1,4 +1,4 @@
-Module Arrow Exact
+# Arrow Exact
 
 Arrow Exact allows you to use Kotlin's type system to enforce exactness of data structures.
 
@@ -11,17 +11,19 @@ example easily create a `NotBlankString` type that is a `String` that is not bla
 the Arrow's `Raise` DSL to `ensure` the value is not blank.
 
 ```kotlin
+import arrow.core.raise.Raise
 import arrow.core.raise.ensure
 import arrow.exact.Exact
 import arrow.exact.ExactError
-import arrow.exact.exact
 
 @JvmInline
-value class NotBlankString private constructor(val value: String) {
-  companion object : Exact<String, NotBlankString> by exact({
-    ensure(raw.isNotBlank()) { ExactError("Cannot be blank.") }
-    NotBlankString(raw)
-  })
+value class NotBlankString private constructor(val value: String) { 
+  companion object : Exact<String, NotBlankString> {
+    override fun Raise<ExactError>.spec(raw: String): NotBlankString { 
+      ensure(raw.isNotBlank()) { ExactError("Cannot be blank.") }
+      return NotBlankString(raw)
+    }
+  }
 }
 ```
 
@@ -48,31 +50,54 @@ Either.Left(ExactError(message=Cannot be blank.))
 <!--- KNIT example-readme-01.kt -->
 <!--- TEST -->
 
+You can also define `Exact` by using Kotlin delegation.
+<!--- INCLUDE
+import arrow.core.raise.ensure
+import arrow.exact.Exact
+import arrow.exact.ExactError
+-->
+```kotlin
+@JvmInline
+value class NotBlankString private constructor(val value: String) {
+   companion object : Exact<String, NotBlankString> by Exact({
+     ensure(it.isNotBlank()) { ExactError("Cannot be blank.") }
+     NotBlankString(it)
+   })
+}
+```
+<!--- KNIT example-readme-02.kt -->
+
 You can define a second type `NotBlankTrimmedString` that is a `NotBlankString` that is also
-trimmed. Since the `exact` constructor allows us to compose `Exact` instances, we can easily
+trimmed. Since the `ensure` allows us to compose `Exact` instances, we can easily
 reuse the `NotBlankString` type.
 <!--- INCLUDE
+import arrow.core.raise.Raise
 import arrow.core.raise.ensure
 import arrow.exact.Exact
 import arrow.exact.ExactError
-import arrow.exact.exact
+import arrow.exact.ensure
 
-@JvmInline value class NotBlankString private constructor(val value: String) {
-  companion object : Exact<String, NotBlankString> by exact({
-    ensure(raw.isNotBlank()) { ExactError("Cannot be blank.") }
-    NotBlankString(raw)
-  })
+@JvmInline
+value class NotBlankString private constructor(val value: String) {
+  companion object : Exact<String, NotBlankString> {
+    override fun Raise<ExactError>.spec(raw: String): NotBlankString {
+      ensure(raw.isNotBlank()) { ExactError("Cannot be blank.") }
+      return NotBlankString(raw)
+    }
+  }
 }
 -->
 
 ```kotlin
 @JvmInline
-value class NotBlankTrimmedString private constructor(val value: String) {
-  companion object : Exact<String, NotBlankTrimmedString> by exact({
-    val notBlank = ensure(NotBlankString)
-    NotBlankTrimmedString(notBlank.value.trim())
-  })
+value class NotBlankTrimmedString private constructor(val value: String) { 
+  companion object : Exact<String, NotBlankTrimmedString> { 
+    override fun Raise<ExactError>.spec(raw: String): NotBlankTrimmedString { 
+      ensure(raw, NotBlankString)
+      return NotBlankTrimmedString(raw.trim())
+    }
+  }
 }
 ```
 
-<!--- KNIT example-readme-02.kt -->
+<!--- KNIT example-readme-03.kt -->

guide/src/commonMain/kotlin/examples/example-exact-01.kt

@@ -1,17 +1,19 @@
 // This file was automatically generated from Exact.kt by Knit tool. Do not edit.
 package arrow.exact.knit.example.exampleExact01
 
+import arrow.core.raise.Raise
 import arrow.core.raise.ensure
 import arrow.exact.Exact
 import arrow.exact.ExactError
-import arrow.exact.exact
 
 @JvmInline
 value class NotBlankString private constructor(val value: String) {
-  companion object : Exact<String, NotBlankString> by exact({
-    ensure(raw.isNotBlank()) { ExactError("Cannot be blank.") }
-    NotBlankString(raw)
-  })
+  companion object : Exact<String, NotBlankString> {
+    override fun Raise<ExactError>.spec(raw: String): NotBlankString {
+      ensure(raw.isNotBlank()) { ExactError("Cannot be blank.") }
+      return NotBlankString(raw)
+    }
+  }
 }
 
 fun example() {

guide/src/commonMain/kotlin/examples/example-exact-02.kt

@@ -4,19 +4,11 @@ package arrow.exact.knit.example.exampleExact02
 import arrow.core.raise.ensure
 import arrow.exact.Exact
 import arrow.exact.ExactError
-import arrow.exact.exact
-
-@JvmInline value class NotBlankString private constructor(val value: String) {
-  companion object : Exact<String, NotBlankString> by exact({
-    ensure(raw.isNotBlank()) { ExactError("Cannot be blank.") }
-    NotBlankString(raw)
-  })
-}
 
 @JvmInline
-value class NotBlankTrimmedString private constructor(val value: String) {
-  companion object : Exact<String, NotBlankTrimmedString> by exact({
-    val notBlank = ensure(NotBlankString)
-    NotBlankTrimmedString(notBlank.value.trim())
+value class NotBlankString private constructor(val value: String) {
+  companion object : Exact<String, NotBlankString> by Exact({
+    ensure(it.isNotBlank()) { ExactError("Cannot be blank.") }
+    NotBlankString(it)
   })
 }

guide/src/commonMain/kotlin/examples/example-exact-03.kt

@@ -1,34 +1,27 @@
 // This file was automatically generated from Exact.kt by Knit tool. Do not edit.
 package arrow.exact.knit.example.exampleExact03
 
+import arrow.core.raise.Raise
 import arrow.core.raise.ensure
 import arrow.exact.Exact
-import arrow.exact.ExactEither
 import arrow.exact.ExactError
-import arrow.exact.exact
-import arrow.exact.exactEither
+import arrow.exact.ensure
 
-@JvmInline value class NotBlankTrimmedString private constructor(val value: String) {
-  companion object : Exact<String, NotBlankTrimmedString> by exact({
-    ensure(raw.isNotBlank()) { ExactError("Cannot be blank.") }
-    NotBlankTrimmedString(raw.trim())
-  })
-}
-
-sealed interface UsernameError {
-  object Invalid : UsernameError
-  data class Offensive(val username: String) : UsernameError
+class NotBlankString private constructor(val value: String) {
+  companion object : Exact<String, NotBlankString> {
+    override fun Raise<ExactError>.spec(raw: String): NotBlankString {
+      ensure(raw.isNotBlank()) { ExactError("Cannot be blank.") }
+      return NotBlankString(raw)
+    }
+  }
 }
 
 @JvmInline
-value class Username private constructor(val value: String) {
-  companion object : ExactEither<UsernameError, String, Username> by exactEither({
-    val username =
-      ensure(NotBlankTrimmedString) {
-        UsernameError.Invalid
-      }.value
-    ensure(username.length < 100) { UsernameError.Invalid }
-    ensure(username !in listOf("offensive")) { UsernameError.Offensive(username) }
-    Username(username)
-  })
+value class NotBlankTrimmedString private constructor(val value: String) {
+  companion object : Exact<String, NotBlankTrimmedString> {
+    override fun Raise<ExactError>.spec(raw: String): NotBlankTrimmedString {
+      ensure(raw, NotBlankString)
+      return NotBlankTrimmedString(raw.trim())
+    }
+  }
 }

guide/src/commonMain/kotlin/examples/example-exact-04.kt

@@ -0,0 +1,39 @@
+// This file was automatically generated from Exact.kt by Knit tool. Do not edit.
+package arrow.exact.knit.example.exampleExact04
+
+import arrow.core.raise.Raise
+import arrow.core.raise.ensure
+import arrow.exact.Exact
+import arrow.exact.ExactEither
+import arrow.exact.ExactError
+import arrow.exact.ensure
+
+@JvmInline
+value class NotBlankTrimmedString private constructor(val value: String) {
+  companion object : Exact<String, NotBlankTrimmedString> {
+    override fun Raise<ExactError>.spec(raw: String): NotBlankTrimmedString {
+      ensure(raw.isNotBlank()) { ExactError("Cannot be blank.") }
+      return NotBlankTrimmedString(raw.trim())
+    }
+  }
+}
+
+sealed interface UsernameError {
+  object Invalid : UsernameError
+  data class Offensive(val username: String) : UsernameError
+}
+
+@JvmInline
+value class Username private constructor(val value: String) {
+  companion object : ExactEither<UsernameError, String, Username> {
+    override fun Raise<UsernameError>.spec(raw: String): Username {
+      val username =
+        ensure(raw, NotBlankTrimmedString) {
+          UsernameError.Invalid
+        }.value
+      ensure(username.length < 100) { UsernameError.Invalid }
+      ensure(username !in listOf("offensive")) { UsernameError.Offensive(username) }
+      return Username(username)
+    }
+  }
+}

guide/src/commonMain/kotlin/examples/example-readme-01.kt

@@ -1,17 +1,19 @@
 // This file was automatically generated from README.md by Knit tool. Do not edit.
 package arrow.exact.knit.example.exampleReadme01
 
+import arrow.core.raise.Raise
 import arrow.core.raise.ensure
 import arrow.exact.Exact
 import arrow.exact.ExactError
-import arrow.exact.exact
 
 @JvmInline
-value class NotBlankString private constructor(val value: String) {
-  companion object : Exact<String, NotBlankString> by exact({
-    ensure(raw.isNotBlank()) { ExactError("Cannot be blank.") }
-    NotBlankString(raw)
-  })
+value class NotBlankString private constructor(val value: String) { 
+  companion object : Exact<String, NotBlankString> {
+    override fun Raise<ExactError>.spec(raw: String): NotBlankString { 
+      ensure(raw.isNotBlank()) { ExactError("Cannot be blank.") }
+      return NotBlankString(raw)
+    }
+  }
 }
 
 fun example() {

guide/src/commonMain/kotlin/examples/example-readme-02.kt

@@ -4,19 +4,11 @@ package arrow.exact.knit.example.exampleReadme02
 import arrow.core.raise.ensure
 import arrow.exact.Exact
 import arrow.exact.ExactError
-import arrow.exact.exact
-
-@JvmInline value class NotBlankString private constructor(val value: String) {
-  companion object : Exact<String, NotBlankString> by exact({
-    ensure(raw.isNotBlank()) { ExactError("Cannot be blank.") }
-    NotBlankString(raw)
-  })
-}
 
 @JvmInline
-value class NotBlankTrimmedString private constructor(val value: String) {
-  companion object : Exact<String, NotBlankTrimmedString> by exact({
-    val notBlank = ensure(NotBlankString)
-    NotBlankTrimmedString(notBlank.value.trim())
-  })
+value class NotBlankString private constructor(val value: String) {
+   companion object : Exact<String, NotBlankString> by Exact({
+     ensure(it.isNotBlank()) { ExactError("Cannot be blank.") }
+     NotBlankString(it)
+   })
 }

guide/src/commonMain/kotlin/examples/example-readme-03.kt

@@ -0,0 +1,28 @@
+// This file was automatically generated from README.md by Knit tool. Do not edit.
+package arrow.exact.knit.example.exampleReadme03
+
+import arrow.core.raise.Raise
+import arrow.core.raise.ensure
+import arrow.exact.Exact
+import arrow.exact.ExactError
+import arrow.exact.ensure
+
+@JvmInline
+value class NotBlankString private constructor(val value: String) {
+  companion object : Exact<String, NotBlankString> {
+    override fun Raise<ExactError>.spec(raw: String): NotBlankString {
+      ensure(raw.isNotBlank()) { ExactError("Cannot be blank.") }
+      return NotBlankString(raw)
+    }
+  }
+}
+
+@JvmInline
+value class NotBlankTrimmedString private constructor(val value: String) { 
+  companion object : Exact<String, NotBlankTrimmedString> { 
+    override fun Raise<ExactError>.spec(raw: String): NotBlankTrimmedString { 
+      ensure(raw, NotBlankString)
+      return NotBlankTrimmedString(raw.trim())
+    }
+  }
+}