Ior syntax

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

@@ -1,7 +1,9 @@
 package cats
 package data
 
+import cats.data.Validated.{Invalid, Valid}
 import cats.functor.Bifunctor
+
 import scala.annotation.tailrec
 
 /** Represents a right-biased disjunction that is either an `A`, or a `B`, or both an `A` and a `B`.
@@ -47,6 +49,7 @@ sealed abstract class Ior[+A, +B] extends Product with Serializable {
   final def unwrap: Either[Either[A, B], (A, B)] = fold(a => Left(Left(a)), b => Left(Right(b)), (a, b) => Right((a, b)))
 
   final def toEither: Either[A, B] = fold(Left(_), Right(_), (_, b) => Right(b))
+  final def toValidated: Validated[A, B] = fold(Invalid(_), Valid(_), (_, b) => Valid(b))
   final def toOption: Option[B] = right
   final def toList: List[B] = right.toList
 
@@ -102,7 +105,7 @@ sealed abstract class Ior[+A, +B] extends Product with Serializable {
     fold(identity, ev, (_, b) => ev(b))
 
   // scalastyle:off cyclomatic.complexity
-  final def append[AA >: A, BB >: B](that: AA Ior BB)(implicit AA: Semigroup[AA], BB: Semigroup[BB]): AA Ior BB = this match {
+  final def combine[AA >: A, BB >: B](that: AA Ior BB)(implicit AA: Semigroup[AA], BB: Semigroup[BB]): AA Ior BB = this match {
     case Ior.Left(a1) => that match {
       case Ior.Left(a2) => Ior.Left(AA.combine(a1, a2))
       case Ior.Right(b2) => Ior.Both(a1, b2)
@@ -150,7 +153,7 @@ private[data] sealed abstract class IorInstances extends IorInstances0 {
   }
 
   implicit def catsDataSemigroupForIor[A: Semigroup, B: Semigroup]: Semigroup[Ior[A, B]] = new Semigroup[Ior[A, B]] {
-    def combine(x: Ior[A, B], y: Ior[A, B]) = x.append(y)
+    def combine(x: Ior[A, B], y: Ior[A, B]) = x.combine(y)
   }
 
   implicit def catsDataMonadForIor[A: Semigroup]: Monad[A Ior ?] = new Monad[A Ior ?] {
@@ -198,6 +201,9 @@ private[data] sealed trait IorFunctions {
   def left[A, B](a: A): A Ior B = Ior.Left(a)
   def right[A, B](b: B): A Ior B = Ior.Right(b)
   def both[A, B](a: A, b: B): A Ior B = Ior.Both(a, b)
+  def rightNel[A, B](b: B): IorNel[A, B] = right(b)
+  def leftNel[A, B](a: A): IorNel[A, B] = left(NonEmptyList.of(a))
+  def bothNel[A, B](a: A, b: B): IorNel[A, B] = Ior.Both(NonEmptyList.of(a), b)
 
   /**
    * Create an `Ior` from two Options if at least one of them is defined.

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

@@ -75,6 +75,11 @@ sealed abstract class Validated[+E, +A] extends Product with Serializable {
    */
   def toOption: Option[A] = fold(_ => None, Some.apply)
 
+  /**
+    * Returns Valid values wrapped in Ior.Right, and None for Ior.Left values
+    */
+  def toIor: Ior[E, A] = fold(Ior.left, Ior.right)
+
   /**
    * Convert this value to a single element List if it is Valid,
    * otherwise return an empty List
@@ -430,13 +435,18 @@ private[data] trait ValidatedFunctions {
   }
 
   /**
-   * Converts an `Either[A, B]` to an `Validated[A, B]`.
+   * Converts an `Either[A, B]` to a `Validated[A, B]`.
    */
   def fromEither[A, B](e: Either[A, B]): Validated[A, B] = e.fold(invalid, valid)
 
   /**
-   * Converts an `Option[B]` to an `Validated[A, B]`, where the provided `ifNone` values is returned on
+   * Converts an `Option[B]` to a `Validated[A, B]`, where the provided `ifNone` values is returned on
    * the invalid of the `Validated` when the specified `Option` is `None`.
    */
   def fromOption[A, B](o: Option[B], ifNone: => A): Validated[A, B] = o.fold(invalid[A, B](ifNone))(valid)
