Add Decidable

CONTRIBUTING.md

@@ -105,7 +105,7 @@ To build Cats you should have
  * `console`: launch a REPL
  * `test`: run the tests
  * `unidoc`: generate the documentation
- * `fmt`: run formatting of the code
+ * `scalafmtAll`: run formatting of the code
  * `validate`: run tests, style-checker, and doc generation
 
 #### Scala and Scala.js

core/src/main/scala/cats/Applicative.scala

@@ -215,6 +215,12 @@ trait Applicative[F[_]] extends Apply[F] with InvariantMonoidal[F] { self =>
       val G = ContravariantMonoidal[G]
     }
 
+  def composeDecidable[G[_]: Decidable]: Decidable[λ[α => F[G[α]]]] =
+    new ComposedApplicativeDecidable[F, G] {
+      val F = self
+      val G = Decidable[G]
+    }
+
   /**
    * Returns the given argument (mapped to Unit) if `cond` is `false`,
    * otherwise, unit lifted into F.

core/src/main/scala/cats/Composed.scala

@@ -176,6 +176,18 @@ private[cats] trait ComposedContravariantCovariant[F[_], G[_]] extends Contravar
     F.contramap(fga)(gb => G.map(gb)(f))
 }
 
+private[cats] trait ComposedApplicativeDecidable[F[_], G[_]]
+    extends Decidable[λ[α => F[G[α]]]]
+    with ComposedApplicativeContravariantMonoidal[F, G] { outer =>
+  def F: Applicative[F]
+  def G: Decidable[G]
+
+  def sum[A, B](fa: F[G[A]], fb: F[G[B]]): F[G[Either[A, B]]] =
+    F.map(F.product(fa, fb))(Function.tupled(G.sum))
+
+  override def zero: F[G[Nothing]] = F.pure(G.zero)
+}
+
 private[cats] trait ComposedApplicativeContravariantMonoidal[F[_], G[_]]
     extends ContravariantMonoidal[λ[α => F[G[α]]]] { outer =>
   def F: Applicative[F]

core/src/main/scala/cats/ContravariantMonoidal.scala

@@ -38,7 +38,7 @@ trait ContravariantMonoidal[F[_]] extends ContravariantSemigroupal[F] with Invar
    * the diagonal
    */
   def trivial[A]: F[A] = contramap(unit)(_ => ())
