org.scalatest.OptionValues.scala Maven / Gradle / Ivy

/*
 * Copyright 2001-2013 Artima, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.scalatest

import org.scalactic._
import java.util.NoSuchElementException
import org.scalatest.exceptions.StackDepthException
import org.scalatest.exceptions.TestFailedException

/**
 * Trait that provides an implicit conversion that adds a value method
 * to Option, which will return the value of the option if it is defined,
 * or throw TestFailedException if not.
 *
 * 
 * This construct allows you to express in one statement that an option should be defined
 * and that its value should meet some expectation. Here's an example:
 * 
 *
 *  * opt.value should be > 9
 * 
 *
 * 
 * Or, using an assertion instead of a matcher expression:
 * 
 *
 *  * assert(opt.value > 9)
 * 
 *
 * 
 * Were you to simply invoke get on the Option, 
 * if the option wasn't defined, it would throw a NoSuchElementException:
 * 
 *
 *  * val opt: Option[Int] = None
 *
 * opt.get should be > 9 // opt.get throws NoSuchElementException
 * 
 *
 * 
 * The NoSuchElementException would cause the test to fail, but without providing a stack depth pointing
 * to the failing line of test code. This stack depth, provided by TestFailedException (and a
 * few other ScalaTest exceptions), makes it quicker for
 * users to navigate to the cause of the failure. Without OptionValues, to get
 * a stack depth exception you would need to make two statements, like this:
 * 
 *
 *  * val opt: Option[Int] = None
 *
 * opt should be ('defined) // throws TestFailedException
 * opt.get should be > 9
 * 
 *
 * 
 * The OptionValues trait allows you to state that more concisely:
 * 
 *
 *  * val opt: Option[Int] = None
 *
 * opt.value should be > 9 // opt.value throws TestFailedException
 * 
 */
trait OptionValues {

  import scala.language.implicitConversions

  /**
   * Implicit conversion that adds a value method to Option.
   *
   * @param opt the Option on which to add the value method
   */
  implicit def convertOptionToValuable[T](opt: Option[T])(implicit pos: source.Position): Valuable[T] = new Valuable(opt, pos)

  /**
   * Wrapper class that adds a value method to Option, allowing
   * you to make statements like:
   *
   *    * opt.value should be > 9
   * 
   *
   * @param opt An option to convert to Valuable, which provides the value method.
   */
  class Valuable[T](opt: Option[T], pos: source.Position) {

    /**
     * Returns the value contained in the wrapped Option, if defined, else throws TestFailedException with
     * a detail message indicating the option was not defined.
     */
    def value: T = {
      try {
        opt.get
      }
      catch {
        case cause: NoSuchElementException => 
          throw new TestFailedException((_: StackDepthException) => Some(Resources.optionValueNotDefined), Some(cause), pos)
      }
    }
  }
}

/**
 * Companion object that facilitates the importing of OptionValues members as 
 * an alternative to mixing it in. One use case is to import OptionValues's members so you can use
 * value on option in the Scala interpreter:
 *
 *  * $ scala -cp scalatest-1.7.jar
 * Welcome to Scala version 2.9.1.final (Java HotSpot(TM) 64-Bit Server VM, Java 1.6.0_29).
 * Type in expressions to have them evaluated.
 * Type :help for more information.
 *
 * scala> import org.scalatest._
 * import org.scalatest._
 *
 * scala> import matchers.Matchers._
 * import matchers.Matchers._
 *
 * scala> import OptionValues._
 * import OptionValues._
 *
 * scala> val opt1: Option[Int] = Some(1)
 * opt1: Option[Int] = Some(1)
 * 
 * scala> val opt2: Option[Int] = None
 * opt2: Option[Int] = None
 * 
 * scala> opt1.value should be < 10
 * 
 * scala> opt2.value should be < 10
 * org.scalatest.TestFailedException: The Option on which value was invoked was not defined.
 *   at org.scalatest.OptionValues$Valuable.value(OptionValues.scala:68)
 *   at .<init>(<console>:18)
 *   ...
 * 
 *
 */
object OptionValues extends OptionValues