+
+  /**
+    * Converts an `Ior[A, B]` to a `Validated[A, B]`.
+    */
+  def fromIor[A, B](ior: Ior[A, B]): Validated[A, B] = ior.fold(invalid, valid, (_, b) => valid(b))
 }

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

@@ -3,6 +3,7 @@ package cats
 package object data {
   type NonEmptyStream[A] = OneAnd[Stream, A]
   type ValidatedNel[+E, +A] = Validated[NonEmptyList[E], A]
+  type IorNel[+B, +A] = Ior[NonEmptyList[B], A]
 
   def NonEmptyStream[A](head: A, tail: Stream[A] = Stream.empty): NonEmptyStream[A] =
     OneAnd(head, tail)

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

@@ -22,6 +22,7 @@ trait AllSyntax
     with FunctorFilterSyntax
     with GroupSyntax
     with InvariantSyntax
+    with IorSyntax
     with ListSyntax
     with MonadCombineSyntax
     with MonadErrorSyntax

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

@@ -0,0 +1,163 @@
+package cats.syntax
+
+import cats.data.{Ior, IorNel, NonEmptyList}
+
+trait IorSyntax {
+  implicit def catsSyntaxIorId[A](a: A): IorIdOps[A] = new IorIdOps(a)
+  implicit def catsSyntaxListIorNel[A, B](list: List[IorNel[A, B]]): IorNelListOps[A, B] =
+    new IorNelListOps(list)
+}
+
+final class IorIdOps[A](val a: A) extends AnyVal {
+  /**
+    * Wrap a value in `Ior.Right`.
+    *
+    * Example:
+    * {{{
+    * scala> import cats.data.Ior
+    * scala> import cats.implicits._
+    *
+    * scala> "hello".rightIor[String]
+    * res0: Ior[String, String] = Right(hello)
+    * }}}
+    */
+  def rightIor[B]: Ior[B, A] = Ior.right(a)
+
+  /**
+    * Wrap a value in `Ior.Left`.
+    *
+    * Example:
+    * {{{
+    * scala> import cats.data.Ior
+    * scala> import cats.implicits._
+    *
+    * scala> "error".leftIor[String]
+    * res0: Ior[String, String] = Left(error)
+    * }}}
+    */
+  def leftIor[B]: Ior[A, B] = Ior.left(a)
+
+  /**
+    * Wrap a value in the right side of `Ior.Both`.
+    *
+    * Example:
+    * {{{
+    * scala> import cats.data.Ior
+    * scala> import cats.implicits._
+    *
+    * scala> "hello".putRightIor("error")
+    * res0: Ior[String, String] = Both(error,hello)
+    * }}}
+    */
+  def putRightIor[B](left: B): Ior[B, A] = Ior.both(left, a)
+
+  /**
+    * Wrap a value in the left side of `Ior.Both`.
+    *
+    * Example:
+    * {{{
+    * scala> import cats.data.Ior
+    * scala> import cats.implicits._
+    *
+    * scala> "error".putLeftIor("hello")
+    * res0: Ior[String, String] = Both(error,hello)
+    * }}}
+    */
+  def putLeftIor[B](right: B): Ior[A, B] = Ior.both(a, right)
+
+  /**
+    * Wrap a value in a NonEmptyList in `Ior.Right`.
+    *
+    * Example:
+    * {{{
+    * scala> import cats.data.IorNel
+    * scala> import cats.implicits._
+    *
+    * scala> "hello".rightIorNel[String]
+    * res0: IorNel[String, String] = Right(hello)
+    * }}}
+    */
+  def rightIorNel[B]: IorNel[B, A] = Ior.rightNel(a)
+
+  /**
+    * Wrap a value in a NonEmptyList in `Ior.Left`.
+    *
+    * Example:
+    * {{{
+    * scala> import cats.data.IorNel
+    * scala> import cats.implicits._
+    *
+    * scala> "error".leftIorNel[String]
+    * res0: IorNel[String, String] = Left(NonEmptyList(error))
+    * }}}
+    */
+  def leftIorNel[B]: IorNel[A, B] = Ior.leftNel(a)
+
+  /**
+    * Wrap a value in a NonEmptyList in the right side of `Ior.Both`.
+    *
+    * Example:
+    * {{{
+    * scala> import cats.data.IorNel
+    * scala> import cats.implicits._
+    *
+    * scala> "hello".putRightIorNel[String]("error")
+    * res0: IorNel[String, String] = Both(NonEmptyList(error),hello)
+    * }}}
+    */
+  def putRightIorNel[B](left: B): IorNel[B, A] = Ior.bothNel(left, a)
+
+  /**
+    * Wrap a value in a NonEmptyList in the left side of `Ior.Both`.
+    *
+    * Example:
+    * {{{
+    * scala> import cats.data.IorNel
+    * scala> import cats.implicits._
+    *
+    * scala> "I got it wrong".putLeftIorNel[String]("hello")
+    * res0: IorNel[String, String] = Both(NonEmptyList(I got it wrong),hello)
+    * }}}
+    */
+  def putLeftIorNel[B](right: B): IorNel[A, B] = Ior.bothNel(a, right)
+}
+
+
+final class IorNelListOps[A, B](val list: List[IorNel[A, B]]) extends AnyVal {
+
+  /**
+    * Returns single combined Ior by reducing a list of IorNel
+    *
+    * Example:
+    * {{{
+    * scala> import cats.data.Ior
+    * scala> import cats.data.NonEmptyList
+    * scala> import cats.implicits._
+    *
+    * scala> List("hello".rightIorNel[String], "error".leftIorNel[String]).reduceToIor
+    * res0: Ior[NonEmptyList[String], NonEmptyList[String]] = Both(NonEmptyList(error),NonEmptyList(hello))
+    * }}}
+    */
+  def reduceToIor: Ior[NonEmptyList[A], NonEmptyList[B]] =
+    list.map(_.map(NonEmptyList(_, Nil))).reduce(_ combine _)
+
+  /**
+    * Returns an Option of a single combined Ior by reducing a list of IorNel
+    *
+    * Example:
+    * {{{
+    * scala> import cats.data.Ior
+    * scala> import cats.data.IorNel
+    * scala> import cats.data.NonEmptyList
+    * scala> import cats.implicits._
+    *
+    * scala> List("hello".rightIorNel[String], "error".leftIorNel[String]).reduceToOptionIor
+    * res0: Option[Ior[NonEmptyList[String], NonEmptyList[String]]] = Some(Both(NonEmptyList(error),NonEmptyList(hello)))
+    *
+    * scala> List.empty[IorNel[String, String]].reduceToOptionIor
+    * res1: Option[Ior[NonEmptyList[String], NonEmptyList[String]]] = None
+    * }}}
+    */
+  def reduceToOptionIor: Option[Ior[NonEmptyList[A], NonEmptyList[B]]] =
+    list.map(_.map(NonEmptyList(_, Nil))) reduceOption (_ combine _)
+}

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

@@ -1,12 +1,71 @@
 package cats
 package syntax
 
-import cats.data.NonEmptyList
+import cats.data.Validated.{Invalid, Valid}
+import cats.data.{Ior, IorNel, NonEmptyList, ValidatedNel}
 
 trait ListSyntax {
   implicit def catsSyntaxList[A](la: List[A]): ListOps[A] = new ListOps(la)
 }
 
 final class ListOps[A](val la: List[A]) extends AnyVal {
+
+  /**
+    * Returns an Option of NonEmptyList from a List
+    *
+    * Example:
+    * {{{
+    * scala> import cats.data.NonEmptyList
+    * scala> import cats.implicits._
+    *
+    * scala> val result1: List[Int] = List(1, 2)
+    * scala> result1.toNel
+    * res0: Option[NonEmptyList[Int]] = Some(NonEmptyList(1, 2))
+    *
+    * scala> val result2: List[Int] = List.empty[Int]
+    * scala> result2.toNel
+    * res1: Option[NonEmptyList[Int]] = None
+    * }}}
+    */
   def toNel: Option[NonEmptyList[A]] = NonEmptyList.fromList(la)
+
+  /**
+    * Returns a IorNel from a List
+    *
+    * Example:
+    * {{{
+    * scala> import cats.data.IorNel
+    * scala> import cats.implicits._
+    *
+    * scala> val result1: List[String] = List("error 1", "error 2")
+    * scala> result1.toIorNel(1)
+    * res0: IorNel[String, Int] = Left(NonEmptyList(error 1, error 2))
+    *
+    * scala> val result2: List[String] = List.empty[String]
+    * scala> result2.toIorNel(1)
+    * res1: IorNel[String, Int] = Right(1)
+    * }}}
+    */
+  def toIorNel[B](ifEmpty: => B): IorNel[A, B] =
+    toNel.fold[IorNel[A, B]](Ior.rightNel(ifEmpty))(Ior.left)
+
+  /**
+    * Returns a ValidatedNel from a List
+    *
+    * Example:
+    * {{{
+    * scala> import cats.data.ValidatedNel
+    * scala> import cats.implicits._
+    *
+    * scala> val result1: List[String] = List("error 1", "error 2")
+    * scala> result1.toValidatedNel(1)
+    * res0: ValidatedNel[String, Int] = Invalid(NonEmptyList(error 1, error 2))
+    *
+    * scala> val result2: List[String] = List.empty[String]
+    * scala> result2.toValidatedNel(1)
+    * res1: ValidatedNel[String, Int] = Valid(1)
+    * }}}
+    */
+  def toValidatedNel[B](ifEmpty: => B): ValidatedNel[A, B] =
+    toNel.fold[ValidatedNel[A, B]](Valid(ifEmpty))(Invalid(_))
 }

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

@@ -1,7 +1,7 @@
 package cats
 package syntax
 
-import cats.data.{Validated, ValidatedNel}
+import cats.data.{Ior, Validated, ValidatedNel}
 
 trait OptionSyntax {
   final def none[A]: Option[A] = Option.empty[A]
@@ -112,6 +112,46 @@ final class OptionOps[A](val oa: Option[A]) extends AnyVal {
    */
   def toValidNel[B](b: => B): ValidatedNel[B, A] = oa.fold[ValidatedNel[B, A]](Validated.invalidNel(b))(Validated.Valid(_))
 
+  /**
+    * If the `Option` is a `Some`, return its value in a [[cats.data.Ior.Right]].
+    * If the `Option` is `None`, wrap the provided `B` value in a [[cats.data.Ior.Left]]
+    *
+    * Example:
+    * {{{
+    * scala> import cats.data.Ior
+    * scala> import cats.implicits._
+    *
+    * scala> val result1: Option[Int] = Some(3)
+    * scala> result1.toRightIor("error!")
+    * res0: Ior[String, Int] = Right(3)
+    *
+    * scala> val result2: Option[Int] = None
+    * scala> result2.toRightIor("error!")
+    * res1: Ior[String, Int] = Left(error!)
+    * }}}
+    */
+  def toRightIor[B](b: => B): Ior[B, A] = oa.fold[Ior[B, A]](Ior.Left(b))(Ior.Right(_))
+
+  /**
+    * If the `Option` is a `Some`, return its value in a [[cats.data.Ior.Left]].
+    * If the `Option` is `None`, wrap the provided `B` value in a [[cats.data.Ior.Right]]
+    *
+    * Example:
+    * {{{
+    * scala> import cats.data.Ior
+    * scala> import cats.implicits._
+    *
+    * scala> val result1: Option[String] = Some("error!")
+    * scala> result1.toLeftIor(3)
+    * res0: Ior[String, Int] = Left(error!)
+    *
+    * scala> val result2: Option[String] = None
+    * scala> result2.toLeftIor(3)
+    * res1: Ior[String, Int] = Right(3)
+    * }}}
+    */
+  def toLeftIor[B](b: => B): Ior[A, B] = oa.fold[Ior[A, B]](Ior.Right(b))(Ior.Left(_))
+
   /**
    * If the `Option` is a `Some`, return its value. If the `Option` is `None`,
    * return the `empty` value for `Monoid[A]`.

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

@@ -22,6 +22,7 @@ package object syntax {
   object functorFilter extends FunctorFilterSyntax
   object group extends GroupSyntax
   object invariant extends InvariantSyntax
+  object ior extends IorSyntax
   object list extends ListSyntax
   object monadCombine extends MonadCombineSyntax
   object monadError extends MonadErrorSyntax