add OptionT.liftF and update related docs and tests. Close issue #659

AUTHORS.md

@@ -13,6 +13,7 @@ This file lists the people whose contributions have made Cats
 possible:
 
  * Adelbert Chang
+ * Alessandro Lacava
  * Alissa Pajer
  * Alistair Johnson
  * Amir Mohammad Saied

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

@@ -120,6 +120,12 @@ object OptionT extends OptionTInstances {
     def apply[A](value: Option[A])(implicit F: Applicative[F]): OptionT[F, A] =
       OptionT(F.pure(value))
   }
+
+  /**
+    * Lifts the `F[A]` Functor into an `OptionT[F, A]`.
+    *
+    */
+  def liftF[F[_], A](fa: F[A])(implicit F: Functor[F]): OptionT[F, A] = OptionT(F.map(fa)(Option(_)))
 }
 
 private[data] sealed trait OptionTInstances1 {

docs/src/main/tut/optiont.md

@@ -51,6 +51,33 @@ val noWelcome: OptionT[Future, String] = customGreetingT.filterNot(_.contains("w
 val withFallback: Future[String] = customGreetingT.getOrElse("hello, there!")
 ```
 
+## From `Option[A]` and/or `F[A]` to `OptionT[F, A]`
+
+Sometimes you may have an `Option[A]` and/or `F[A]` and want to *lift* them into an `OptionT[F, A]`. For this purpose `OptionT` exposes two useful methods, namely `fromOption` and `liftF`, respectively. E.g.:
+
+```tut:silent
+import scala.concurrent.Future
+import scala.concurrent.ExecutionContext.Implicits.global
+
+import cats.data.OptionT
+import cats.std.future._
+
+val greetingFO: Future[Option[String]] = Future.successful(Some("Hello"))
+
+val firstnameF: Future[String] = Future.successful("Jane")
+
+val lastnameO: Option[String] = Some("Doe")
+
+val ot: OptionT[Future, String] = for {
+  g <- OptionT(greetingFO)
+  f <- OptionT.liftF(firstnameF)
+  l <- OptionT.fromOption(lastnameO)
+} yield s"$g $f $l"
+
+val result: Future[Option[String]] = ot.value // Future(Some("Hello Jane Doe"))
+
+```
+
 ## Beyond map
 
 Sometimes the operation you want to perform on an `Option[Future[String]]` might not be as simple as just wrapping the `Option` method in a `Future.map` call. For example, what if we want to greet the customer with their custom greeting if it exists but otherwise fall back to a default `Future[String]` greeting? Without `OptionT`, this implementation might look like:

tests/src/test/scala/cats/tests/OptionTTests.scala

@@ -111,6 +111,12 @@ class OptionTTests extends CatsSuite {
     }
   }
 
+  test("liftF") {
+    forAll { (xs: List[Int]) =>
+      xs.map(Option(_)) should ===(OptionT.liftF(xs).value)
+    }
+  }
+
   test("show"){
     val xor: String Xor Option[Int] = Xor.right(Some(1))
     OptionT[Xor[String, ?], Int](xor).show should === ("Xor.Right(Some(1))")