From c28d39250cac3c98f4996c4c56faa195997d6b15 Mon Sep 17 00:00:00 2001 From: domlopez Date: Sun, 10 Mar 2019 18:57:41 +0100 Subject: [PATCH 01/18] 0.9.0 dependencies in README.md --- README.md | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) diff --git a/README.md b/README.md index 44754ac65a8..2823b6461f6 100644 --- a/README.md +++ b/README.md @@ -76,16 +76,6 @@ Trimmed down versions: ```groovy def arrow_version = "0.9.0" -``` - -You can find the dependencies necessary in the Basic Setup of the README at the 0.9.0 tag clicking [here](https://github.com/arrow-kt/arrow/blob/0.9.0/README.md#next-development-version-090). - -# Next development version 0.9.1 - -Add the dependencies into the project's `build.gradle` - -```groovy -def arrow_version = "0.9.1-SNAPSHOT" dependencies { compile "io.arrow-kt:arrow-core-data:$arrow_version" compile "io.arrow-kt:arrow-core-extensions:$arrow_version" @@ -115,6 +105,7 @@ dependencies { compile "io.arrow-kt:arrow-query-language:$arrow_version" //optional compile "io.arrow-kt:arrow-integration-retrofit-adapter:$arrow_version" //optional } + ``` # Additional Setup From 60b6d78787990cb9c5fdf1ca666d558a937b67a3 Mon Sep 17 00:00:00 2001 From: John Date: Mon, 25 Mar 2019 19:30:26 +0100 Subject: [PATCH 02/18] Add imports to Eval examples --- .../src/main/kotlin/arrow/core/Eval.kt | 69 ++++++++++++++++++- 1 file changed, 66 insertions(+), 3 deletions(-) diff --git a/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt b/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt index 9b8b52d3de7..1cbdaa54b7c 100644 --- a/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt +++ b/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt @@ -5,6 +5,8 @@ import arrow.higherkind fun EvalOf.value(): A = this.fix().value() /** + * ank_macro_hierarchy(arrow.core.Eval) + * * Eval is a monad which controls evaluation of a value or a computation that produces a value. * * Three basic evaluation strategies: @@ -29,6 +31,28 @@ fun EvalOf.value(): A = this.fix().value() * Eval instances whose computation involves calling .value on another * Eval instance -- this can defeat the trampolining and lead to stack * overflows. + * + * Example of stack safety: + * + * ```kotlin:ank + * import arrow.core.Eval + * + * fun even(n: Int): Eval = + * Eval.always { n == 0 }.flatMap { + * if(it == true) Eval.now(true) + * else odd(n - 1) + * } + * + * fun odd(n: Int): Eval = + * Eval.always { n == 0 }.flatMap { + * if(it == true) Eval.now(false) + * else even(n - 1) + * } + * + * // if not wrapped in eval this type of computation would blow the stack and result in a StackOverflowError + * odd(100000).value() + * ``` + * */ @higherkind sealed class Eval : EvalOf { @@ -44,11 +68,50 @@ sealed class Eval : EvalOf { } fun just(a: A): Eval = now(a) - + /** + * Creates an Eval instance from an already constructed value but still defers evaluation when chaining expressions with `map` and `flatMap` + * + * @param a is an already computed value of type [A] + * + * ```kotlin:ank + * import arrow.* + * import arrow.core.* + * + * val eager = Eval.now(1).map { it + 1 } + * eager.value() + * ``` + */ fun now(a: A) = Now(a) - + /** + * Creates an Eval instance from a function deferring it's evaluation until `.value()` is invoked memoizing the computed value. + * + * @param f is a function or computation that will be called only once when `.value()` is invoked for the first time. + * + * ```kotlin:ank + * import arrow.* + * import arrow.core.* + * + * val lazyEvaled = Eval.later { "expensive computation" } + * lazyEvaled.value() + * ``` + * + * "expensive computation" is only computed once since the results are memoized and multiple calls to `value()` will just return the cached value. + */ fun later(f: () -> A) = Later(f) - + /** + * Creates an Eval instance from a function deferring it's evaluation until `.value()` is invoked recomputing each time `.value()` is invoked. + * + * @param f is a function or computation that will be called every time `.value()` is invoked. + * + * ```kotlin:ank + * import arrow.* + * import arrow.core.* + * + * val alwaysEvaled = Eval.always { "expensive computation" } + * alwaysEvaled.value() + * ``` + * + */ fun always(f: () -> A) = Always(f) fun defer(f: () -> Eval): Eval = Defer(f) From 31b4c7b52f1fba1262caf5b757db3a44fdc28b31 Mon Sep 17 00:00:00 2001 From: John Date: Mon, 25 Mar 2019 20:20:41 +0100 Subject: [PATCH 03/18] Having a paragraph after the example, make dokka generate the snippet --- .../core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt b/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt index 1cbdaa54b7c..cf33040472a 100644 --- a/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt +++ b/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt @@ -74,12 +74,13 @@ sealed class Eval : EvalOf { * @param a is an already computed value of type [A] * * ```kotlin:ank - * import arrow.* * import arrow.core.* * * val eager = Eval.now(1).map { it + 1 } * eager.value() * ``` + * + * It will return 2. */ fun now(a: A) = Now(a) /** @@ -88,7 +89,6 @@ sealed class Eval : EvalOf { * @param f is a function or computation that will be called only once when `.value()` is invoked for the first time. * * ```kotlin:ank - * import arrow.* * import arrow.core.* * * val lazyEvaled = Eval.later { "expensive computation" } @@ -104,13 +104,13 @@ sealed class Eval : EvalOf { * @param f is a function or computation that will be called every time `.value()` is invoked. * * ```kotlin:ank - * import arrow.* * import arrow.core.* * * val alwaysEvaled = Eval.always { "expensive computation" } * alwaysEvaled.value() * ``` * + * "expensive computation" is computed every time `value()` is invoked. */ fun always(f: () -> A) = Always(f) From 276765b6ac3c0ddb3a665cfbba10e540318e664c Mon Sep 17 00:00:00 2001 From: John Date: Tue, 26 Mar 2019 00:13:40 +0100 Subject: [PATCH 04/18] Remove old documentation for Eval --- .../docs/docs/arrow/core/eval/README.md | 87 ------------------- 1 file changed, 87 deletions(-) delete mode 100644 modules/docs/arrow-docs/docs/docs/arrow/core/eval/README.md diff --git a/modules/docs/arrow-docs/docs/docs/arrow/core/eval/README.md b/modules/docs/arrow-docs/docs/docs/arrow/core/eval/README.md deleted file mode 100644 index 36558d1c0c7..00000000000 --- a/modules/docs/arrow-docs/docs/docs/arrow/core/eval/README.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -layout: docs -title: Eval -permalink: /docs/arrow/core/eval/ -redirect_from: - - /docs/datatypes/eval/ -video: FcaaTJhCEcw ---- - -## Eval - -{:.beginner} -beginner - -Eval is a monad that allows us to control evaluation and chain lazy operations that are not executed until `value()` is invoked. - -Eval includes internally trampolining facilities which allows us to chain computations without fear of blowing up the stack. -There are two different factors that play into evaluation: memoization and laziness. - -Eval supports memoization, eager and lazy evaluation strategies - -### now - -`Eval#now` creates an Eval instance from an already constructed value but still defers evaluation when chaining expressions with `map` and `flatMap` - -```kotlin:ank -import arrow.* -import arrow.core.* - -val eager = Eval.now(1).map { it + 1 } -eager.value() -``` - -### later - -`Eval#later` creates an Eval instance from a function deferring it's evaluation until `.value()` is invoked memoizing the computed value. - -```kotlin:ank -val lazyEvaled = Eval.later { "expensive computation" } -lazyEvaled.value() -``` - -`"expensive computation"` is only computed once since the results are memoized and multiple calls to `value()` will just return the cached value. - -### always - -`Eval#always` creates an Eval instance from a function deferring it's evaluation until `.value()` is invoked recomputing each time `.value()` is invoked. - -```kotlin:ank -val alwaysEvaled = Eval.always { "expensive computation" } -alwaysEvaled.value() -``` - -### Stack safety - -`Eval` empowers stack safe programs by chaining lazy computations - -```kotlin:ank -fun even(n: Int): Eval = - Eval.always { n == 0 }.flatMap { - if(it == true) Eval.now(true) - else odd(n - 1) - } - -fun odd(n: Int): Eval = - Eval.always { n == 0 }.flatMap { - if(it == true) Eval.now(false) - else even(n - 1) - } - -// if not wrapped in eval this type of computation would blow the stack and result in a StackOverflowError -odd(100000).value() -``` - -### Supported type classes - -```kotlin:ank:replace -import arrow.reflect.* -import arrow.data.* -import arrow.core.* - -DataType(Eval::class).tcMarkdownList() -``` - -## Credits - -Contents partially adapted from [Cats Eval](https://typelevel.org/cats/datatypes/eval.html) From 2314edcf3e621e1ee551990b7691a4ea40e564a9 Mon Sep 17 00:00:00 2001 From: John Date: Tue, 26 Mar 2019 00:33:32 +0100 Subject: [PATCH 05/18] Change links to new Eval documentation --- .../docs/docs/arrow/typeclasses/foldable/README.md | 2 +- .../arrow-docs/docs/docs/arrow/typeclasses/monad/README.md | 6 +++--- modules/docs/arrow-docs/docs/docs/datatypes/intro/README.md | 2 +- .../arrow-docs/docs/docs/quickstart/libraries/README.md | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/modules/docs/arrow-docs/docs/docs/arrow/typeclasses/foldable/README.md b/modules/docs/arrow-docs/docs/docs/arrow/typeclasses/foldable/README.md index f3dea909bb6..ec129ef366d 100644 --- a/modules/docs/arrow-docs/docs/docs/arrow/typeclasses/foldable/README.md +++ b/modules/docs/arrow-docs/docs/docs/arrow/typeclasses/foldable/README.md @@ -67,7 +67,7 @@ Right associative lazy fold on `F` using the provided function. This method evaluates `lb` lazily, and returns a lazy value to support laziness in a stack-safe way avoiding StackOverflows. -For more detailed information about how this method works see the documentation for [`Eval`]({{ '/docs/arrow/core/eval' | relative_url }}). +For more detailed information about how this method works see the documentation for [`Eval`]({{ '/docs/apidocs/arrow-core-data/arrow.core/-eval/index.html' | relative_url }}). ```kotlin:ank:silent fun concatenateStringFromRight(strKind: Kind, FO: Foldable): String = diff --git a/modules/docs/arrow-docs/docs/docs/arrow/typeclasses/monad/README.md b/modules/docs/arrow-docs/docs/docs/arrow/typeclasses/monad/README.md index 6356020fe20..5da5a5f1312 100644 --- a/modules/docs/arrow-docs/docs/docs/arrow/typeclasses/monad/README.md +++ b/modules/docs/arrow-docs/docs/docs/arrow/typeclasses/monad/README.md @@ -85,11 +85,11 @@ Some(5).mproduct { #### followedBy/followedByEval Executes sequentially two elements that are independent from one another. -The [`Eval`]({{ '/docs/arrow/core/eval' | relative_url }}) variant allows you to pass lazily calculated values. +The [`Eval`]({{ '/docs/apidocs/arrow-core-data/arrow.core/-eval/index.html' | relative_url }}) variant allows you to pass lazily calculated values. ```kotlin:ank import arrow.core.extensions.option.monad.followedBy - + Some(1).followedBy(Some(2)) ``` @@ -108,7 +108,7 @@ IO.just(1).effectM(::logValue).fix().unsafeRunSync() #### forEffect/forEffectEval Executes sequentially two elements that are independent from one another, ignoring the value of the second one. -The [`Eval`]({{ '/docs/arrow/core/eval' | relative_url }}) variant allows you to pass lazily calculated values. +The [`Eval`]({{ '/docs/apidocs/arrow-core-data/arrow.core/-eval/index.html' | relative_url }}) variant allows you to pass lazily calculated values. ```kotlin:ank import arrow.core.extensions.option.monad.* diff --git a/modules/docs/arrow-docs/docs/docs/datatypes/intro/README.md b/modules/docs/arrow-docs/docs/docs/datatypes/intro/README.md index 1c1a1575beb..14430d9d299 100644 --- a/modules/docs/arrow-docs/docs/docs/datatypes/intro/README.md +++ b/modules/docs/arrow-docs/docs/docs/datatypes/intro/README.md @@ -51,7 +51,7 @@ so they are always required. - [`Either`]({{ '/docs/arrow/core/either/' | relative_url }}) - an if/else branch in execution -- [`Eval`]({{ '/docs/arrow/core/eval/' | relative_url }}) - lazy evaluation of functions with stack safety and memoization +- [`Eval`]({{ '/docs/apidocs/arrow-core-data/arrow.core/-eval/index.html' | relative_url }}) - lazy evaluation of functions with stack safety and memoization - `TupleN` - a heterogeneous grouping of 2-9 values without creating a named class diff --git a/modules/docs/arrow-docs/docs/docs/quickstart/libraries/README.md b/modules/docs/arrow-docs/docs/docs/quickstart/libraries/README.md index f4890fafa17..f0c13694c08 100644 --- a/modules/docs/arrow-docs/docs/docs/quickstart/libraries/README.md +++ b/modules/docs/arrow-docs/docs/docs/quickstart/libraries/README.md @@ -21,7 +21,7 @@ beginner The smallest set of [datatypes]({{ '/docs/datatypes/intro/' | relative_url }}) necessary to start in FP, and that other libraries can build upon. The focus here is on API design and abstracting small code patterns. -Datatypes: [`Either`]({{ '/docs/arrow/core/either/' | relative_url }}), [`Option`]({{ '/docs/arrow/core/option/' | relative_url }}), [`Try`]({{ '/docs/arrow/core/try/' | relative_url }}), [`Eval`]({{ '/docs/arrow/core/eval/' | relative_url }}), [`Id`]({{ '/docs/arrow/core/id/' | relative_url }}), `TupleN`, `Function0`, `Function1`, `FunctionK` +Datatypes: [`Either`]({{ '/docs/arrow/core/either/' | relative_url }}), [`Option`]({{ '/docs/arrow/core/option/' | relative_url }}), [`Try`]({{ '/docs/arrow/core/try/' | relative_url }}), [`Eval`]({{ '/docs/apidocs/arrow-core-data/arrow.core/-eval/index.html' | relative_url }}), [`Id`]({{ '/docs/arrow/core/id/' | relative_url }}), `TupleN`, `Function0`, `Function1`, `FunctionK` ### arrow-syntax From 43ef09696b3e42adcc32da2f28d6bba2822d313f Mon Sep 17 00:00:00 2001 From: John Date: Tue, 26 Mar 2019 01:22:29 +0100 Subject: [PATCH 06/18] Modify Eval link in sidebar --- modules/docs/arrow-docs/docs/_data/sidebar.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/docs/arrow-docs/docs/_data/sidebar.yml b/modules/docs/arrow-docs/docs/_data/sidebar.yml index 30c9e2e619f..47ebe9930e6 100644 --- a/modules/docs/arrow-docs/docs/_data/sidebar.yml +++ b/modules/docs/arrow-docs/docs/_data/sidebar.yml @@ -200,7 +200,7 @@ options: url: /docs/arrow/data/coproduct/ - title: Eval - url: /docs/arrow/core/eval/ + url: /docs/apidocs/arrow-core-data/arrow.core/-eval/ - title: OptionT url: /docs/arrow/data/optiont/ From b5524c927dd1af6cd1fd65a7a0d89ad4a90a44da Mon Sep 17 00:00:00 2001 From: John Date: Tue, 26 Mar 2019 02:08:59 +0100 Subject: [PATCH 07/18] Restore README.md --- README.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 2823b6461f6..c711ee9536b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.arrow-kt/arrow-core/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.arrow-kt/arrow-core) +[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.arrow-kt/arrow-core-data/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.arrow-kt/arrow-core) [![Build Status](https://travis-ci.org/arrow-kt/arrow.svg?branch=master)](https://travis-ci.org/arrow-kt/arrow/) [![Kotlin version badge](https://img.shields.io/badge/kotlin-1.3-blue.svg)](https://kotlinlang.org/docs/reference/whatsnew13.html) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0) @@ -76,6 +76,16 @@ Trimmed down versions: ```groovy def arrow_version = "0.9.0" +``` + +You can find the dependencies necessary in the Basic Setup of the README at the 0.9.0 tag clicking [here](https://github.com/arrow-kt/arrow/blob/0.9.0/README.md#next-development-version-090). + +# Next development version 0.9.1 + +Add the dependencies into the project's `build.gradle` + +```groovy +def arrow_version = "0.9.1-SNAPSHOT" dependencies { compile "io.arrow-kt:arrow-core-data:$arrow_version" compile "io.arrow-kt:arrow-core-extensions:$arrow_version" @@ -96,8 +106,6 @@ dependencies { compile "io.arrow-kt:arrow-effects-rx2-extensions:$arrow_version" //optional compile "io.arrow-kt:arrow-effects-reactor-data:$arrow_version" //optional compile "io.arrow-kt:arrow-effects-reactor-extensions:$arrow_version" //optional - compile "io.arrow-kt:arrow-effects-kotlinx-coroutines-data:$arrow_version" //optional - compile "io.arrow-kt:arrow-effects-kotlinx-coroutines-extensions:$arrow_version" //optional compile "io.arrow-kt:arrow-optics:$arrow_version" //optional compile "io.arrow-kt:arrow-generic:$arrow_version" //optional compile "io.arrow-kt:arrow-recursion-data:$arrow_version" //optional @@ -105,7 +113,6 @@ dependencies { compile "io.arrow-kt:arrow-query-language:$arrow_version" //optional compile "io.arrow-kt:arrow-integration-retrofit-adapter:$arrow_version" //optional } - ``` # Additional Setup From b6b390a67c81c143dec6c9ca500867e41000d57b Mon Sep 17 00:00:00 2001 From: AdrianRaFo <15971742+AdrianRaFo@users.noreply.github.com> Date: Wed, 24 Apr 2019 18:15:15 +0200 Subject: [PATCH 08/18] add playground label to ank --- .../arrow-core-data/src/main/kotlin/arrow/core/Eval.kt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt b/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt index cf33040472a..7adcc0d360d 100644 --- a/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt +++ b/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt @@ -34,7 +34,7 @@ fun EvalOf.value(): A = this.fix().value() * * Example of stack safety: * - * ```kotlin:ank + * ```kotlin:ank:playground * import arrow.core.Eval * * fun even(n: Int): Eval = @@ -73,7 +73,7 @@ sealed class Eval : EvalOf { * * @param a is an already computed value of type [A] * - * ```kotlin:ank + * ```kotlin:ank:playground * import arrow.core.* * * val eager = Eval.now(1).map { it + 1 } @@ -88,7 +88,7 @@ sealed class Eval : EvalOf { * * @param f is a function or computation that will be called only once when `.value()` is invoked for the first time. * - * ```kotlin:ank + * ```kotlin:ank:playground * import arrow.core.* * * val lazyEvaled = Eval.later { "expensive computation" } @@ -103,7 +103,7 @@ sealed class Eval : EvalOf { * * @param f is a function or computation that will be called every time `.value()` is invoked. * - * ```kotlin:ank + * ```kotlin:ank:playground * import arrow.core.* * * val alwaysEvaled = Eval.always { "expensive computation" } From bad965c4d7d20d97828975fbaf8a1c78fb06252b Mon Sep 17 00:00:00 2001 From: John Date: Thu, 16 May 2019 01:24:59 +0200 Subject: [PATCH 09/18] Adding boilerplate needed to run playground code --- .../core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt b/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt index aad41f8d241..0ab0a843b04 100644 --- a/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt +++ b/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt @@ -37,6 +37,7 @@ fun EvalOf.value(): A = this.fix().value() * ```kotlin:ank:playground * import arrow.core.Eval * + * //sampleStart * fun even(n: Int): Eval = * Eval.always { n == 0 }.flatMap { * if(it == true) Eval.now(true) @@ -50,7 +51,10 @@ fun EvalOf.value(): A = this.fix().value() * } * * // if not wrapped in eval this type of computation would blow the stack and result in a StackOverflowError - * odd(100000).value() + * fun main() { + * println(odd(100000).value()) + * } + * //sampleEnd * ``` * */ From 525aa34c8c67c6ef31a73a8f9e4ffa124968f3d5 Mon Sep 17 00:00:00 2001 From: John Date: Thu, 16 May 2019 16:05:15 +0200 Subject: [PATCH 10/18] Adapt the rest of the examples for playground support --- .../src/main/kotlin/arrow/core/Eval.kt | 28 +++++++++++++------ 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt b/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt index 0ab0a843b04..9fee80f9cd9 100644 --- a/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt +++ b/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt @@ -52,7 +52,7 @@ fun EvalOf.value(): A = this.fix().value() * * // if not wrapped in eval this type of computation would blow the stack and result in a StackOverflowError * fun main() { - * println(odd(100000).value()) + * println(odd(100000).value()) * } * //sampleEnd * ``` @@ -80,8 +80,12 @@ sealed class Eval : EvalOf { * ```kotlin:ank:playground * import arrow.core.* * - * val eager = Eval.now(1).map { it + 1 } - * eager.value() + * //sampleStart + * fun main() { + * val eager = Eval.now(1).map { it + 1 } + * println(eager.value()) + * } + * //sampleEnd * ``` * * It will return 2. @@ -95,8 +99,12 @@ sealed class Eval : EvalOf { * ```kotlin:ank:playground * import arrow.core.* * - * val lazyEvaled = Eval.later { "expensive computation" } - * lazyEvaled.value() + * //sampleStart + * fun main() { + * val lazyEvaled = Eval.later { "expensive computation" } + * println(lazyEvaled.value()) + * } + * //sampleEnd * ``` * * "expensive computation" is only computed once since the results are memoized and multiple calls to `value()` will just return the cached value. @@ -110,8 +118,12 @@ sealed class Eval : EvalOf { * ```kotlin:ank:playground * import arrow.core.* * - * val alwaysEvaled = Eval.always { "expensive computation" } - * alwaysEvaled.value() + * //sampleStart + * fun main() { + * val alwaysEvaled = Eval.always { "expensive computation" } + * println(alwaysEvaled.value()) + * } + * //sampleEnd * ``` * * "expensive computation" is computed every time `value()` is invoked. @@ -146,7 +158,7 @@ sealed class Eval : EvalOf { else -> fa } - // Enforce tailrec call to collapse inside compute loop + //Enforce tailrec call to collapse inside compute loop private fun collapse1(fa: Eval): Eval = collapse(fa) @Suppress("UNCHECKED_CAST") From e555b595b1ee649e91cad00e90395b3c3353f3a3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Manuel=20M=C3=A9ndez=20Rey?= Date: Thu, 16 May 2019 16:23:31 +0200 Subject: [PATCH 11/18] Update modules/docs/arrow-docs/docs/docs/datatypes/intro/README.md Co-Authored-By: Adrian Ramirez Fornell <15971742+AdrianRaFo@users.noreply.github.com> --- modules/docs/arrow-docs/docs/docs/datatypes/intro/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/docs/arrow-docs/docs/docs/datatypes/intro/README.md b/modules/docs/arrow-docs/docs/docs/datatypes/intro/README.md index 14430d9d299..f34d58137b8 100644 --- a/modules/docs/arrow-docs/docs/docs/datatypes/intro/README.md +++ b/modules/docs/arrow-docs/docs/docs/datatypes/intro/README.md @@ -51,7 +51,7 @@ so they are always required. - [`Either`]({{ '/docs/arrow/core/either/' | relative_url }}) - an if/else branch in execution -- [`Eval`]({{ '/docs/apidocs/arrow-core-data/arrow.core/-eval/index.html' | relative_url }}) - lazy evaluation of functions with stack safety and memoization +- [`Eval`]({{ '/docs/apidocs/arrow-core-data/arrow.core/-eval' | relative_url }}) - lazy evaluation of functions with stack safety and memoization - `TupleN` - a heterogeneous grouping of 2-9 values without creating a named class From 158a201883c226e6453d49a892dbc0f7e5c83c31 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Manuel=20M=C3=A9ndez=20Rey?= Date: Thu, 16 May 2019 16:25:14 +0200 Subject: [PATCH 12/18] Update modules/docs/arrow-docs/docs/docs/quickstart/libraries/README.md Co-Authored-By: Adrian Ramirez Fornell <15971742+AdrianRaFo@users.noreply.github.com> --- .../docs/arrow-docs/docs/docs/quickstart/libraries/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/docs/arrow-docs/docs/docs/quickstart/libraries/README.md b/modules/docs/arrow-docs/docs/docs/quickstart/libraries/README.md index c12b5e1d581..ce2db147f15 100644 --- a/modules/docs/arrow-docs/docs/docs/quickstart/libraries/README.md +++ b/modules/docs/arrow-docs/docs/docs/quickstart/libraries/README.md @@ -21,7 +21,7 @@ beginner The smallest set of [datatypes]({{ '/docs/datatypes/intro/' | relative_url }}) necessary to start in FP, and that other libraries can build upon. The focus here is on API design and abstracting small code patterns. -Datatypes: [`Either`]({{ '/docs/arrow/core/either/' | relative_url }}), [`Option`]({{ '/docs/arrow/core/option/' | relative_url }}), [`Try`]({{ '/docs/arrow/core/try/' | relative_url }}), [`Eval`]({{ '/docs/apidocs/arrow-core-data/arrow.core/-eval/index.html' | relative_url }}), [`Id`]({{ '/docs/arrow/core/id/' | relative_url }}), `TupleN`, `Function0`, `Function1`, `FunctionK` +Datatypes: [`Either`]({{ '/docs/arrow/core/either/' | relative_url }}), [`Option`]({{ '/docs/arrow/core/option/' | relative_url }}), [`Try`]({{ '/docs/arrow/core/try/' | relative_url }}), [`Eval`]({{ '/docs/apidocs/arrow-core-data/arrow.core/-eval' | relative_url }}), [`Id`]({{ '/docs/arrow/core/id/' | relative_url }}), `TupleN`, `Function0`, `Function1`, `FunctionK` ### arrow-syntax From 12bae6845463e1dc708da6f0e8fadeff370df69d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Manuel=20M=C3=A9ndez=20Rey?= Date: Thu, 16 May 2019 16:25:26 +0200 Subject: [PATCH 13/18] Update modules/docs/arrow-docs/docs/docs/arrow/typeclasses/monad/README.md Co-Authored-By: Adrian Ramirez Fornell <15971742+AdrianRaFo@users.noreply.github.com> --- .../docs/arrow-docs/docs/docs/arrow/typeclasses/monad/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/docs/arrow-docs/docs/docs/arrow/typeclasses/monad/README.md b/modules/docs/arrow-docs/docs/docs/arrow/typeclasses/monad/README.md index 5da5a5f1312..dae868605b5 100644 --- a/modules/docs/arrow-docs/docs/docs/arrow/typeclasses/monad/README.md +++ b/modules/docs/arrow-docs/docs/docs/arrow/typeclasses/monad/README.md @@ -108,7 +108,7 @@ IO.just(1).effectM(::logValue).fix().unsafeRunSync() #### forEffect/forEffectEval Executes sequentially two elements that are independent from one another, ignoring the value of the second one. -The [`Eval`]({{ '/docs/apidocs/arrow-core-data/arrow.core/-eval/index.html' | relative_url }}) variant allows you to pass lazily calculated values. +The [`Eval`]({{ '/docs/apidocs/arrow-core-data/arrow.core/-eval' | relative_url }}) variant allows you to pass lazily calculated values. ```kotlin:ank import arrow.core.extensions.option.monad.* From be7104786686b4a1e83e9f5ff2eb2a5dc44fe17e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Manuel=20M=C3=A9ndez=20Rey?= Date: Thu, 16 May 2019 16:25:39 +0200 Subject: [PATCH 14/18] Update modules/docs/arrow-docs/docs/docs/arrow/typeclasses/monad/README.md Co-Authored-By: Adrian Ramirez Fornell <15971742+AdrianRaFo@users.noreply.github.com> --- .../docs/arrow-docs/docs/docs/arrow/typeclasses/monad/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/docs/arrow-docs/docs/docs/arrow/typeclasses/monad/README.md b/modules/docs/arrow-docs/docs/docs/arrow/typeclasses/monad/README.md index dae868605b5..a79756ff231 100644 --- a/modules/docs/arrow-docs/docs/docs/arrow/typeclasses/monad/README.md +++ b/modules/docs/arrow-docs/docs/docs/arrow/typeclasses/monad/README.md @@ -85,7 +85,7 @@ Some(5).mproduct { #### followedBy/followedByEval Executes sequentially two elements that are independent from one another. -The [`Eval`]({{ '/docs/apidocs/arrow-core-data/arrow.core/-eval/index.html' | relative_url }}) variant allows you to pass lazily calculated values. +The [`Eval`]({{ '/docs/apidocs/arrow-core-data/arrow.core/-eval' | relative_url }}) variant allows you to pass lazily calculated values. ```kotlin:ank import arrow.core.extensions.option.monad.followedBy From c91118a0cfde9e7af17d33cfe8423e523f97513a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Manuel=20M=C3=A9ndez=20Rey?= Date: Thu, 16 May 2019 16:25:51 +0200 Subject: [PATCH 15/18] Update modules/docs/arrow-docs/docs/docs/arrow/typeclasses/foldable/README.md Co-Authored-By: Adrian Ramirez Fornell <15971742+AdrianRaFo@users.noreply.github.com> --- .../arrow-docs/docs/docs/arrow/typeclasses/foldable/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/docs/arrow-docs/docs/docs/arrow/typeclasses/foldable/README.md b/modules/docs/arrow-docs/docs/docs/arrow/typeclasses/foldable/README.md index ec129ef366d..0d8cacd401e 100644 --- a/modules/docs/arrow-docs/docs/docs/arrow/typeclasses/foldable/README.md +++ b/modules/docs/arrow-docs/docs/docs/arrow/typeclasses/foldable/README.md @@ -67,7 +67,7 @@ Right associative lazy fold on `F` using the provided function. This method evaluates `lb` lazily, and returns a lazy value to support laziness in a stack-safe way avoiding StackOverflows. -For more detailed information about how this method works see the documentation for [`Eval`]({{ '/docs/apidocs/arrow-core-data/arrow.core/-eval/index.html' | relative_url }}). +For more detailed information about how this method works see the documentation for [`Eval`]({{ '/docs/apidocs/arrow-core-data/arrow.core/-eval' | relative_url }}). ```kotlin:ank:silent fun concatenateStringFromRight(strKind: Kind, FO: Foldable): String = From 5a8cfc60186cf5abfbbef7770a441689a3a607d3 Mon Sep 17 00:00:00 2001 From: John Date: Thu, 16 May 2019 16:41:52 +0200 Subject: [PATCH 16/18] Update sampleStart sampleEnd lines --- .../src/main/kotlin/arrow/core/Eval.kt | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt b/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt index 9fee80f9cd9..7313470af09 100644 --- a/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt +++ b/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt @@ -72,6 +72,7 @@ sealed class Eval : EvalOf { } fun just(a: A): Eval = now(a) + /** * Creates an Eval instance from an already constructed value but still defers evaluation when chaining expressions with `map` and `flatMap` * @@ -80,17 +81,18 @@ sealed class Eval : EvalOf { * ```kotlin:ank:playground * import arrow.core.* * - * //sampleStart * fun main() { + * //sampleStart * val eager = Eval.now(1).map { it + 1 } * println(eager.value()) - * } * //sampleEnd + * } * ``` * * It will return 2. */ fun now(a: A) = Now(a) + /** * Creates an Eval instance from a function deferring it's evaluation until `.value()` is invoked memoizing the computed value. * @@ -99,17 +101,18 @@ sealed class Eval : EvalOf { * ```kotlin:ank:playground * import arrow.core.* * - * //sampleStart * fun main() { + * //sampleStart * val lazyEvaled = Eval.later { "expensive computation" } * println(lazyEvaled.value()) - * } * //sampleEnd + * } * ``` * * "expensive computation" is only computed once since the results are memoized and multiple calls to `value()` will just return the cached value. */ fun later(f: () -> A) = Later(f) + /** * Creates an Eval instance from a function deferring it's evaluation until `.value()` is invoked recomputing each time `.value()` is invoked. * @@ -118,12 +121,12 @@ sealed class Eval : EvalOf { * ```kotlin:ank:playground * import arrow.core.* * - * //sampleStart * fun main() { + * //sampleStart * val alwaysEvaled = Eval.always { "expensive computation" } * println(alwaysEvaled.value()) - * } * //sampleEnd + * } * ``` * * "expensive computation" is computed every time `value()` is invoked. From 738561e44631bc71d570b32b6350861dd9232745 Mon Sep 17 00:00:00 2001 From: John Date: Thu, 16 May 2019 16:55:35 +0200 Subject: [PATCH 17/18] Needed space to pass ktlint checks --- modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt b/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt index 7313470af09..dcde46314c5 100644 --- a/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt +++ b/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt @@ -161,7 +161,7 @@ sealed class Eval : EvalOf { else -> fa } - //Enforce tailrec call to collapse inside compute loop + // Enforce tailrec call to collapse inside compute loop private fun collapse1(fa: Eval): Eval = collapse(fa) @Suppress("UNCHECKED_CAST") From 37b05874a1982c1163b7ff1081324c997183ad84 Mon Sep 17 00:00:00 2001 From: John Date: Fri, 17 May 2019 11:03:20 +0200 Subject: [PATCH 18/18] Remove unneeded diagram macro --- modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt | 2 -- 1 file changed, 2 deletions(-) diff --git a/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt b/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt index dcde46314c5..25d34050b5c 100644 --- a/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt +++ b/modules/core/arrow-core-data/src/main/kotlin/arrow/core/Eval.kt @@ -5,8 +5,6 @@ import arrow.higherkind fun EvalOf.value(): A = this.fix().value() /** - * ank_macro_hierarchy(arrow.core.Eval) - * * Eval is a monad which controls evaluation of a value or a computation that produces a value. * * Three basic evaluation strategies: