- Adding Applicative#lazyZip, supporting short-circuiting for some types

- FoldRight now operates in terms of Lazy and can be short-circuited

Author: jnape

CHANGELOG.md

@@ -8,11 +8,13 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 - ***Breaking Change***: `IO` is now sealed and moved to its own package. Most previous constructions using the static 
 factory methods should continue to work (by simply targeting `Supplier` now instead of an anonymous `IO`), but some 
 might need to be reworked, and subtyping is obviously no longer supported.
+- ***Breaking Change***: `FoldRight` now requires `Lazy` as part of its interface to support short-circuiting operations
 - `IO` is now stack-safe, regardless of whether the composition nests linearly or recursively
 
 ### Added
 - `Lazy`, a monad supporting stack-safe lazy evaluation
 - `LazyRec`, a function for writing stack-safe recursive algorithms embedded in `Lazy`
+- `Applicative#lazyZip`, for zipping two applicatives in a way that might not require evaluation of one applicative
 
 ## [3.3.0] - 2019-02-18
 ### Added

src/main/java/com/jnape/palatable/lambda/adt/Either.java

@@ -9,6 +9,7 @@
 import com.jnape.palatable.lambda.functions.specialized.checked.CheckedSupplier;
 import com.jnape.palatable.lambda.functor.Applicative;
 import com.jnape.palatable.lambda.functor.Bifunctor;
+import com.jnape.palatable.lambda.functor.builtin.Lazy;
 import com.jnape.palatable.lambda.monad.Monad;
 import com.jnape.palatable.lambda.traversable.Traversable;
 
@@ -20,6 +21,7 @@
 
 import static com.jnape.palatable.lambda.functions.builtin.fn1.Id.id;
 import static com.jnape.palatable.lambda.functions.builtin.fn3.FoldLeft.foldLeft;
