Or

Represents a value that is one of two possible types, with one type being “good” and the other “bad.”

An Or will either be a “good” value wrapped in an instance of Good or a “bad” value wrapped in an instance of Bad.

The motivation for Or

Or differs from Scala's Either type in that Either treats both its Left and Right alternatives in an identical manner, whereas Or treats its two alternatives differently: it favors Good over Bad. Because of this, it is more convenient to work with Ors when you prefer one alternative over the other; for example, if one alternative represents a valid result and another represents an error.

To illustrate, imagine you want to create instances this Person class from user input strings:

case class Person(name: String, age: Int)

You might write a method that parses the name from user input string and returns an Option[String]: None if the string is empty or blank, else the trimmed string wrapped in a Some:

def parseName(input: String): Option[String] = {
  val trimmed = input.trim
  if (!trimmed.isEmpty) Some(trimmed) else None
}

You might also write a method that parses the age from user input string and returns an Option[Int]: None if either the string is not a valid integer or it is a negative integer, else the string converted to an integer wrapped in a Some:

def parseAge(input: String): Option[Int] = {
  try {
    val age = input.trim.toInt
    if (age >= 0) Some(age) else None
  }
  catch {
    case _: NumberFormatException => None
  }
}

With these building blocks you could write a method that parses name and age input strings and returns either a Person, wrapped in a Some, or None if either the name or age, or both, was invalid:

def parsePerson(inputName: String, inputAge: String): Option[Person] =
  for {
    name <- parseName(inputName)
    age <- parseAge(inputAge)
  } yield Person(name, age)

Here are some examples of invoking parsePerson:

parsePerson("Bridget Jones", "29")
// Result: Some(Person(Bridget Jones,29))

parsePerson("Bridget Jones", "")
// Result: None

parsePerson("Bridget Jones", "-29")
// Result: None

parsePerson("", "")
// Result: None

Now imagine you want to give an error message back if the user's input is invalid. You might rewrite the parsing methods to return an Either instead. In this case, the desired result is a valid name or age, which by convention should be placed on the right of the Either. The left will be a String error message. Here's the new parseName function, which returns an Either[String, String]:

def parseName(input: String): Either[String, String] = {
  val trimmed = input.trim
  if (!trimmed.isEmpty) Right(trimmed) else Left(s""""${input}" is not a valid name""")
}

And here's the new parseAge function, which returns an Either[String, Int]:

def parseAge(input: String): Either[String, Int] = {
  try {
    val age = input.trim.toInt
    if (age >= 0) Right(age) else Left(s""""${age}" is not a valid age""")
  }
  catch {
    case _: NumberFormatException => Left(s""""${input}" is not a valid integer""")
  }
}

The new parsePerson method will return an Either[String, Person]:

def parsePerson(inputName: String, inputAge: String): Either[String, Person] =
  for {
    name <- parseName(inputName).right
    age <- parseAge(inputAge).right
  } yield Person(name, age)

Note that Either requires you to add .right at the end of each generator in the for expression. Although the convention is to place the valid result on the right, you must explicitly (and repetitively) indicate that you've done so by transforming the Either to a RightProjection by invoking .right at each step. Given this implementation, the parsePerson method will now short-circuit at the first sign of trouble (as it did when we used an Option), but you now get the first error message returned in a Left. Here are some examples:

parsePerson("Bridget Jones", "29")
// Result: Right(Person(Bridget Jones,29))

parsePerson("Bridget Jones", "")
// Result: Left("" is not a valid integer)

parsePerson("Bridget Jones", "-29")
// Result: Left("-29" is not a valid age)

parsePerson("", "")
// Result: Left("" is not a valid name)

An Either with “attitude”

Because Or declares one alternative to be “good” and the other “bad,” it is more convenient than Either in this kind of situation. One difference to note with Or is that the Good alternative is on the left, Bad on the right. The reason is that Or is designed to be written using infix notation, and placing the “happy path” first is more readable. For example, instead of writing:

Or[Int, ErrorMessage]

You can write:

Int Or ErrorMessage

Here's how the parseName method might be written using an Or, where ErrorMessage is a type alias for String declared in the org.scalautils package object:

import org.scalautils._

def parseName(input: String): String Or ErrorMessage = {
  val trimmed = input.trim
  if (!trimmed.isEmpty) Good(trimmed) else Bad(s""""${input}" is not a valid name""")
}

You can think of the String Or ErrorMessage result type like this:

The parseName method will return a name String or, if the input string is not a valid name, an ErrorMessage.

Here's how the parseAge method might be written:

