org.scalatest.matchers.AMatcher.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.matchers
import org.scalatest._
import org.scalactic.Prettifier
import scala.reflect.ClassTag
/**
* Trait extended by matcher objects that can match a value of the specified type.
* AMatcher represents a noun that appears after the word a, thus a nounName is required.
*
*
* The value to match is passed to the AMatcher's apply method. The result is a MatchResult.
* An AMatcher is, therefore, a function from the specified type, T, to a MatchResult.
*
*
*
* Although AMatcher
* and Matcher represent very similar concepts, they have no inheritance relationship
* because Matcher is intended for use right after should or must
* whereas AMatcher is intended for use right after a.
*
*
*
* As an example, you could create AMatcher[Int]
* called positiveNumber that would match any positive Int, and one called negativeNumber that would match
* any negative Int.
* Given this pair of AMatchers, you could check whether an Int was positive or negative with expressions like:
*
*
*
* num should be a positiveNumber
* num should not be a negativeNumber
*
*
*
* Here's is how you might define the positiveNumber and negativeNumber AMatchers:
*
*
*
* // Using AMatcher.apply method
* val positiveNumber = AMatcher[Int]("positive number"){ _ > 0 }
*
* // Or by extending AMatcher trait
* val negativeNumber = new AMatcher[Int] {
* val nounName = "negative number"
* def apply(left: Int): MatchResult =
* MatchResult(
* left < 0,
* left + " was not a " + nounName,
* left + " was a " + nounName
* )
* }
*
*
*
* Here's an rather contrived example of how you might use positiveNumber and negativeNumber:
*
*
*
*
* val num1 = 1
* num1 should be a positiveNumber
*
* val num2 = num1 * -1
* num2 should be a negativeNumber
*
* num1 should be a negativeNumber
*
*
*
* The last assertion in the above test will fail with this failure message:
*
*
*
* 1 was not a negative number
*
*
*
* For more information on MatchResult and the meaning of its fields, please
* see the documentation for MatchResult. To understand why AMatcher
* is contravariant in its type parameter, see the section entitled "Matcher's variance" in the
* documentation for Matcher.
*
*
* @tparam T The type used by this AMatcher's apply method.
* @author Bill Venners
* @author Chee Seng
*/
private[scalatest] trait AMatcher[-T] extends Function1[T, MatchResult] {
/**
* The name of the noun that this AMatcher represents.
*/
val nounName: String
/**
* Check to see if the specified object, left, matches, and report the result in
* the returned MatchResult. The parameter is named left, because it is
* usually the value to the left of a should or must invocation. For example,
* in:
*
*
* num should be a positiveNumber
*
*
* The num should be expression results in a regular ResultOfBeWordForAny that hold
* a reference to num and has a method named a that takes a AMatcher. The a method
* calls AMatcher's apply method by passing in the num, and check if num matches.
*
* @param left the value against which to match
* @return the MatchResult that represents the result of the match
*/
def apply(left: T): MatchResult
}
/**
* Companion object for trait AMatcher that provides a
* factory method that creates a AMatcher[T] from a
* passed noun name and function of type (T => MatchResult).
*
* @author Bill Venners
* @author Chee Seng
*/
private[scalatest] object AMatcher {
/**
* Factory method that creates a AMatcher[T] from a
* passed noun name and function of type (T => MatchResult).
*
* @param name the noun name
* @param fun the function of type (T => MatchResult)
* @return AMatcher instance that has the passed noun name and matches using the passed function
* @author Bill Venners
* @author Chee Seng
*/
def apply[T](name: String)(fun: T => Boolean)(implicit ev: ClassTag[T]) =
new AMatcher[T] {
val nounName = name
def apply(left: T): MatchResult =
MatchResult(
fun(left),
Resources.rawWasNotA,
Resources.rawWasA,
Vector(left, UnquotedString(nounName))
)
override def toString: String = "AMatcher[" + ev.runtimeClass.getName + "](" + Prettifier.default(name) + ", " + ev.runtimeClass.getName + " => Boolean)"
}
}