org.scalatest.matchers.AnMatcher.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.
 * AnMatcher represents a noun that appears after the word an, thus a nounName is required.
 *
 * 
 * The value to match is passed to the AnMatcher's apply method. The result is a MatchResult.
 * An AnMatcher is, therefore, a function from the specified type, T, to a MatchResult.
 * 
 *
 * 
 * Although AnMatcher
 * and Matcher represent very similar concepts, they have no inheritance relationship
 * because Matcher is intended for use right after should or must
 * whereas AnMatcher is intended for use right after an.
 * 
 *
 * 
 * As an example, you could create AnMatcher[Int]
 * called oddNumber that would match any odd Int, and one called evenNumber that would match
 * any even Int.
 * Given this pair of AnMatchers, you could check whether an Int was odd or even number with expressions like:
 * 
 *
 *  * num should be an oddNumber
 * num should not be an evenNumber
 * 
 *
 * 
 * Here's is how you might define the oddNumber and evenNumber AnMatchers:
 * 
 *
 *  * // Using AnMatcher.apply method
 * val oddNumber = AnMatcher[Int]("odd number"){ _ % 2 != 0 }
 *
 * // Or by extending AnMatcher trait
 * val evenNumber = new AnMatcher[Int] {
 *   val nounName = "even number"
 *   def apply(left: Int): MatchResult =
 *     MatchResult(
 *       left % 2 == 0,
 *       left + " was not an " + nounName,
 *       left + " was an " + nounName
 *     )
 * }
 * 
 *
 * 
 * Here's an rather contrived example of how you might use oddNumber and evenNumber:
 * 
 *
 *  *
 * val num1 = 1
 * num1 should be an oddNumber
 *
 * val num2 = num1 + 1
 * num2 should be an evenNumber
 *
 * num1 should be an evenNumber
 * 
 *
 * 
 * The last assertion in the above test will fail with this failure message:
 * 
 *
 *  * 1 was not an even number
 * 
 *
 * 
 * For more information on MatchResult and the meaning of its fields, please
 * see the documentation for MatchResult. To understand why AnMatcher
 * 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 AnMatcher's apply method.
 * @author Bill Venners
 * @author Chee Seng
 */
private[scalatest] trait AnMatcher[-T] extends Function1[T, MatchResult] {
  /**
   * The name of the noun that this AnMatcher 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 an oddNumber
   * 
   *
   * The num should be expression results in a regular ResultOfBeWordForAny that hold
   * a reference to num and has a method named an that takes a AnMatcher.  The an method
   * calls AnMatcher'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 AnMatcher that provides a
 * factory method that creates a AnMatcher[T] from a
 * passed noun name and function of type (T => MatchResult).
 *
 * @author Bill Venners
 * @author Chee Seng
 */
private[scalatest] object AnMatcher {

  /**
   * Factory method that creates a AnMatcher[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 AnMatcher 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 AnMatcher[T] {
      val nounName = name
      def apply(left: T): MatchResult = 
        MatchResult(
          fun(left), 
          Resources.rawWasNotAn,
          Resources.rawWasAn,
          Vector(left, UnquotedString(nounName))
        )
      override def toString: String = "AnMatcher[" + ev.runtimeClass.getName + "](" + Prettifier.default(name) + ", " + ev.runtimeClass.getName + " => Boolean)"
    }
  
}