-
+  def conquer[A]: F[A] = trivial[A]
 }
 object ContravariantMonoidal extends SemigroupalArityFunctions {
   def monoid[F[_], A](implicit f: ContravariantMonoidal[F]): Monoid[F[A]] =

core/src/main/scala/cats/Decidable.scala

@@ -0,0 +1,88 @@
+/*
+ * Copyright (c) 2015 Typelevel
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package cats
+
+/**
+ * [[Decidable]] functors are functors that supply
+ * a `decide` operation allowing choices to be made.
+ *
+ * This is comparable to [[Alternative]] in the
+ * covariant case.
+ *
+ * Must obey laws in cats.laws.DecidableLaws.
+ *
+ * Based on ekmett's contravariant library:
+ * https://hackage.haskell.org/package/contravariant-1.4/docs/Data-Functor-Contravariant-Divisible.html#g:2
+ */
+trait Decidable[F[_]] extends ContravariantMonoidal[F] {
+  def sum[A, B](fa: F[A], fb: F[B]): F[Either[A, B]]
+  def zero: F[Nothing]
+
+  def decide[A, B, C](fa: F[A], fb: F[B])(f: C => Either[A, B]): F[C] =
+    contramap(sum(fa, fb))(f)
+
+  final def chosen[B, C](fb: F[B], fc: F[C]): F[Either[B, C]] = sum(fb, fc)
+  def lose[A](f: A => Nothing): F[A] = contramap[Nothing, A](zero)(f)
+}
+
+object Decidable {
+
+  /**
+   * Summon an instance of [[Decidable]] for `F`.
+   */
+  @inline def apply[F[_]](implicit instance: Decidable[F]): Decidable[F] = instance
+
+  @deprecated("Use cats.syntax object imports", "2.2.0")
+  object ops {
+    implicit def toAllDecidableOps[F[_], A](target: F[A])(implicit tc: Decidable[F]): AllOps[F, A] {
+      type TypeClassType = Decidable[F]
+    } =
+      new AllOps[F, A] {
+        type TypeClassType = Decidable[F]
+        val self: F[A] = target
+        val typeClassInstance: TypeClassType = tc
+      }
+  }
+  trait Ops[F[_], A] extends Serializable {
+    type TypeClassType <: Decidable[F]
+    def self: F[A]
+    val typeClassInstance: TypeClassType
+    def sum[B](fb: F[B]): F[Either[A, B]] = typeClassInstance.sum[A, B](self, fb)
+    def decide[B, C](fb: F[B])(f: C => Either[A, B]): F[C] = typeClassInstance.decide[A, B, C](self, fb)(f)
+    def chosen[B](fc: F[B]): F[Either[A, B]] = typeClassInstance.chosen[A, B](self, fc)
+  }
+  trait AllOps[F[_], A] extends Ops[F, A] with ContravariantMonoidal.AllOps[F, A] {
+    type TypeClassType <: Decidable[F]
+  }
+  trait ToDecidableOps extends Serializable {
+    implicit def toDecidableOps[F[_], A](target: F[A])(implicit tc: Decidable[F]): Ops[F, A] {
+      type TypeClassType = Decidable[F]
+    } =
+      new Ops[F, A] {
+        type TypeClassType = Decidable[F]
+        val self: F[A] = target
+        val typeClassInstance: TypeClassType = tc
+      }
+  }
+  @deprecated("Use cats.syntax object imports", "2.2.0")
+  object nonInheritedOps extends ToDecidableOps
+}

core/src/main/scala/cats/Invariant.scala

@@ -176,9 +176,9 @@ object Invariant extends ScalaVersionSpecificInvariantInstances with InvariantIn
     cats.instances.ordering.catsContravariantMonoidalForOrdering
   implicit def catsContravariantMonoidalForPartialOrdering: ContravariantMonoidal[PartialOrdering] =
     cats.instances.partialOrdering.catsContravariantMonoidalForPartialOrdering
-  implicit def catsContravariantMonoidalForEq: ContravariantMonoidal[Eq] =
+  def catsContravariantMonoidalForEq: ContravariantMonoidal[Eq] =
     cats.instances.eq.catsContravariantMonoidalForEq
-  implicit def catsContravariantMonoidalForEquiv: ContravariantMonoidal[Equiv] =
+  def catsContravariantMonoidalForEquiv: ContravariantMonoidal[Equiv] =
     cats.instances.equiv.catsContravariantMonoidalForEquiv
   implicit def catsContravariantForHash: Contravariant[Hash] =
     cats.instances.all.catsContravariantForHash
@@ -195,6 +195,13 @@ object Invariant extends ScalaVersionSpecificInvariantInstances with InvariantIn
   implicit def catsInvariantForFractional: Invariant[Fractional] =
     cats.instances.invariant.catsInvariantForFractional
 
+  implicit def catsDecidableForEquiv: Decidable[Equiv] =
+    cats.instances.equiv.catsDecidableForEquiv
+  implicit def catsDecidableForEq: Decidable[Eq] =
+    cats.instances.eq.catsDecidableForEq
+  implicit def catsDecidableForPredicate: Decidable[* => Boolean] =
+    cats.instances.function.catsStdDecidableForPredicate
+
   implicit val catsInvariantMonoid: Invariant[Monoid] = new Invariant[Monoid] {
 
     def imap[A, B](fa: Monoid[A])(f: A => B)(g: B => A): Monoid[B] =

core/src/main/scala/cats/Semigroupal.scala

@@ -108,15 +108,17 @@ object Semigroupal extends ScalaVersionSpecificSemigroupalInstances with Semigro
     cats.instances.ordering.catsContravariantMonoidalForOrdering
   implicit val catsSemigroupalForPartialOrdering: Semigroupal[PartialOrdering] =
     cats.instances.partialOrdering.catsContravariantMonoidalForPartialOrdering
-  implicit val catsSemigroupalForEq: Semigroupal[Eq] = cats.instances.eq.catsContravariantMonoidalForEq
+  implicit val catsSemigroupalForEq: Semigroupal[Eq] = cats.instances.eq.catsDecidableForEq
   implicit val catsSemigroupalForEquiv: Semigroupal[Equiv] =
-    cats.instances.equiv.catsContravariantMonoidalForEquiv
+    cats.instances.equiv.catsDecidableForEquiv
   implicit val catsSemigroupalForMonoid: Semigroupal[Monoid] =
     cats.instances.invariant.catsSemigroupalForMonoid
   implicit val catsSemigroupalForSemigroup: Semigroupal[Semigroup] =
     cats.instances.invariant.catsInvariantMonoidalSemigroup
   implicit val catsSemigroupalForCommutativeSemigroup: Semigroupal[CommutativeSemigroup] =
     cats.instances.invariant.catsInvariantMonoidalCommutativeSemigroup
+  implicit val catsSemigroupalForPredicate: Semigroupal[* => Boolean] =
+    cats.instances.function.catsStdDecidableForPredicate
 
   /**
    * Summon an instance of [[Semigroupal]] for `F`.

core/src/main/scala/cats/data/Const.scala

@@ -171,7 +171,6 @@ sealed abstract private[data] class ConstInstances extends ConstInstances0 {
 }
 
 sealed abstract private[data] class ConstInstances0 extends ConstInstances1 {
-
   implicit def catsDataContravariantMonoidalForConst[D: Monoid]: ContravariantMonoidal[Const[D, *]] =
     new ContravariantMonoidal[Const[D, *]] {
       override def unit = Const.empty[D, Unit]

core/src/main/scala/cats/data/IdT.scala

@@ -94,6 +94,15 @@ sealed private[data] trait IdTApplicative[F[_]] extends Applicative[IdT[F, *]] w
   def pure[A](a: A): IdT[F, A] = IdT.pure(a)
 }
 
+sealed private[data] trait IdTDecidable[F[_]] extends Decidable[IdT[F, *]] with IdTContravariantMonoidal[F] {
+  implicit val F0: Decidable[F]
+
+  override def sum[A, B](fa: IdT[F, A], fb: IdT[F, B]): IdT[F, Either[A, B]] =
+    IdT(F0.sum(fa.value, fb.value))
+
+  override def zero: IdT[F, Nothing] = IdT[F, Nothing](F0.zero)
+}
+
 sealed private[data] trait IdTContravariantMonoidal[F[_]] extends ContravariantMonoidal[IdT[F, *]] {
   implicit val F0: ContravariantMonoidal[F]
 
@@ -186,6 +195,11 @@ sealed abstract private[data] class IdTInstances6 extends IdTInstances7 {
 sealed abstract private[data] class IdTInstances5 extends IdTInstances6 {
   implicit def catsDataFunctorForIdT[F[_]](implicit F: Functor[F]): Functor[IdT[F, *]] =
     new IdTFunctor[F] { implicit val F0: Functor[F] = F }
+
+  implicit def catsDataDecidableForIdT[F[_]](implicit
+    F: Decidable[F]
+  ): Decidable[IdT[F, *]] =
+    new IdTDecidable[F] { implicit val F0: Decidable[F] = F }
 }
 
 sealed abstract private[data] class IdTInstances4 extends IdTInstances5 {

core/src/main/scala/cats/data/Kleisli.scala

@@ -371,6 +371,10 @@ sealed abstract private[data] class KleisliInstances0 extends KleisliInstances0_
       implicit def F: Monad[F] = F0
     }
 
+  implicit def catsDataDecidableForKleisli[F[_], A](implicit
+    F0: Decidable[F]
+  ): Decidable[Kleisli[F, A, *]] =
+    new KleisliDecidable[F, A] { def F: Decidable[F] = F0 }
 }
 
 sealed abstract private[data] class KleisliInstances0_5 extends KleisliInstances1 {
@@ -613,6 +617,18 @@ private[data] trait KleisliAlternative[F[_], A]
   implicit def F: Alternative[F]
 }
 
+sealed private[data] trait KleisliDecidable[F[_], D]
+    extends Decidable[Kleisli[F, D, *]]
+    with KleisliContravariantMonoidal[F, D] {
+  implicit def F: Decidable[F]
+
+  def sum[A, B](fa: Kleisli[F, D, A], fb: Kleisli[F, D, B]): Kleisli[F, D, Either[A, B]] =
+    Kleisli(d => F.sum(fa.run(d), fb.run(d)))
+
+  override val zero: ReaderT[F, D, Nothing] =
+    Kleisli[F, D, Nothing](_ => F.zero)
+}
+
 sealed private[data] trait KleisliContravariantMonoidal[F[_], D] extends ContravariantMonoidal[Kleisli[F, D, *]] {
   implicit def F: ContravariantMonoidal[F]
 

core/src/main/scala/cats/data/Nested.scala

@@ -65,12 +65,6 @@ sealed abstract private[data] class NestedInstances extends NestedInstances0 {
       val FG: NonEmptyTraverse[λ[α => F[G[α]]]] = NonEmptyTraverse[F].compose[G]
     }
 
-  implicit def catsDataContravariantMonoidalForApplicativeForNested[F[_]: Applicative, G[_]: ContravariantMonoidal]
-    : ContravariantMonoidal[Nested[F, G, *]] =
-    new NestedContravariantMonoidal[F, G] with NestedContravariant[F, G] {
-      val FG: ContravariantMonoidal[λ[α => F[G[α]]]] = Applicative[F].composeContravariantMonoidal[G]
-    }
-
   implicit def catsDataDeferForNested[F[_], G[_]](implicit F: Defer[F]): Defer[Nested[F, G, *]] =
     new Defer[Nested[F, G, *]] {
       def defer[A](fa: => Nested[F, G, A]): Nested[F, G, A] =
@@ -136,6 +130,12 @@ sealed abstract private[data] class NestedInstances1 extends NestedInstances2 {
       val FG: Reducible[λ[α => F[G[α]]]] = Reducible[F].compose[G]
     }
 
+  implicit def catsDataDecidableForApplicativeForNested[F[_]: Applicative, G[_]: Decidable]
+    : Decidable[Nested[F, G, *]] =
+    new NestedDecidable[F, G] with NestedContravariant[F, G] {
+      val FG: Decidable[λ[α => F[G[α]]]] = Applicative[F].composeDecidable[G]
+    }
+
   implicit def catsDataFunctorForContravariantForNested[F[_]: Contravariant, G[_]: Contravariant]
     : Functor[Nested[F, G, *]] =
     new NestedFunctor[F, G] {
@@ -149,6 +149,12 @@ sealed abstract private[data] class NestedInstances2 extends NestedInstances3 {
       val FG: Foldable[λ[α => F[G[α]]]] = Foldable[F].compose[G]
     }
 
+  implicit def catsDataContravariantMonoidalForApplicativeForNested[F[_]: Applicative, G[_]: ContravariantMonoidal]
+    : ContravariantMonoidal[Nested[F, G, *]] =
+    new NestedContravariantMonoidal[F, G] with NestedContravariant[F, G] {
+      val FG: ContravariantMonoidal[λ[α => F[G[α]]]] = Applicative[F].composeContravariantMonoidal[G]
+    }
+
   implicit def catsDataContravariantForCovariantNested[F[_]: Contravariant, G[_]: Functor]
     : Contravariant[Nested[F, G, *]] =
     new NestedContravariant[F, G] {
@@ -394,6 +400,17 @@ private[data] trait NestedContravariant[F[_], G[_]] extends Contravariant[Nested
     Nested(FG.contramap(fga.value)(f))
 }
 
+private[data] trait NestedDecidable[F[_], G[_]]
+    extends Decidable[Nested[F, G, *]]
+    with NestedContravariantMonoidal[F, G] {
+  def FG: Decidable[λ[α => F[G[α]]]]
+
+  def sum[A, B](fa: Nested[F, G, A], fb: Nested[F, G, B]): Nested[F, G, Either[A, B]] =
+    Nested(FG.sum(fa.value, fb.value))
+
+  def zero: Nested[F, G, Nothing] = Nested[F, G, Nothing](FG.zero)
+}
+
 private[data] trait NestedContravariantMonoidal[F[_], G[_]] extends ContravariantMonoidal[Nested[F, G, *]] {
   def FG: ContravariantMonoidal[λ[α => F[G[α]]]]
 

core/src/main/scala/cats/data/Op.scala

@@ -41,6 +41,15 @@ sealed abstract private[data] class OpInstances extends OpInstances0 {
   implicit def catsDataCategoryForOp[Arr[_, _]](implicit ArrC: Category[Arr]): Category[Op[Arr, *, *]] =
     new OpCategory[Arr] { def Arr: Category[Arr] = ArrC }
 
+  implicit def catsDataDecidableForOp[Arr[_, _], R](implicit
+    ArrC: ArrowChoice[Arr],
+    monn: Monoid[R]
+  ): Decidable[Op[Arr, R, *]] =
+    new OpDecidable[Arr, R] {
+      def Arr: ArrowChoice[Arr] = ArrC
+      def M: Monoid[R] = monn
+    }
+
   implicit def catsDataEqForOp[Arr[_, _], A, B](implicit ArrEq: Eq[Arr[B, A]]): Eq[Op[Arr, A, B]] =
     new OpEq[Arr, A, B] { def Arr: Eq[Arr[B, A]] = ArrEq }
 
@@ -52,6 +61,17 @@ sealed abstract private[data] class OpInstances extends OpInstances0 {
 sealed abstract private[data] class OpInstances0 {
   implicit def catsDataComposeForOp[Arr[_, _]](implicit ArrC: Compose[Arr]): Compose[Op[Arr, *, *]] =
     new OpCompose[Arr] { def Arr: Compose[Arr] = ArrC }
+
+  implicit def catsDataContravariantMonoidalForOp[Arr[_, _], R](implicit
+    ArrC: Arrow[Arr],
+    M0: Monoid[R]
+  ): ContravariantMonoidal[Op[Arr, R, *]] =
+    new OpContravariantMonoidal[Arr, R] { def Arr = ArrC; def M = M0 }
+}
+
+sealed abstract private[data] class OpInstances1 {
+  implicit def catsDataContravariantForOp[Arr[_, _], R](implicit ArrC: Arrow[Arr]): Contravariant[Op[Arr, R, *]] =
+    new OpContravariant[Arr, R] { def Arr = ArrC }
 }
 
 private[data] trait OpCategory[Arr[_, _]] extends Category[Op[Arr, *, *]] with OpCompose[Arr] {
@@ -67,6 +87,39 @@ private[data] trait OpCompose[Arr[_, _]] extends Compose[Op[Arr, *, *]] {
     f.compose(g)
 }
 
+private[data] trait OpDecidable[Arr[_, _], R] extends Decidable[Op[Arr, R, *]] with OpContravariantMonoidal[Arr, R] {
+  implicit def Arr: ArrowChoice[Arr]
+  implicit def M: Monoid[R]
+
+  def sum[A, B](fa: Op[Arr, R, A], fb: Op[Arr, R, B]): Op[Arr, R, Either[A, B]] =
+    Op(Arr.choice(fa.run, fb.run))
+
+  override def zero: Op[Arr, R, Nothing] =
+    Op[Arr, R, Nothing](
+      Arr.lift[Nothing, R](_ => throw new Exception("Materialized a value of type `Nothing`, this is a bug!"))
+    )
+}
+
+private[data] trait OpContravariantMonoidal[Arr[_, _], R]
+    extends OpContravariant[Arr, R]
+    with ContravariantMonoidal[Op[Arr, R, *]] {
+  implicit def Arr: Arrow[Arr]
+  implicit def M: Monoid[R]
+
+  def unit: Op[Arr, R, Unit] =
+    Op(Arr.lift(Function.const(M.empty)))
+
+  def product[A, B](fa: Op[Arr, R, A], fb: Op[Arr, R, B]): Op[Arr, R, (A, B)] =
+    Op(Arr.compose(Arr.lift((M.combine _).tupled), Arr.split(fa.run, fb.run)))
+}
+
+private[data] trait OpContravariant[Arr[_, _], R] extends Contravariant[Op[Arr, R, *]] {
+  implicit def Arr: Arrow[Arr]
+
+  def contramap[A, B](fa: Op[Arr, R, A])(f: B => A): Op[Arr, R, B] =
+    Op(Arr.compose(fa.run, Arr.lift(f)))
+}
+
 private[data] trait OpEq[Arr[_, _], A, B] extends Eq[Op[Arr, A, B]] {
   implicit def Arr: Eq[Arr[B, A]]