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

Go to download
Show more of this group Show more artifacts with this name
Show all versions of scalatest_2.11.0-M5 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

/**
 * Defines a custom way to normalize instances of a type that can also handle normalization of that type when passed as Any.
 *
 * 
 * 
 * 
 * @tparam A the type whose uniformity is being defined
 */
trait Uniformity[A] extends Normalization[A] { thisUniformity =>

  // TODO: Add an example of Array[String] isInstanceOfA here and in NormalizedEquality
  /* TODO: Need to fix this scaladoc!
   * Indicates whether the passed object is an instance of type A.
   *
   * 
   * This method is invoked by the areEqual method of subclass NormalizedEquality to determine whether or not
   * b can be cast to A so that it can be safely passed to normalized.
   * To implement this method, simply call b.isInstanceOf[A] for the actual A type.
   * For example, if you are defining a NormalizedEquality[String], your isInstanceOf
   * method should look like:
   * 
   *
   *    * def isInstanceOfA(b: Any) = b.isInstanceOf[String]
   * 
   *
   * 
   * If you are defining a NormalizedEquality[xml.Node] your isInstanceOf method
   * should look like:
   * 
   *
   *    * def isInstanceOfA(b: Any) = b.isInstanceOf[xml.Node]
   * 
   *
   * @param b the object to inspect to determine whether it is an instance of A
   * @return true if the passed object is an instance of A
   */

  /**
   * Returns either the result of passing this object to normalized, if appropriate, or the same object.
   */
  def normalizedOrSame(b: Any): Any

  /**
   * Indicates whether this Uniformity's normalized method can handle the passed object, if cast to the appropriate type.
   *
   * 
   * If this method returns true for a particular passed object, it means that if the object is passed
   * to normalizedOrSame, that method will return the result of passing it to normalized.
   * It does not mean that the object will necessarily be modified when passed to normalizedOrSame or normalized.
   * For example, the lowerCased field of StringNormalizations is a Uniformity[String]
   * that normalizes strings by forcing all characters to lower case:
   * 
   *
   *    * scala> import org.scalautils._
   * import org.scalautils._
   *
   * scala> import StringNormalizations._
   * import StringNormalizations._
   *
   * scala> lowerCased
   * res0: org.scalautils.Uniformity[String] = org.scalautils.StringNormalizations$$anon$1@236db810
   *
   * scala> lowerCased.normalized("HALLOOO!")
   * res1: String = hallooo!
   * 
   *
   * 
   * Now consider two strings held from variables of type AnyRef:
   * 
   *
   *    * scala> val yell: AnyRef = "HOWDY"
   * yell: AnyRef = HOWDY
   *
   * scala> val whisper: AnyRef = "howdy"
   * whisper: AnyRef = howdy
   * 
   *
   * 
   * As you would expect, when yell is passed to normalizedCanHandle, it returns true, and when
   * yell is passed to normalizedOrSame, it returns a lower-cased (normal) form:
   * 
   *
   *    * scala> lowerCased.normalizedCanHandle(yell)
   * res2: Boolean = true
   *
   * scala> lowerCased.normalizedOrSame(yell)
   * res3: Any = howdy
   * 
   *
   * 
   * A similar thing happens, however, when whisper is passed to normalizedCanHandle and normalizedOrSame,
   * even though in this case the string is already in normal form according to the lowerCased Uniformity:
   * 
   *
   *    * scala> lowerCased.normalizedCanHandle(whisper)
   * res4: Boolean = true
   *
   * scala> lowerCased.normalizedOrSame(whisper)
   * res5: Any = howdy
   * 
   *
   * 
   * This illustrates that normalizedCanHandle does not indicate that the passed object is not in normalized form already, just that
   * it can be be handled by the normalized method. This further means that the normalized method itself
   * simply ensures that objects are returned in normal form. It need not necessarily change them: if a passed object is already in
   * normal form, normalized can (and usually should) return the exact same object. That is in fact what happened when we normalized
   * whisper. Since whisper's value of "hello" was already in normal form (all lower-cased), normalized (
   * invoked by the normalizedOrSame method) returned the exact same object passed:
   * 
   *
   *    * scala> val whisperNormed = res5.asInstanceOf[AnyRef]
   * whisperNormed: AnyRef = howdy
   *
   * scala> whisperNormed eq whisper
   * res8: Boolean = true
   * 
   */
  def normalizedCanHandle(b: Any): Boolean

  /**
   * Returns a new Uniformity that combines this and the passed Uniformity.
   *
   * 
   * The normalized, normalizeCanHandle, and normalizedOrSame methods
   * of the Uniformity's returned by this method return a result 
   * obtained by passing it first to this Normalization's implementation of the method,
   * then passing that result to the other Normalization's normalized the method, respectively.
   * Essentially, the body of the composed normalized method is:
   * 
   *
   *    * uniformityPassedToAnd.normalized(uniformityOnWhichAndWasInvoked.normalized(a))
   * 
   *
   * 
   * The body of the composed normalizeCanHandle method is:
   * 
   *
   *    * uniformityPassedToAnd.normalizeCanHandle(uniformityOnWhichAndWasInvoked.normalizeCanHandle(a))
   * 
   *
   * 
   * And the body of the composed normalizedOrSame method is:
   * 
   *
   *    * uniformityPassedToAnd.normalizedOrSame(uniformityOnWhichAndWasInvoked.normalizedOrSame(a))
   * 
   *
   * 
   * If the passed object is already in normal form, this method may return the same instance passed.
   * 
   *
   * @param other a Uniformity to 'and' with this one
   * @return a Uniformity representing the composition of this and the passed Uniformity
   */
  final def and(other: Uniformity[A]): Uniformity[A] =
    new Uniformity[A] {
      // Note in Scaladoc what order, and recommend people don't do side effects anyway.
      // By order, I mean left's normalized gets called first then right's normalized gets called on that result, for "left and right"
      def normalized(a: A): A = other.normalized(thisUniformity.normalized(a))
      def normalizedCanHandle(b: Any): Boolean = other.normalizedCanHandle(b) || thisUniformity.normalizedCanHandle(b)
      def normalizedOrSame(b: Any): Any = other.normalizedOrSame(thisUniformity.normalizedOrSame(b))
    }
}