/core/src/main/scala/scalaz/Bind.scala

  1package scalaz
  2
  3////
  4/**
  5 * An [[scalaz.Apply]] functor, where a lifted function can introduce
  6 * new values _and_ new functor context to be incorporated into the
  7 * lift context.  The essential new operation of [[scalaz.Monad]]s.
  8 *
  9 * @see [[scalaz.Bind.BindLaw]]
 10 */
 11////
 12trait Bind[F[_]] extends Apply[F] { self =>
 13  ////
 14
 15  /** Equivalent to `join(map(fa)(f))`. */
 16  def bind[A, B](fa: F[A])(f: A => F[B]): F[B]
 17
 18  // Derived combinators with big consequences:
 19  //
 20  // - ap must be sequential, f first then fa.
 21  // - apply2 must be sequential, fa first then fb.
 22  //
 23  // These are why IO is not parallel by default, by design.
 24  override def ap[A, B](fa: => F[A])(f: => F[A => B]): F[B] = {
 25    val fa0 = Need(fa)
 26    bind(f)(x => map(fa0.value)(x))
 27  }
 28  override def apply2[A, B, C](fa: => F[A], fb: => F[B])(f: (A, B) => C): F[C] = {
 29    val fb0 = Need(fb)
 30    bind(fa)(a => map(fb0.value)(b => f(a, b)))
 31  }
 32
 33  /** Sequence the inner `F` of `FFA` after the outer `F`, forming a
 34   * single `F[A]`. */
 35  def join[A](ffa: F[F[A]]): F[A] = bind(ffa)(a => a)
 36
 37  // derived functions
 38
 39  /**
 40   * `if` lifted into a binding.  Unlike `lift3((t,c,a)=>if(t)c else
 41   * a)`, this will only include context from the chosen of `ifTrue`
 42   * and `ifFalse`, not the other.
 43   */
 44  def ifM[B](value: F[Boolean], ifTrue: => F[B], ifFalse: => F[B]): F[B] = {
 45    val t = Need(ifTrue)
 46    val f = Need(ifFalse)
 47    bind(value)(if(_) t.value else f.value)
 48  }
 49
 50  /** Pair `A` with the result of function application. */
 51  def mproduct[A, B](fa: F[A])(f: A => F[B]): F[(A, B)] =
 52    bind(fa)(a => map(f(a))((a, _)))
 53
 54  /**The product of Bind `F` and `G`, `[x](F[x], G[x]])`, is a Bind */
 55  def product[G[_]](implicit G0: Bind[G]): Bind[λ[α => (F[α], G[α])]] =
 56    new ProductBind[F, G] {
 57      def F = self
 58      def G = G0
 59    }
 60
 61  trait BindLaw extends ApplyLaw {
 62    /**
 63     * As with semigroups, monadic effects only change when their
 64     * order is changed, not when the order in which they're
 65     * combined changes.
 66     */
 67    def associativeBind[A, B, C](fa: F[A], f: A => F[B], g: B => F[C])(implicit FC: Equal[F[C]]): Boolean =
 68      FC.equal(bind(bind(fa)(f))(g), bind(fa)((a: A) => bind(f(a))(g)))
 69
 70    /** `ap` is consistent with `bind`. */
 71    def apLikeDerived[A, B](fa: F[A], f: F[A => B])(implicit FB: Equal[F[B]]): Boolean =
 72      FB.equal(ap(fa)(f), bind(f)(f => map(fa)(f)))
 73  }
 74  def bindLaw = new BindLaw {}
 75
 76  ////
 77  val bindSyntax: scalaz.syntax.BindSyntax[F] =
 78    new scalaz.syntax.BindSyntax[F] { def F = Bind.this }
 79}
 80
 81object Bind {
 82  @inline def apply[F[_]](implicit F: Bind[F]): Bind[F] = F
 83
 84  import Isomorphism._
 85
 86  def fromIso[F[_], G[_]](D: F <~> G)(implicit E: Bind[G]): Bind[F] =
 87    new IsomorphismBind[F, G] {
 88      override def G: Bind[G] = E
 89      override def iso: F <~> G = D
 90    }
 91
 92  ////
 93
 94  ////
 95}
 96
 97trait IsomorphismBind[F[_], G[_]] extends Bind[F] with IsomorphismApply[F, G]{
 98  implicit def G: Bind[G]
 99  ////
100
101  override def bind[A, B](fa: F[A])(f: A => F[B]): F[B] =
102    iso.from(G.bind(iso.to(fa))(f.andThen(iso.to.apply)))
103  ////
104}