org.scalatest.PartialFunctionValues.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 org.scalatest.exceptions.StackDepthException
import org.scalatest.exceptions.TestFailedException
/**
* Trait that provides an implicit conversion that adds a valueAt method
* to PartialFunction, which will return the value (result) of the function applied to the argument passed to valueAt,
* or throw TestFailedException if the partial function is not defined at the argument.
*
*
* This construct allows you to express in one statement that a partial function should be defined for a particular input,
* and that its result value should meet some expectation. Here's an example:
*
*
*
* pf.valueAt("IV") should equal (4)
*
*
*
* Or, using an assertion instead of a matcher expression:
*
*
*
* assert(pf.valueAt("IV") === 4)
*
*
*
* Were you to simply invoke apply on the PartialFunction, passing in an input value,
* if the partial function wasn't defined at that input, it would throw some exception, but likely not one
* that provides a stack depth:
*
*
*
* // Note: a Map[K, V] is a PartialFunction[K, V]
* val pf: PartialFunction[String, Int] = Map("I" -> 1, "II" -> 2, "III" -> 3, "IV" -> 4)
*
* pf("V") should equal (5) // pf("V") throws NoSuchElementException
*
*
*
* The NoSuchElementException thrown in this situation 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 PartialFunctionValues, to get
* a stack depth exception you would need to make two statements, like this:
*
*
*
* val pf: PartialFunction[String, Int] = Map("I" -> 1, "II" -> 2, "III" -> 3, "IV" -> 4)
*
* pf.isDefinedAt("V") should be (true) // throws TestFailedException
* pf("V") should equal (5)
*
*
*
* The PartialFunctionValues trait allows you to state that more concisely:
*
*
*
* val pf: PartialFunction[String, Int] = Map("I" -> 1, "II" -> 2, "III" -> 3, "IV" -> 4)
*
* pf.valueAt("V") should equal (5) // pf.valueAt("V") throws TestFailedException
*
*/
trait PartialFunctionValues {
import scala.language.implicitConversions
/**
* Implicit conversion that adds a valueAt method to PartialFunction.
*
* @param pf the PartialFunction on which to add the valueAt method
*/
implicit def convertPartialFunctionToValuable[A, B](pf: PartialFunction[A, B])(implicit pos: source.Position): Valuable[A, B] = new Valuable(pf, pos)
/**
* Wrapper class that adds a valueAt method to PartialFunction, allowing
* you to make statements like:
*
*
* pf.valueAt("VI") should equal (6)
*
*
* @param pf An PartialFunction to convert to Valuable, which provides the valueAt method.
*/
class Valuable[A, B](pf: PartialFunction[A, B], pos: source.Position) {
/**
* Returns the result of applying the wrapped PartialFunction to the passed input, if it is defined at that input, else
* throws TestFailedException with a detail message indicating the PartialFunction was not defined at the given input.
*/
def valueAt(input: A): B = {
if (pf.isDefinedAt(input)) {
pf.apply(input)
}
else
throw new TestFailedException((_: StackDepthException) => Some(Resources.partialFunctionValueNotDefined(input.toString)), None, pos)
}
}
}
/**
* Companion object that facilitates the importing of PartialFunctionValues members as
* an alternative to mixing it in. One use case is to import PartialFunctionValues's members so you can use
* the valueAt method on PartialFunction 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 PartialFunctionValues._
* import PartialFunctionValues._
*
* scala> val pf: PartialFunction[String, Int] = Map("I" -> 1, "II" -> 2, "III" -> 3, "IV" -> 4)
* pf: PartialFunction[String,Int] = Map(I -> 1, II -> 2, III -> 3, IV -> 4)
*
* scala> pf("IV") should equal (4)
*
* scala> pf("V") should equal (5)
* java.util.NoSuchElementException: key not found: V
* at scala.collection.MapLike$class.default(MapLike.scala:224)
* at scala.collection.immutable.Map$Map4.default(Map.scala:167)
* ...
*
*/
object PartialFunctionValues extends PartialFunctionValues