def parseAge(input: String): Int Or ErrorMessage = {
  try {
    val age = input.trim.toInt
    if (age >= 0) Good(age) else Bad(s""""${age}" is not a valid age""")
  }
  catch {
    case _: NumberFormatException => Bad(s""""${input}" is not a valid integer""")
  }
}

Given these implementations, here's how you'd write the parsePerson method:

def parsePerson(inputName: String, inputAge: String): Person Or ErrorMessage =
  for {
    name <- parseName(inputName)
    age <- parseAge(inputAge)
  } yield Person(name, age)

Because of Or's attitude, you need not write .good at the end of each generator. Or will keep going so long as each step produces a Good, short circuiting at the first sign of a Bad. Here are a few invocations of this parsePerson method:

parsePerson("Bridget Jones", "29")
// Result: Good(Person(Bridget Jones,29))

parsePerson("Bridget Jones", "")
// Result: Bad("" is not a valid integer)

parsePerson("Bridget Jones", "-29")
// Result: Bad("-29" is not a valid age)

parsePerson("", "")
// Result: Bad("" is not a valid name)

Accumulating errors with Or

Another difference between Or and Either is that Or enables you to accumulate errors if the Bad type is an Every. An Every is similar to a Seq in that it contains ordered elements, but different from Seq in that it cannot be empty. An Every is either a One, which contains one and only one element, or a Many, which contains two or more elements.

Note: an Or whose Bad type is an Every, or one of its subtypes, is called an “accumulating Or.”

To rewrite the previous example so that errors can be accumulated, you need first to return an Every as the Bad type. Here's how you'd change the parseName method:

def parseName(input: String): String Or One[ErrorMessage] = {
  val trimmed = input.trim
  if (!trimmed.isEmpty) Good(trimmed) else Bad(One(s""""${input}" is not a valid name"""))
}

Because parseName will either return a valid name String wrapped in a Good, or one error message, wrapped in a Bad, you would write the Bad type as One[ErrorMessage]. The same is true for parseAge:

def parseAge(input: String): Int Or One[ErrorMessage] = {
  try {
    val age = input.trim.toInt
    if (age >= 0) Good(age) else Bad(One(s""""${age}" is not a valid age"""))
  }
  catch {
    case _: NumberFormatException => Bad(One(s""""${input}" is not a valid integer"""))
  }
}

Because a for expression short-circuits on the first Bad encountered, you'll need to use a different approach to write the parsePerson method. In this example, the withGood method from trait Accumulation will do the trick:

import Accumulation._

def parsePerson(inputName: String, inputAge: String): Person Or Every[ErrorMessage] = {
  val name = parseName(inputName)
  val age = parseAge(inputAge)
  withGood(name, age) { Person(_, _) }
}

Trait Accumulation offers overloaded withGood methods that take 1 to 22 accumulating Ors, plus a function taking the same number of corresponding Good values. In this example, if both name and age are Goods, the withGood method will pass the good name String and age Int to the Person(_, _) function, and return the resulting Person object wrapped in a Good. If either name and age, or both, are Bad, withGood will return the accumulated errors in a Bad.

The result of parsePerson, if Bad, will therefore contain either one or two error messages, i.e., the result will either be a One or a Many. As a result, the result type of parsePerson must be Person Or Every[ErrorMessage]. Regardless of whether a Bad result contains one or two error messages, it will contain every error message. Here's some invocations of this accumulating version of parsePerson:

parsePerson("Bridget Jones", "29")
// Result: Good(Person(Bridget Jones,29))

parsePerson("Bridget Jones", "")
// Result: Bad(One("" is not a valid integer))

parsePerson("Bridget Jones", "-29")
// Result: Bad(One("-29" is not a valid age))

parsePerson("", "")
// Result: Bad(Many("" is not a valid name, "" is not a valid integer))

Note that in the last example, the Bad contains an error message for both name and age.

Other ways to accumulate errors

The Accumlation trait also enables other ways of accumulating errors.

Using combined

If you have a collection of accumulating Ors, for example, you can combine them into one Or using combined, like this:

List(parseAge("29"), parseAge("30"), parseAge("31")).combined
// Result: Good(List(29, 30, 31))

List(parseAge("29"), parseAge("-30"), parseAge("31")).combined
// Result: Bad(One("-30" is not a valid age))

List(parseAge("29"), parseAge("-30"), parseAge("-31")).combined
// Result: Bad(Many("-30" is not a valid age, "-31" is not a valid age))

Using validatedBy

Or if you have a collection of values and a function that transforms that type of value into an accumulating Ors, you can validate the values using the function using validatedBy, like this:

