org.scalautils.LegacyTripleEquals.scala Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of scalatest_2.9.1 Show documentation
ScalaTest is a free, open-source testing toolkit for Scala and Java programmers.
The newest version!
/*
 * 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.scalautils

/**
 * Provides === and !== operators that return Boolean, delegate the equality determination
 * to an Equality type class, and require no relationship between the types of the two values compared. 
 * 
 * 
 * Recommended Usage:
 * Trait LegacyTripleEquals is useful (in test, not production, code) when you need determine equality for a type of object differently than its
 * equals method: either you can't change the equals method, or the equals method is sensible generally, but
 * you are in a special situation where you need something else. If you also want a compile-time type check, however, you should use one
 * of LegacyTripleEquals sibling traits: 
 * ConversionCheckedLegacyTripleEquals or TypeCheckedLegacyTripleEquals.
 * 
 *
 * 
 * 
 * Note: This trait is extended by org.scalatest.Assertions, because it provides the same kind of === operator that was
 * historically provided by Assertions.
 * The purpose of this trait is to maintain compatibility with existing ScalaTest code that uses the original === operator. After
 * ScalaTest no longer supports Scala 2.9, the “legacy” triple equals traits will be deprecated and eventually removed. Good error messages will
 * be obtained for both == and === through assert macros. In the transition phase, you can in production code use regular triple equals traits, 
 * whose === operators return Boolean, and in test code use "legacy" triple equals traits, whose ===
 * operators return Option[String].
 * 
 * 
 *
 * 
 * This trait will override or hide implicit methods defined by its sibling traits,
 * ConversionCheckedLegacyTripleEquals or TypeCheckedLegacyTripleEquals,
 * and can therefore be used to temporarily turn of type checking in a limited scope.
 * Because the methods in LegacyTripleEquals (and its siblings)override all the methods defined in
 * supertype EqualityConstraints, you can achieve the same
 * kind of nested tuning of equality constraints whether you mix in traits, import from companion objects, or use some combination of both.
 * 
 *
 * 
 * In short, you should be able to select a primary constraint level via either a mixin or import, then change that in nested scopes
 * however you want, again either through a mixin or import, without getting any implicit conversion ambiguity. The innermost constraint level in scope
 * will always be in force.
 * 

 *
 * @author Bill Venners
 */
trait LegacyTripleEquals extends EqualityConstraints {

  implicit override def defaultEquality[A]: Equality[A] = new DefaultEquality[A]

  implicit override def unconstrainedEquality[A, B](implicit equalityOfA: Equality[A]): EqualityConstraint[A, B] = new BasicEqualityConstraint[A, B](equalityOfA)

  override def convertToEqualizer[T](left: T): Equalizer[T] = new Equalizer(left)
  override def convertToCheckingEqualizer[T](left: T): CheckingEqualizer[T] = new CheckingEqualizer(left)

  implicit override def convertToLegacyEqualizer[T](left: T): LegacyEqualizer[T] = new LegacyEqualizer(left)
  override def convertToLegacyCheckingEqualizer[T](left: T): LegacyCheckingEqualizer[T] = new LegacyCheckingEqualizer(left)

  override def lowPriorityTypeCheckedEqualityConstraint[A, B](implicit equalityOfA: Equality[A], ev: A <:< B): EqualityConstraint[A, B] = new BasicEqualityConstraint[A, B](equalityOfA)
  override def typeCheckedEqualityConstraint[A, B](implicit equalityOfA: Equality[A], ev: B <:< A): EqualityConstraint[A, B] = new BasicEqualityConstraint[A, B](equalityOfA)

  override def lowPriorityConversionCheckedEqualityConstraint[A, B](implicit equalityOfB: Equality[B], cnv: A => B): EqualityConstraint[A, B] = new AToBEqualityConstraint[A, B](equalityOfB, cnv)
  override def conversionCheckedEqualityConstraint[A, B](implicit equalityOfA: Equality[A], cnv: B => A): EqualityConstraint[A, B] = new BToAEqualityConstraint[A, B](equalityOfA, cnv)

  /**
   * Implicit conversion from Any to Equalizer, used to enable
   * assertions with === comparisons.
   *
   * 
   * For more information
   * on this mechanism, see the documentation for Equalizer.
   * 
   *
   * 
   * Because trait Suite mixes in Assertions, this implicit conversion will always be
   * available by default in ScalaTest Suites. This is the only implicit conversion that is in scope by default in every
   * ScalaTest Suite. Other implicit conversions offered by ScalaTest, such as those that support the matchers DSL
   * or invokePrivate, must be explicitly invited into your test code, either by mixing in a trait or importing the
   * members of its companion object. The reason ScalaTest requires you to invite in implicit conversions (with the exception of the
   * implicit conversion for === operator)  is because if one of ScalaTest's implicit conversions clashes with an
   * implicit conversion used in the code you are trying to test, your program won't compile. Thus there is a chance that if you
   * are ever trying to use a library or test some code that also offers an implicit conversion involving a === operator,
   * you could run into the problem of a compiler error due to an ambiguous implicit conversion. If that happens, you can turn off
   * the implicit conversion offered by this convertToEqualizer method simply by overriding the method in your
   * Suite subclass, but not marking it as implicit:
   * 
   *
   *    * // In your Suite subclass
   * override def convertToEqualizer(left: Any) = new Equalizer(left)
   * 
   * 
   * @param left the object whose type to convert to Equalizer.
   * @throws NullPointerException if left is null.
   */
  // implicit override def convertToEqualizer[T](left: T): Equalizer[T] = new Equalizer(left)
}

/**
 * Companion object to trait LegacyTripleEquals that facilitates the importing of LegacyTripleEquals members as 
 * an alternative to mixing it in. One use case is to import LegacyTripleEquals members so you can use
 * them in the Scala interpreter:
 *
 *  * $ scala -classpath scalatest.jar
 * Welcome to Scala version 2.10.0
 * Type in expressions to have them evaluated.
 * Type :help for more information.
 *
 * scala> import org.scalautils._
 * import org.scalautils._
 *
 * scala> import LegacyTripleEquals._
 * import LegacyTripleEquals._
 *
 * scala> 1 + 1 === 2
 * res0: Option[String] = None
 * 
 */
object LegacyTripleEquals extends LegacyTripleEquals