Skip to content

Commit bd41d55

Browse files
jnapejnape
authored
Updating from README.md
1 parent b546388 commit bd41d55

File tree

1 file changed

+115
-3
lines changed

1 file changed

+115
-3
lines changed

‎index.md

Lines changed: 115 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,13 @@ Functional patterns for Java 8
1010
- [Background](#background)
1111
- [Installation](#installation)
1212
- [Examples](#examples)
13+
- [Semigroups](#semigroups)
14+
- [Monoids](#monoids)
15+
- [Functors](#functors)
16+
- [Bifunctors](#bifunctors)
17+
- [Profunctors](#profunctors)
18+
- [Applicatives](#applicatives)
19+
- [Traversables](#traversables)
1320
- [ADTs](#adts)
1421
- [HLists](#hlists)
1522
- [Tuples](#tuples)
@@ -48,14 +55,14 @@ Add the following dependency to your:
4855
<dependency>
4956
<groupId>com.jnape.palatable</groupId>
5057
<artifactId>lambda</artifactId>
51-
<version>1.5.6</version>
58+
<version>1.6.0</version>
5259
</dependency>
5360
```
5461

5562
`build.gradle` ([Gradle](https://docs.gradle.org/current/userguide/dependency_management.html)):
5663

5764
```gradle
58-
compile group: 'com.jnape.palatable', name: 'lambda', version: '1.5.6'
65+
compile group: 'com.jnape.palatable', name: 'lambda', version: '1.6.0'
5966
```
6067

6168
<a name="examples">Examples</a>
@@ -138,10 +145,115 @@ Iterable<Iterable<Integer>> multiplesOf3InGroupsOf3 =
138145

139146
Check out the [tests](https://github.com/palatable/lambda/tree/master/src/test/java/com/jnape/palatable/lambda/functions/builtin) or [javadoc](http://palatable.github.io/lambda/javadoc/) for more examples.
140147

148+
<a name="semigroups">Semigroups</a>
149+
----
150+
151+
[Semigroups](https://en.wikipedia.org/wiki/Semigroup) are supported via `Semigroup<A>`, a subtype of `Fn2<A,A,A>`, and add left and right folds over an `Iterable<A>`.
152+
153+
Lambda ships some default logical semigroups for lambda types and core JDK types. Common examples are:
154+
155+
- `AddAll` for concatenating two `Collection`s
156+
- `Collapse` for collapsing two `Tuple2`s together
157+
- `Merge` for merging two `Either`s using left-biasing semantics
158+
159+
Check out the [semigroup](https://palatable.github.io/lambda/javadoc/com/jnape/palatable/lambda/semigroup/builtin/package-summary.html) package for more examples.
160+
161+
<a name="monoids">Monoids</a>
162+
----
163+
164+
[Monoids](https://en.wikipedia.org/wiki/Monoid) are supported via `Monoid<A>`, a subtype of `Semigroup<A>` with an `A #identity()` method, and add left and right reduces over an `Iterable<A>`.
165+
166+
Some commonly used lambda monoid implementations include:
167+
168+
- `Present` for merging together two `Optional`s
169+
- `Join` for joining two `String`s
170+
- `And` for logical conjunction of two `Boolean`s
171+
- `Or` for logical disjunction of two `Boolean`s
172+
173+
Additionally, instances of `Monoid<A>` can be trivially synthesized from instances of `Semigroup<A>` via the `Monoid#monoid` static factory method, taking the `Semigroup` and the identity element `A` or a supplier of the identity element `Supplier<A>`.
174+
175+
Check out the [monoid](https://palatable.github.io/lambda/javadoc/com/jnape/palatable/lambda/monoid/builtin/package-summary.html) package for more examples.
176+
177+
<a name="functors">Functors</a>
178+
----
179+
180+
Functors are implemented via the `Functor` interface, and are sub-typed by every function type that lambda exports, as well as many of the [ADTs](#adts).
181+
182+
Examples of functors include:
183+
184+
- `Fn*`, `Semigroup`, and `Monoid`
185+
- `SingletonHList` and `Tuple*`
186+
- `Choice*`
187+
- `Either`
188+
- `Const`, `Identity`, and `Compose`
189+
- `Lens`
190+
191+
Implementing `Functor` is as simple as providing a definition for the covariant mapping function `#fmap` (ideally satisfying the [two laws](https://hackage.haskell.org/package/base-4.9.1.0/docs/Data-Functor.html)).
192+
193+
### <a name="bifunctors">Bifunctors</a>
194+
195+
Bifunctors -- functors that support two parameters that can be covariantly mapped over -- are implemented via the `Bifunctor` interface.
196+
197+
Examples of bifunctors include:
198+
199+
- `Tuple*`
200+
- `Choice*`
201+
- `Either`
202+
- `Const`
203+
204+
Implementing `Bifunctor` requires implementing *either* `biMapL` and `biMapR` *or* `biMap`. As with `Functor`, there are a [few laws](https://hackage.haskell.org/package/base-4.9.1.0/docs/Data-Bifunctor.html) that well-behaved instances of `Bifunctor` should adhere to.
205+
206+
### <a name="profunctors">Profunctors</a>
207+
208+
Profunctors -- functors that support one parameter that can be mapped over contravariantly, and a second parameter that can be mapped over covariantly -- are implemented via the `Profunctor` interface.
209+
210+
Examples of profunctors include:
211+
212+
- `Fn*`
213+
- `Lens`
214+
215+
Implementing `Profunctor` requires implementing *either* `diMapL` and `diMapR` *or* `diMap`. As with `Functor` and `Bifunctor`, there are [some laws](https://hackage.haskell.org/package/profunctors-5.2/docs/Data-Profunctor.html) that well behaved instances of `Profunctor` should adhere to.
216+
217+
### <a name="applicatives">Applicatives</a>
218+
219+
Applicative functors -- functors that can be applied together with a 2-arity or higher function -- are implemented via the `Applicative` interface.
220+
221+
Examples of applicative functors include:
222+
223+
- `Fn*`, `Semigroup`, and `Monoid`
224+
- `SingletonHList` and `Tuple*`
225+
- `Choice*`
226+
- `Either`
227+
- `Const`, `Identity`, and `Compose`
228+
- `Lens`
229+
230+
In addition to implementing `fmap` from `Functor`, implementing an applicative functor involves providing two methods: `pure`, a method that lifts a value into the functor; and `zip`, a method that applies a lifted function to a lifted value, returning a new lifted value. As usual, there are [some laws](https://hackage.haskell.org/package/base-4.9.1.0/docs/Control-Applicative.html) that should be adhered to.
231+
232+
For example, imagine we have an `Fn2<String,String,String>` we'll call `join` that simply joins two strings. If we wanted to join the `String`s wrapped inside two `Either<Integer,String>` instances, without `Applicative`, we would at best only be able to `fmap` one while `fmap`ping the other, resulting in an `Either<Integer, Either<Integer,String>>`.
233+
234+
With `Applicative`, however, we can `fmap(join)` the first `Either<Integer String>`, resulting in an `Either<Integer, Fn1<String, String>>`, and then `zip` the second `Either<Integer, String>`, producing another `Either<Integer, String>`. In this way, `Applicative` can be thought of as facilitating `fmap`ping a functor with a multi-arity function.
235+
236+
### <a name="traversables">Traversables</a>
237+
238+
Traversable functors -- functors that can be "traversed from left to right" -- are implemented via the `Traversable` interface.
239+
240+
Examples of traversable functors include:
241+
242+
- `SingletonHList` and `Tuple*`
243+
- `Choice*`
244+
- `Either`
245+
- `Const` and `Identity`
246+
- `TraversableIterable` for wrapping `Iterable` in an instance of `Traversable`
247+
- `TraversableOptional` for wrapping `Optional` in an instance of `Traversable`
248+
249+
In addition to implementing `fmap` from `Functor`, implementing a traversable functor involves providing an implementation of `traverse`.
250+
251+
As always, there are [some laws](https://hackage.haskell.org/package/base-4.9.1.0/docs/Data-Traversable.html) that should be observed.
252+
141253
<a name="adts">ADTs</a>
142254
----
143255

144-
In addition to the functions above, lambda also supports a few first-class [algebraic data types](https://www.wikiwand.com/en/Algebraic_data_type).
256+
Lambda also supports a few first-class [algebraic data types](https://www.wikiwand.com/en/Algebraic_data_type).
145257

146258
### <a name="hlists">Heterogeneous Lists (HLists)</a>
147259

0 commit comments

Comments
 (0)