aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--readme.md91
1 files changed, 91 insertions, 0 deletions
diff --git a/readme.md b/readme.md
index a2f7f9c..9a2a408 100644
--- a/readme.md
+++ b/readme.md
@@ -2,6 +2,97 @@
2 2
3_Some functional sweetness for Java._ 3_Some functional sweetness for Java._
4 4
5This library provides useful monads that are not present in the JDK.
6The defined types and API are minimal and highly composable with the standard ones, avoiding re-inventing them.
7
8
9## Usage
10
11The Javadoc for the latest snapshot version is available online [here][javadoc].
12
13[javadoc]: https://javadoc.jitpack.io/org/pacien/lemonad/master-SNAPSHOT/javadoc/
14
15### Attempt
16
17The `Attempt` monad represents a computation which can be either successful or failed.
18It allows the transformation of results and the recovery of errors in a pipeline,
19similarly to [Scala's `Try`][scala-try] or [Java's `CompletableFuture`][java-completable-future].
20
21This monad does __not__ require the error type to be a `Throwable`,
22the use of which being problematic in performance-sensitive contexts.
23
24[scala-try]: https://www.scala-lang.org/api/2.12.8/scala/util/Try.html
25[java-completable-future]: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/CompletableFuture.html
26
27```java
28import static org.pacien.lemonad.attempt.Attempt.*;
29
30(tree.hasLemon() ? success(tree.getLemon()) : failure("No lemon."))
31 .mapFailure(error -> store.buyLemon())
32 .mapResult(this::makeLemonade)
33 .ifSuccess(this::drink);
34```
35
36### Validation
37
38The `Validation` monad represents a validation of a subject which can be either valid or invalid.
39In the latter case, the monad wraps one or multiple validation errors in addition to the subject of the validation.
40
41The `Validator` functional interface represents a function which performs verification operations on a supplied subject and returns
42a `Validation`.
43`Validator`s can be composed to perform verifications against multiple criteria and obtain an aggregated `Validation`.
44
45```java
46import static org.pacien.lemonad.validation.Validator.*;
47
48var validator = validatingAll(
49 ensuringPredicate(not(Lemon::isRotten), "Bad lemon."),
50 validatingField(Lemon::juiceContent, ensuringPredicate(mL -> mL >= 40, "Not juicy.")));
51
52validator.validate(lemon)
53 .ifValid(this::makeLemonade)
54 .ifInvalid(errors -> makeLifeTakeTheLemonBack());
55```
56
57
58## Setup
59
60_lemonad_ requires Java 11 or above.
61Binaries are compiled by and distributed through [JitPack][jitpack-page].
62
63[jitpack-page]: https://jitpack.io/#org.pacien/lemonad
64
65### Gradle (`build.gradle`)
66
67```groovy
68repositories {
69 maven { url 'https://jitpack.io' }
70}
71
72dependencies {
73 implementation 'org.pacien:lemonad:master-11a6ff0260-1'
74}
75```
76
77### Maven (`pom.xml`)
78
79```xml
80<project>
81 <repositories>
82 <repository>
83 <id>jitpack.io</id>
84 <url>https://jitpack.io</url>
85 </repository>
86 </repositories>
87
88 <dependency>
89 <groupId>org.pacien</groupId>
90 <artifactId>lemonad</artifactId>
91 <version>master-11a6ff0260-1</version>
92 </dependency>
93</project>
94```
95
5 96
6## License 97## License
7 98