List("29", "30", "31").validatedBy(parseAge)
// Result: Good(List(29, 30, 31))

List("29", "-30", "31").validatedBy(parseAge)
// Result: Bad(One("-30" is not a valid age))

List("29", "-30", "-31").validatedBy(parseAge)
// Result: Bad(Many("-30" is not a valid age, "-31" is not a valid age))

Using zip

You can also zip two accumulating Ors together. If both are Good, you'll get a Good tuple containin both original Good values. Otherwise, you'll get a Bad containing every error message. Here are some examples:

parseName("Dude") zip parseAge("21")
// Result: Good((Dude,21))

parseName("Dude") zip parseAge("-21")
// Result: Bad(One("-21" is not a valid age))

parseName("") zip parseAge("-21")
// Result: Bad(Many("" is not a valid name, "-21" is not a valid age))

Using when

In addition, given an accumlating Or, you can pass one or more validation functions to when on the Or to submit that Or to further scrutiny. A validation function accepts a Good type and returns a Validation[E], where E is the type in the Every in the Bad type. For an Int Or One[ErrorMessage], for example the validation function type would be Int => Validation[ErrorMessage]. Here are a few examples:

def isRound(i: Int): Validation[ErrorMessage] =
  if (i % 10 == 0) Pass else Fail(i + " was not a round number")

def isDivBy3(i: Int): Validation[ErrorMessage] =
  if (i % 3 == 0) Pass else Fail(i + " was not divisible by 3")

If the Or on which you call when is already Bad, you get the same (Bad) Or back, because no Good value exists to pass to the valiation functions:

parseAge("-30").when(isRound, isDivBy3)
// Result: Bad(One("-30" is not a valid age))

If the Or on which you call when is Good, and also passes all the validation functions (i.e., the all return None), you again get the same Or back, but this time, a Good one:

parseAge("30").when(isRound, isDivBy3)
// Result: Good(30)

If one or more of the validation functions fails, however, you'll get a Bad back contining every error. Here are some examples:

parseAge("33").when(isRound, isDivBy3)
// Result: Bad(One(33 was not a round number))

parseAge("20").when(isRound, isDivBy3)
// Result: Bad(One(20 was not divisible by 3))

parseAge("31").when(isRound, isDivBy3)
// Result: Bad(Many(31 was not a round number, 31 was not divisible by 3))

Note that you can use when to accumulate errors in a for expression involving an accumulating Or, like this:

for (age <- parseAge("-30") when (isRound, isDivBy3)) yield age
// Result: Bad(One("-30" is not a valid age))

for (age <- parseAge("30") when (isRound, isDivBy3)) yield age
// Result: Good(30)

for (age <- parseAge("33") when (isRound, isDivBy3)) yield age
// Result: Bad(One(33 was not a round number))

for (age <- parseAge("20") when (isRound, isDivBy3)) yield age
// Result: Bad(One(20 was not divisible by 3))

for (age <- parseAge("31") when (isRound, isDivBy3)) yield age
// Result: Bad(Many(31 was not a round number, 31 was not divisible by 3))

Much ado about Nothing

Because Or has two types, but each of its two subtypes only takes a value of one or the other type, the Scala compiler will infer Nothing for the unspecified type:

scala> Good(3)
res0: org.scalautils.Good[Int,Nothing] = Good(3)
scala> Bad("oops")
res1: org.scalautils.Bad[Nothing,String] = Bad(oops)

Often Nothing will work fine, as it will be widened as soon as the compiler encounters a more specific type. Sometimes, however, you may need to specify it. In such situations you can use this syntax:

scala> Good(3).orBad[String]
res2: org.scalautils.Good[Int,String] = Good(3)
scala> Good[Int].orBad("oops")
res3: org.scalautils.Bad[Int,String] = Bad(oops)

If you want to specify both types, because you don't like the inferred type, you can do so like this:

scala> Good[AnyVal, String](3)
res4: org.scalautils.Good[AnyVal,String] = Good(3)
scala> Bad[Int, ErrorMessage]("oops")
res5: org.scalautils.Bad[Int,org.scalautils.ErrorMessage] = Bad(oops)

But you may find the code is clearer if you instead use a type ascription, like this:

scala> Good(3): AnyVal Or String
res6: org.scalautils.Or[AnyVal,String] = Good(3)
scala> Bad("oops"): Int Or ErrorMessage
res7: org.scalautils.Or[Int,org.scalautils.ErrorMessage] = Bad(oops)

Note: The Or hierarchy was inspired in part by the disjoint union (\/) and Validation types of scalaz, the ProcessResult type of Typesafe Activator, and the Result type of ScalaKittens.