+import static com.jnape.palatable.lambda.functor.builtin.Lazy.lazy;
 import static java.util.Arrays.asList;
 
 /**
@@ -187,54 +189,94 @@ public Either<L, R> peek(Consumer<L> leftConsumer, Consumer<R> rightConsumer) {
     @Override
     public abstract <V> V match(Function<? super L, ? extends V> leftFn, Function<? super R, ? extends V> rightFn);
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public <C> Choice3<L, R, C> diverge() {
         return match(Choice3::a, Choice3::b);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public final <R2> Either<L, R2> fmap(Function<? super R, ? extends R2> fn) {
         return Monad.super.<R2>fmap(fn).coerce();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     @SuppressWarnings("unchecked")
     public final <L2> Either<L2, R> biMapL(Function<? super L, ? extends L2> fn) {
         return (Either<L2, R>) Bifunctor.super.biMapL(fn);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     @SuppressWarnings("unchecked")
     public final <R2> Either<L, R2> biMapR(Function<? super R, ? extends R2> fn) {
         return (Either<L, R2>) Bifunctor.super.biMapR(fn);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public final <L2, R2> Either<L2, R2> biMap(Function<? super L, ? extends L2> leftFn,
                                                Function<? super R, ? extends R2> rightFn) {
         return match(l -> left(leftFn.apply(l)), r -> right(rightFn.apply(r)));
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public final <R2> Either<L, R2> pure(R2 r2) {
         return right(r2);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public final <R2> Either<L, R2> zip(Applicative<Function<? super R, ? extends R2>, Either<L, ?>> appFn) {
         return appFn.<Either<L, Function<? super R, ? extends R2>>>coerce().flatMap(this::biMapR);
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public <R2> Lazy<Either<L, R2>> lazyZip(
+            Lazy<Applicative<Function<? super R, ? extends R2>, Either<L, ?>>> lazyAppFn) {
+        return match(l -> lazy(left(l)),
+                     r -> lazyAppFn.fmap(eitherLF -> eitherLF.<R2>fmap(f -> f.apply(r)).coerce()));
+    }
+
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public final <R2> Either<L, R2> discardL(Applicative<R2, Either<L, ?>> appB) {
         return Monad.super.discardL(appB).coerce();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public final <R2> Either<L, R> discardR(Applicative<R2, Either<L, ?>> appB) {
         return Monad.super.discardR(appB).coerce();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     @SuppressWarnings("unchecked")
     public final <R2, App extends Applicative, TravB extends Traversable<R2, Either<L, ?>>, AppB extends Applicative<R2, App>, AppTrav extends Applicative<TravB, App>> AppTrav traverse(

src/main/java/com/jnape/palatable/lambda/adt/Maybe.java

@@ -9,6 +9,7 @@
 import com.jnape.palatable.lambda.functions.specialized.checked.CheckedSupplier;
 import com.jnape.palatable.lambda.functor.Applicative;
 import com.jnape.palatable.lambda.functor.Functor;
+import com.jnape.palatable.lambda.functor.builtin.Lazy;
 import com.jnape.palatable.lambda.monad.Monad;
 import com.jnape.palatable.lambda.traversable.Traversable;
 
@@ -22,6 +23,7 @@
 import static com.jnape.palatable.lambda.adt.Unit.UNIT;
 import static com.jnape.palatable.lambda.functions.builtin.fn1.Constantly.constantly;
 import static com.jnape.palatable.lambda.functions.builtin.fn1.Id.id;
+import static com.jnape.palatable.lambda.functor.builtin.Lazy.lazy;
 
 /**
  * The optional type, representing a potentially absent value. This is lambda's analog of {@link Optional}, supporting
@@ -125,36 +127,70 @@ public final <B> Maybe<B> fmap(Function<? super A, ? extends B> fn) {
         return Monad.super.<B>fmap(fn).coerce();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public final <B> Maybe<B> zip(Applicative<Function<? super A, ? extends B>, Maybe> appFn) {
         return Monad.super.zip(appFn).coerce();
     }
 
+    /**
+     * Terminate early if this is a {@link Nothing}; otherwise, continue the {@link Applicative#zip zip}.
+     *
+     * @param lazyAppFn the lazy other applicative instance
+     * @param <B>       the result type
+     * @return the zipped {@link Maybe}
+     */
+    @Override
+    public <B> Lazy<Maybe<B>> lazyZip(Lazy<Applicative<Function<? super A, ? extends B>, Maybe>> lazyAppFn) {
+        return match(constantly(lazy(nothing())),
+                     a -> lazyAppFn.fmap(maybeF -> maybeF.<B>fmap(f -> f.apply(a)).coerce()));
+    }
+
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public final <B> Maybe<B> discardL(Applicative<B, Maybe> appB) {
         return Monad.super.discardL(appB).coerce();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public final <B> Maybe<A> discardR(Applicative<B, Maybe> appB) {
         return Monad.super.discardR(appB).coerce();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public final <B> Maybe<B> flatMap(Function<? super A, ? extends Monad<B, Maybe>> f) {
         return match(constantly(nothing()), f.andThen(Applicative::coerce));
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public <B> Choice3<Unit, A, B> diverge() {
         return match(Choice3::a, Choice3::b);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public Tuple2<Maybe<Unit>, Maybe<A>> project() {
         return CoProduct2.super.project().into(HList::tuple);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public Choice2<A, Unit> invert() {
         return match(Choice2::b, Choice2::a);

src/main/java/com/jnape/palatable/lambda/adt/These.java

@@ -5,6 +5,7 @@
 import com.jnape.palatable.lambda.adt.hlist.Tuple2;
 import com.jnape.palatable.lambda.functor.Applicative;
 import com.jnape.palatable.lambda.functor.Bifunctor;
+import com.jnape.palatable.lambda.functor.builtin.Lazy;
 import com.jnape.palatable.lambda.monad.Monad;
 import com.jnape.palatable.lambda.traversable.Traversable;
 
@@ -14,6 +15,7 @@
 import static com.jnape.palatable.lambda.adt.hlist.HList.tuple;
 import static com.jnape.palatable.lambda.functions.builtin.fn1.Constantly.constantly;
 import static com.jnape.palatable.lambda.functions.builtin.fn2.Into.into;
+import static com.jnape.palatable.lambda.functor.builtin.Lazy.lazy;
 
 /**
  * The coproduct of a coproduct (<code>{@link CoProduct2}&lt;A, B&gt;</code>) and its product (<code>{@link
@@ -96,6 +98,12 @@ public final <C> These<A, C> zip(Applicative<Function<? super B, ? extends C>, T
         return Monad.super.zip(appFn).coerce();
     }
 
+    @Override
+    public <C> Lazy<These<A, C>> lazyZip(Lazy<Applicative<Function<? super B, ? extends C>, These<A, ?>>> lazyAppFn) {
+        return projectA().<Lazy<These<A, C>>>fmap(a -> lazy(a(a)))
+                .orElseGet(() -> Monad.super.lazyZip(lazyAppFn).fmap(Applicative::coerce));
+    }
+
     /**
      * {@inheritDoc}
      */

src/main/java/com/jnape/palatable/lambda/adt/Try.java

@@ -6,6 +6,7 @@
 import com.jnape.palatable.lambda.functions.specialized.checked.CheckedSupplier;
 import com.jnape.palatable.lambda.functor.Applicative;
 import com.jnape.palatable.lambda.functor.BoundedBifunctor;
+import com.jnape.palatable.lambda.functor.builtin.Lazy;
 import com.jnape.palatable.lambda.monad.Monad;
 import com.jnape.palatable.lambda.traversable.Traversable;
 
@@ -18,6 +19,7 @@
 import static com.jnape.palatable.lambda.functions.builtin.fn1.Id.id;
 import static com.jnape.palatable.lambda.functions.builtin.fn1.Upcast.upcast;
 import static com.jnape.palatable.lambda.functions.builtin.fn2.Peek2.peek2;
+import static com.jnape.palatable.lambda.functor.builtin.Lazy.lazy;
 
 /**
  * A {@link Monad} of the evaluation outcome of an expression that might throw. Try/catch/finally semantics map to
@@ -139,36 +141,63 @@ public final <L> Either<L, A> toEither(Function<? super T, ? extends L> fn) {
         return match(fn.andThen(Either::left), Either::right);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public <B> Try<T, B> fmap(Function<? super A, ? extends B> fn) {
         return Monad.super.<B>fmap(fn).coerce();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public <B> Try<T, B> flatMap(Function<? super A, ? extends Monad<B, Try<T, ?>>> f) {
         return match(Try::failure, a -> f.apply(a).coerce());
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public <B> Try<T, B> pure(B b) {
         return success(b);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public <B> Try<T, B> zip(Applicative<Function<? super A, ? extends B>, Try<T, ?>> appFn) {
         return Monad.super.zip(appFn).coerce();
     }
 
+    @Override
+    public <B> Lazy<Try<T, B>> lazyZip(Lazy<Applicative<Function<? super A, ? extends B>, Try<T, ?>>> lazyAppFn) {
+        return match(f -> lazy(failure(f)),
+                     s -> lazyAppFn.fmap(tryF -> tryF.<B>fmap(f -> f.apply(s)).coerce()));
+    }
+
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public <B> Try<T, B> discardL(Applicative<B, Try<T, ?>> appB) {
         return Monad.super.discardL(appB).coerce();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public <B> Try<T, A> discardR(Applicative<B, Try<T, ?>> appB) {
         return Monad.super.discardR(appB).coerce();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     @SuppressWarnings("unchecked")
     public <B, App extends Applicative, TravB extends Traversable<B, Try<T, ?>>, AppB extends Applicative<B, App>, AppTrav extends Applicative<TravB, App>> AppTrav traverse(
@@ -177,17 +206,26 @@ public <B> Try<T, A> discardR(Applicative<B, Try<T, ?>> appB) {
                      a -> fn.apply(a).fmap(Try::success).<TravB>fmap(Applicative::coerce).coerce());
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public <U extends Throwable, D> Try<U, D> biMap(Function<? super T, ? extends U> lFn,
                                                     Function<? super A, ? extends D> rFn) {
         return match(t -> failure(lFn.apply(t)), a -> success(rFn.apply(a)));
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public <U extends Throwable> Try<U, A> biMapL(Function<? super T, ? extends U> fn) {
         return (Try<U, A>) BoundedBifunctor.super.<U>biMapL(fn);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public <B> Try<T, B> biMapR(Function<? super A, ? extends B> fn) {
         return (Try<T, B>) BoundedBifunctor.super.<B>biMapR(fn);