Add Representable Functor (#2284)

* Add Representable Functor and RepresentableStore

* code review updates

* extend AnyVal for representable syntax

* updates to RepresentableSyntax

core/src/main/scala/cats/Representable.scala

@@ -0,0 +1,90 @@
+package cats
+
+/**
+ * Representable.
+ *
+ * Is a witness to the isomorphism forall A. F[A] <-> Representation => A
+ *
+ * Must obey the laws defined in cats.laws.RepresentableLaws
+ * i.e.
+ * tabulate andThen index = identity
+ * index andThen tabulate = identity
+ *
+ * Inspired by the Haskell representable package
+ * http://hackage.haskell.org/package/representable-functors-3.2.0.2/docs/Data-Functor-Representable.html
+ */
+trait Representable[F[_]] extends Serializable {
+
+  def F: Functor[F]
+
+  type Representation
+
+  /**
+   * Create a function that "indexes" into the `F` structure using `Representation`
+   */
+  def index[A](f: F[A]): Representation => A
+
+  /**
+   * Reconstructs the `F` structure using the index function
+   */
+  def tabulate[A](f: Representation => A): F[A]
+}
+
+private trait RepresentableMonad[F[_], R] extends Monad[F] {
+
+  def R: Representable.Aux[F, R]
+
+  override def pure[A](x: A): F[A] = R.tabulate(_ => x)
+
+  override def flatMap[A, B](fa: F[A])(f: A => F[B]): F[B] =
+    R.tabulate(a => R.index(f(R.index(fa)(a)))(a))
+
+  override def tailRecM[A, B](a: A)(f: A => F[Either[A, B]]): F[B] = {
+    R.tabulate { r: R =>
+      @annotation.tailrec
+      def loop(a: A): B =
+        R.index(f(a))(r) match {
+          case Right(b) => b
+          case Left(a) => loop(a)
+        }
+
+      loop(a)
+    }
+  }
+}
+
+private trait RepresentableBimonad[F[_], R] extends RepresentableMonad[F, R] with Bimonad[F] {
+
+  def M: Monoid[R]
+
+  override def coflatMap[A, B](w: F[A])(f: F[A] => B): F[B] =
+    R.tabulate(m => f(R.tabulate(x => R.index(w)(M.combine(m, x)))))
+
+  override def extract[A](fa: F[A]): A =
+    R.index(fa)(M.empty)
+}
+
+object Representable {
+  type Aux[F[_], R] = Representable[F] { type Representation = R }
+
+  /**
+   * Summon the `Representable` instance for `F`
+   */
+  def apply[F[_]](implicit ev: Representable[F]): Representable[F] = ev
+
+  /**
+   * Derives a `Monad` instance for any `Representable` functor
+   */
+  def monad[F[_]](implicit Rep: Representable[F]): Monad[F] = new RepresentableMonad[F, Rep.Representation] {
+    override def R: Representable.Aux[F, Rep.Representation] = Rep
+  }
+
+  /**
+   * Derives a `Bimonad` instance for any `Representable` functor whos representation
+   * has a `Monoid` instance.
+   */
+  def bimonad[F[_], R](implicit Rep: Representable.Aux[F, R], Mon: Monoid[R]): Bimonad[F] = new RepresentableBimonad[F, R] {
+    override def R: Representable.Aux[F, R] = Rep
+    override def M: Monoid[R] = Mon
+  }
+}

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

@@ -185,6 +185,29 @@ private[data] sealed abstract class KleisliInstances0 extends KleisliInstances1
 
   implicit def catsDataContravariantMonoidalForKleisli[F[_], A](implicit F0: ContravariantMonoidal[F]): ContravariantMonoidal[Kleisli[F, A, ?]] =
     new KleisliContravariantMonoidal[F, A] {  def F: ContravariantMonoidal[F] = F0 }
+
+  /**
+   * Witness for: Kleisli[M, E, A] <-> (E, R) => A
+   * if M is Representable
+   */
+  implicit def catsDataRepresentableForKleisli[M[_], R, E](implicit
+    R: Representable.Aux[M, R],
+    FK: Functor[Kleisli[M, E, ?]]): Representable.Aux[Kleisli[M, E, ?], (E, R)] = new Representable[Kleisli[M, E, ?]] {
+
+      override type Representation = (E, R)
+
+      override val F: Functor[Kleisli[M, E, ?]] = FK
+
+      def index[A](f: Kleisli[M, E, A]): Representation => A = {
+        case (e, r) => R.index(f.run(e))(r)
+      }
+
+      def tabulate[A](f: Representation => A): Kleisli[M, E, A] = {
+        def curry[X, Y, Z](f: (X, Y) => Z): X => Y => Z = x => y => f(x, y)
+
+        Kleisli[M, E, A](curry(Function.untupled(f)) andThen R.tabulate)
+      }
+    }
 }
 
 private[data] sealed abstract class KleisliInstances1 extends KleisliInstances2 {

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

@@ -0,0 +1,61 @@
+package cats.data
+
+import cats.{Comonad, Functor, Representable}
+
+/**
+ * A generalisation of the Store comonad, for any `Representable` functor.
+ * `Store` is the dual of `State`
+ */
+final case class RepresentableStore[F[_], S, A](fa: F[A], index: S)(implicit R: Representable.Aux[F, S]) {
+  /**
+   * Inspect the value at "index" s
+   */
+  def peek(s: S): A = R.index(fa)(s)
+
+  /**
+   * Extract the value at the current index.
+   */
+  lazy val extract: A = peek(index)
+
+  /**
+   * Duplicate the store structure
+   */
+  lazy val coflatten: RepresentableStore[F, S, RepresentableStore[F, S, A]] =
+    RepresentableStore(R.tabulate(idx => RepresentableStore(fa, idx)), index)
+
+  def map[B](f: A => B): RepresentableStore[F, S, B] = {
+    RepresentableStore(R.F.map(fa)(f), index)
+  }
+
+  /**
+   * Given a functorial computation on the index `S` peek at the value in that functor.
+   *
+   * {{{
+   *   import cats._, implicits._, data.Store
+   *
+   *   val initial = List("a", "b", "c")
+   *   val store = Store(idx => initial.get(idx).getOrElse(""), 0)
+   *   val adjacent = store.experiment[List] { idx => List(idx - 1, idx, idx + 1) }
+   *
+   *   require(adjacent == List("", "a", "b"))
+   * }}}
+   */
+  def experiment[G[_]](fn: S => G[S])(implicit G: Functor[G]): G[A] = {
+    G.map(fn(index))(peek)
+  }
+}
+
+object RepresentableStore {
+
+  implicit def catsDataRepresentableStoreComonad[F[_], S](implicit R: Representable[F]): Comonad[RepresentableStore[F, S, ?]] =
+    new Comonad[RepresentableStore[F, S, ?]] {
+      override def extract[B](x: RepresentableStore[F, S, B]): B =
+        x.extract
+
+      override def coflatMap[A, B](fa: RepresentableStore[F, S, A])(f: RepresentableStore[F, S, A] => B): RepresentableStore[F, S, B] =
+        fa.coflatten.map(f)
+
+      override def map[A, B](fa: RepresentableStore[F, S, A])(f: A => B): RepresentableStore[F, S, B] =
+        fa.map(f)
+    }
+}

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

@@ -66,4 +66,11 @@ package object data {
 
   type RWS[E, L, S, A] = ReaderWriterState[E, L, S, A]
   val RWS = ReaderWriterState
+
+  type Store[S, A] = RepresentableStore[S => ?, S, A]
+  object Store {
+    import cats.instances.function._
+    def apply[S, A](f: S => A, s: S): Store[S, A] =
+      RepresentableStore[S => ?, S, A](f, s)
+  }
 }

core/src/main/scala/cats/implicits.scala

@@ -5,3 +5,4 @@ object implicits
     with syntax.AllSyntaxBinCompat0
     with syntax.AllSyntaxBinCompat1
     with instances.AllInstances
+    with instances.AllInstancesBinCompat0

core/src/main/scala/cats/instances/all.scala

@@ -32,3 +32,7 @@ trait AllInstances
   with    TupleInstances
   with    UUIDInstances
   with    VectorInstances
+
+trait AllInstancesBinCompat0
+    extends FunctionInstancesBinCompat0
+    with    Tuple2InstancesBinCompat0

core/src/main/scala/cats/instances/function.scala

@@ -10,6 +10,18 @@ import annotation.tailrec
 trait FunctionInstances extends cats.kernel.instances.FunctionInstances
     with Function0Instances with Function1Instances
 
+trait FunctionInstancesBinCompat0 {
+  /**
+   * Witness for: E => A <-> E => A
+   */
+  implicit def catsStdRepresentableForFunction1[E](implicit EF: Functor[E => ?]): Representable.Aux[E => ?, E] = new Representable[E => ?] {
+    override type Representation = E
+    override val F: Functor[E => ?] = EF
+    override def tabulate[A](f: E => A): E => A = f
+    override def index[A](f: E => A): E => A = f
+  }
+}
+
 private[instances] sealed trait Function0Instances extends Function0Instances0 {
   implicit val catsStdBimonadForFunction0: Bimonad[Function0] =
     new Bimonad[Function0] {

core/src/main/scala/cats/instances/package.scala

@@ -1,7 +1,7 @@
 package cats
 
 package object instances {
-  object all             extends AllInstances
+  object all             extends AllInstances with AllInstancesBinCompat0
   object bigInt          extends BigIntInstances
   object bigDecimal      extends BigDecimalInstances
   object bitSet          extends BitSetInstances
@@ -15,6 +15,7 @@ package object instances {
   object equiv           extends EquivInstances
   object float           extends FloatInstances
   object function        extends FunctionInstances
+                         with    FunctionInstancesBinCompat0
   object future          extends FutureInstances
   object int             extends IntInstances
   object invariant       extends InvariantMonoidalInstances
@@ -36,6 +37,7 @@ package object instances {
   object string          extends StringInstances
   object try_            extends TryInstances
   object tuple           extends TupleInstances
+                         with    Tuple2InstancesBinCompat0
   object unit            extends UnitInstances
   object uuid            extends UUIDInstances
   object vector          extends VectorInstances

core/src/main/scala/cats/instances/tuple.scala

@@ -2,10 +2,33 @@ package cats
 package instances
 
 import cats.kernel.{CommutativeMonoid, CommutativeSemigroup}
+
 import scala.annotation.tailrec
 
 trait TupleInstances extends Tuple2Instances with cats.kernel.instances.TupleInstances
 
+trait Tuple2InstancesBinCompat0 {
+
+  /**
+   * Witness for: (A, A) <-> Boolean => A
+   */
+  implicit def catsDataRepresentableForPair(implicit PF: Functor[λ[P => (P, P)]]): Representable.Aux[λ[P => (P, P)], Boolean] = new Representable[λ[P => (P, P)]] {
+    override type Representation = Boolean
+    override val F: Functor[λ[P => (P, P)]] = PF
+
+    override def tabulate[A](f: Boolean => A): (A, A) = (f(true), f(false))
+
+    override def index[A](pair: (A, A)): Boolean => A = {
+      case true => pair._1
+      case false => pair._2
+    }
+  }
+
+  implicit val catsDataFunctorForPair: Functor[λ[P => (P, P)]] = new Functor[λ[P => (P, P)]] {
+    override def map[A, B](fa: (A, A))(f: A => B): (B, B) = (f(fa._1), f(fa._2))
+  }
+}
+
 sealed trait Tuple2Instances extends Tuple2Instances1 {
   implicit val catsStdBitraverseForTuple2: Bitraverse[Tuple2] =
     new Bitraverse[Tuple2] {

core/src/main/scala/cats/package.scala

@@ -77,6 +77,18 @@ package object cats {
       override def isEmpty[A](fa: Id[A]): Boolean = false
   }
 
+  /**
+   * Witness for: Id[A] <-> Unit => A
+   */
+  implicit val catsRepresentableForId: Representable.Aux[Id, Unit] = new Representable[Id] {
+    override type Representation = Unit
+    override val F: Functor[Id] = Functor[Id]
+
+    override def tabulate[A](f: Unit => A): Id[A] = f(())
+
+    override def index[A](f: Id[A]): Unit => A = (_: Unit) => f
+  }
+
   implicit val catsParallelForId: Parallel[Id, Id] = Parallel.identity
 
   type Eq[A] = cats.kernel.Eq[A]

core/src/main/scala/cats/syntax/all.scala

@@ -67,3 +67,4 @@ trait AllSyntaxBinCompat1
     with ParallelFlatSyntax
     with SetSyntax
     with ValidatedExtensionSyntax
+    with RepresentableSyntax

core/src/main/scala/cats/syntax/package.scala

@@ -42,6 +42,7 @@ package object syntax {
   object partialOrder extends PartialOrderSyntax
   object profunctor extends ProfunctorSyntax
   object reducible extends ReducibleSyntax
+  object representable extends RepresentableSyntax
   object semigroup extends SemigroupSyntax
   object semigroupal extends SemigroupalSyntax
   object semigroupk extends SemigroupKSyntax

core/src/main/scala/cats/syntax/representable.scala

@@ -0,0 +1,18 @@
+package cats
+package syntax
+
+trait RepresentableSyntax {
+  implicit final def catsSyntaxTabulate[A, R](f: R => A): TabulateOps[A, R] =
+    new TabulateOps[A, R](f)
+
+  implicit final def catsSyntaxIndex[F[_], A](fa: F[A]): IndexOps[F, A] =
+    new IndexOps[F, A](fa)
+}
+
+final class IndexOps[F[_], A](val fa: F[A]) extends AnyVal {
+  def index[R](implicit R: Representable.Aux[F, R]): R => A = R.index(fa)
+}
+
+final class TabulateOps[A, R](val f: R => A) extends AnyVal {
+  def tabulate[F[_]](implicit R: Representable.Aux[F, R]): F[A] = R.tabulate(f)
+}

laws/src/main/scala/cats/laws/RepresentableLaws.scala

@@ -0,0 +1,24 @@
+package cats
+package laws
+
+
+/**
+ * Laws that must be obeyed by any `Representable` functor.
+ */
+trait RepresentableLaws[F[_], R] {
+
+    implicit val R: Representable.Aux[F, R]
+
+    def indexTabulateIsId[B](fb: F[B]): IsEq[F[B]] = {
+        R.tabulate(R.index(fb)) <-> fb
+    }
+
+    def tabulateIndexIsId[B](f: R => B, x: R): IsEq[B] = {
+        R.index(R.tabulate(f))(x) <-> f(x)
+    }
+}
+
+object RepresentableLaws {
+    def apply[F[_], R](implicit ev: Representable.Aux[F, R]): RepresentableLaws[F, R] =
+        new RepresentableLaws[F, R] { val R: Representable.Aux[F, R] = ev }
+}

laws/src/main/scala/cats/laws/discipline/Arbitrary.scala

@@ -250,11 +250,32 @@ object arbitrary extends ArbitraryInstances0 {
     F: Arbitrary[(E, SA) => F[(L, SB, A)]]): Arbitrary[IndexedReaderWriterStateT[F, E, L, SA, SB, A]] =
     Arbitrary(F.arbitrary.map(IndexedReaderWriterStateT(_)))
 
+
+  implicit def catsLawsArbitraryForRepresentableStore[F[_], S, A](implicit
+    R: Representable.Aux[F, S],
+    ArbS: Arbitrary[S],
+    ArbFA: Arbitrary[F[A]]
+  ): Arbitrary[RepresentableStore[F, S, A]] = {
+    Arbitrary {
+      for {
+        fa <- ArbFA.arbitrary
+        s <- ArbS.arbitrary
+      } yield {
+        RepresentableStore[F, S, A](fa, s)
+      }
+    }
+  }
+
+  implicit def catsLawsCogenForRepresentableStore[F[_]: Representable, S, A](implicit CA: Cogen[A]): Cogen[RepresentableStore[F, S, A]] = {
+    CA.contramap(_.extract)
+  }
+
   implicit def catsLawsArbitraryForAndThen[A, B](implicit F: Arbitrary[A => B]): Arbitrary[AndThen[A, B]] =
     Arbitrary(F.arbitrary.map(AndThen(_)))
 
   implicit def catsLawsCogenForAndThen[A, B](implicit F: Cogen[A => B]): Cogen[AndThen[A, B]] =
     Cogen((seed, x) => F.perturb(seed, x))
+
 }
 
 private[discipline] sealed trait ArbitraryInstances0 {