Extend matchers and add Scaladocs (#1)

Author: stringbean

.scalafmt.conf

@@ -2,4 +2,9 @@ style = default
 maxColumn = 120
 
 align.openParenCallSite = false
-align.openParenDefnSite = false
+align.openParenDefnSite = false
+
+# don't align arrows in match statements
+align.tokens = []
+
+docstrings = JavaDoc

.travis.yml

@@ -4,6 +4,7 @@ sudo: false
 scala:
   - 2.11.11
   - 2.12.7
+  - 2.13.0-M5
 jdk:
   - oraclejdk8
 

build.sbt

@@ -2,7 +2,7 @@ import PgpKeys.{publishLocalSigned, publishSigned}
 import com.typesafe.sbt.SbtGit.GitKeys._
 
 organization := "software.purpledragon.xml"
-version := "0.0.3"
+version := "0.0.4-SNAPSHOT"
 
 scalaVersion := "2.12.7"
 crossScalaVersions := Seq(scalaVersion.value, "2.11.12", "2.13.0-M5")
@@ -58,6 +58,9 @@ lazy val root = project
     git.remoteRepo := "git@github.com:stringbean/scala-xml-compare.git",
     paradoxProperties in Paradox ++= Map(
       "scaladoc.software.purpledragon.xml.base_url" -> ".../api"
+    ),
+    scalacOptions in Compile in doc ++= Seq(
+      "-doc-root-content", baseDirectory.value + "/root-scaladoc.txt"
     )
   )
-  .enablePlugins(ScalaUnidocPlugin, GhpagesPlugin, ParadoxSitePlugin)
+  .enablePlugins(ScalaUnidocPlugin, GhpagesPlugin, ParadoxSitePlugin)

project/SettingsPlugin.scala

@@ -1,5 +1,4 @@
 import com.lucidchart.sbt.scalafmt.ScalafmtCorePlugin.autoImport._
-import de.heikoseeberger.sbtheader.HeaderPlugin.autoImport._
 import sbt.Keys._
 import sbt._
 import sbt.plugins.JvmPlugin
@@ -33,12 +32,12 @@ object SettingsPlugin extends AutoPlugin {
     libraryDependencies ++= (libraryDependencies in LocalRootProject).value,
     scalafmtVersion := "1.5.1",
     autoAPIMappings := true,
-    headerLicense := Some(HeaderLicense.ALv2("2017", "Michael Stringer")),
+    startYear := Some(2017),
     licenses += ("Apache-2.0", url("https://opensource.org/licenses/Apache-2.0")),
     developers := List(
       Developer("stringbean", "Michael Stringer", "@the_stringbean", url("https://github.com/stringbean"))
     ),
-    organizationName := "Purple Dragon Software",
+    organizationName := "Michael Stringer",
     organizationHomepage := Some(url("https://purpledragon.software")),
     homepage := Some(url("https://stringbean.github.io/scala-xml-compare")),
     scmInfo := Some(ScmInfo(url("https://github.com/stringbean/scala-xml-compare"), "https://github.com/stringbean/scala-xml-compare.git")),

project/plugins.sbt

@@ -1,6 +1,6 @@
 // code style
 addSbtPlugin("org.scalastyle" %% "scalastyle-sbt-plugin" % "1.0.0")
-addSbtPlugin("org.scoverage" % "sbt-scoverage" % "1.5.1")
+addSbtPlugin("org.scoverage" % "sbt-scoverage" % "1.6.0-M5")
 addSbtPlugin("com.lucidchart" % "sbt-scalafmt" % "1.15")
 addSbtPlugin("de.heikoseeberger" % "sbt-header" % "5.0.0")
 
@@ -12,4 +12,4 @@ addSbtPlugin("com.jsuereth" % "sbt-pgp" % "1.1.2-1")
 addSbtPlugin("com.eed3si9n" % "sbt-unidoc" % "0.4.2")
 addSbtPlugin("com.typesafe.sbt" % "sbt-ghpages" % "0.6.2")
 addSbtPlugin("com.typesafe.sbt" % "sbt-site" % "1.3.2")
-addSbtPlugin("com.lightbend.paradox" % "sbt-paradox" % "0.3.3")
+addSbtPlugin("com.lightbend.paradox" % "sbt-paradox" % "0.3.3")

root-scaladoc.txt

@@ -0,0 +1,8 @@
+This is the documentation for the [[https://stringbean.github.io/scala-xml-compare scala-xml-compare]] project.
+
+The main [[software.purpledragon.xml.compare compare]] package contains utilities for comparing XML documents and
+generating diffs.
+
+The following test frameworks are supported:
+  - Scalatest in [[software.purpledragon.xml.scalatest `xml-scalatest`]]
+  - specs2 in [[software.purpledragon.xml.specs2 `xml-specs2`]]

xml-compare/src/main/scala/software/purpledragon/xml/compare/XmlCompare.scala

@@ -1,16 +1,54 @@
+/*
+ * Copyright 2017 Michael Stringer
+ *
+ * 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 software.purpledragon.xml.compare
 
 import software.purpledragon.xml.compare.options.DiffOption._
 import software.purpledragon.xml.compare.options.DiffOptions
 
 import scala.xml.{Node, Text}
 
+/**
+ * Utility for comparing XML documents.
+ */
 object XmlCompare {
-  private type Check = (Node, Node, DiffOptions) => XmlDiff
+  private type Check = (Node, Node, DiffOptions, Seq[String]) => XmlDiff
 
-  val DefaultOptions: DiffOptions = Set(IgnorePrefix)
+  /**
+   * Default [[software.purpledragon.xml.compare.options.DiffOption.DiffOption DiffOption]]s to use during XML comparison.
+   *
+   * Currently these are:
+   *  - [[software.purpledragon.xml.compare.options.DiffOption.IgnoreNamespacePrefix IgnoreNamespacePrefix]]
+   */
+  val DefaultOptions: DiffOptions = Set(IgnoreNamespacePrefix)
 
+  /**
+   * Compares two XML documents. This will perform a recursive scan of all the nodes in each document, checking each
+   * for node name, namespace and text.
+   *
+   * @param left the first XML document to compare.
+   * @param right the second XML document to compare.
+   * @param options configuration options to control the way the comparison is performed.
+   * @return results of the XML comparison.
+   */
   def compare(left: Node, right: Node, options: DiffOptions = DefaultOptions): XmlDiff = {
+    compareNodes(left, right, options, Nil)
+  }
+
+  private def compareNodes(left: Node, right: Node, options: DiffOptions, path: Seq[String]): XmlDiff = {
     val checks: Seq[Check] = Seq(
       compareNamespace,
       compareText,
@@ -22,51 +60,55 @@ object XmlCompare {
         // already failed
         status
       } else {
-        check(left, right, options)
+        check(left, right, options, path)
       }
     }
   }
 
-  private def compareNamespace(left: Node, right: Node, options: DiffOptions): XmlDiff = {
+  private def compareNamespace(left: Node, right: Node, options: DiffOptions, path: Seq[String]): XmlDiff = {
     if (left.label != right.label) {
-      XmlDiffers("different label", left.label, right.label)
-    } else if (left.namespace != right.namespace) {
-      XmlDiffers("different namespace", left.namespace, right.namespace)
-    } else if (left.prefix != right.prefix && !options.contains(IgnorePrefix)) {
-      XmlDiffers("different prefix", left.prefix, right.prefix)
+      XmlDiffers("different label", left.label, right.label, extendPath(path, left))
+    } else if (left.namespace != right.namespace && !options.contains(IgnoreNamespace)) {
+      XmlDiffers("different namespace", left.namespace, right.namespace, extendPath(path, left))
+    } else if (left.prefix != right.prefix && !options.contains(IgnoreNamespacePrefix) &&
+               !options.contains(IgnoreNamespace)) {
+      XmlDiffers("different namespace prefix", left.prefix, right.prefix, extendPath(path, left))
     } else {
       XmlEqual
     }
   }
 
-  private def compareText(left: Node, right: Node, options: DiffOptions): XmlDiff = {
-    val leftText = left.child.collect({case t: Text => t}).map(_.text.trim).mkString
-    val rightText = right.child.collect({case t: Text => t}).map(_.text.trim).mkString
+  private def compareText(left: Node, right: Node, options: DiffOptions, path: Seq[String]): XmlDiff = {
+    val leftText = left.child.collect({ case t: Text => t }).map(_.text.trim).mkString
+    val rightText = right.child.collect({ case t: Text => t }).map(_.text.trim).mkString
 
     if (leftText != rightText) {
-      XmlDiffers("different text", leftText, rightText)
+      XmlDiffers("different text", leftText, rightText, extendPath(path, left))
     } else {
       XmlEqual
     }
   }
 
-  private def compareChildren(left: Node, right: Node, options: DiffOptions): XmlDiff = {
+  private def compareChildren(left: Node, right: Node, options: DiffOptions, path: Seq[String]): XmlDiff = {
     val leftChildren = left.child.filterNot(_.isInstanceOf[Text])
     val rightChildren = right.child.filterNot(_.isInstanceOf[Text])
 
     if (leftChildren.size != rightChildren.size) {
-      XmlDiffers("child count", leftChildren.size, rightChildren.size)
+      XmlDiffers("different child count", leftChildren.size, rightChildren.size, extendPath(path, left))
     } else {
-      val matchedChildren = leftChildren.zip(rightChildren)
-
-      matchedChildren.foldLeft[XmlDiff](XmlEqual) { case (status, (leftChild, rightChild)) =>
-        if (!status.isEqual) {
-          // already failed
-          status
-        } else {
-          compare(leftChild, rightChild, options)
-        }
+      leftChildren.zip(rightChildren).foldLeft[XmlDiff](XmlEqual) {
+        case (status, (leftChild, rightChild)) =>
+          if (!status.isEqual) {
+            // already failed
+            status
+          } else {
+            compareNodes(leftChild, rightChild, options, extendPath(path, left))
+          }
       }
     }
   }
+
+  private def extendPath(path: Seq[String], node: Node): Seq[String] = {
+    path :+ node.nameToString(new StringBuilder()).toString
+  }
 }

xml-compare/src/main/scala/software/purpledragon/xml/compare/XmlDiff.scala

@@ -1,18 +1,56 @@
+/*
+ * Copyright 2017 Michael Stringer
+ *
+ * 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 software.purpledragon.xml.compare
 
+/**
+ * Results of a comparison between XML documents. Can be either [[XmlEqual]] or [[XmlDiffers]] (with details of the
+ * differences).
+ */
 sealed trait XmlDiff {
+
+  /** `true` if the XML documents are the same. */
   def isEqual: Boolean
+
+  /** Descriptive message containing the differences (if any). */
   def message: String
+
+  /** Path of the first difference (if any). */
+  def failurePath: Seq[String]
 }
 
+/**
+ * Result of a successful comparison between XML documents.
+ */
 object XmlEqual extends XmlDiff {
-  override def isEqual: Boolean = true
-  override def toString: String = "XmlEqual"
-  override def message: String = ""
+  override val isEqual = true
+  override val toString: String = "XmlEqual"
+  override val message = ""
+  override val failurePath: Seq[String] = Nil
 }
 
-case class XmlDiffers(reason: String, left: Any, right: Any) extends XmlDiff {
-  override def isEqual: Boolean = false
-
-  override def message: String = s"$reason - $left != $right"
+/**
+ * Result of an unsuccessful comparison between XML documents.
+ *
+ * @param reason descriptive reason for the comparison failing.
+ * @param left the left-hand value in the failed comparison.
+ * @param right the right-hand value in the failed comparison.
+ * @param failurePath path to the failed node.
+ */
+case class XmlDiffers(reason: String, left: Any, right: Any, failurePath: Seq[String]) extends XmlDiff {
+  override val isEqual = false
+  override val message = s"$reason: [$left] != [$right]"
 }

xml-compare/src/main/scala/software/purpledragon/xml/compare/options/DiffOption.scala

@@ -1,7 +1,52 @@
+/*
+ * Copyright 2017 Michael Stringer
+ *
+ * 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 software.purpledragon.xml.compare.options
 
+/**
+ * Configuration options for XML comparisons.
+ */
 object DiffOption extends Enumeration {
   type DiffOption = Value
 
-  val IgnorePrefix = DiffOption
+  /**
+   * Ignores XML namespace prefixes on elements.
+   *
+   * Enabling this makes this:
+   * {{{
+   *   <t:example xmlns:t="http://example.com">5</t:example>
+   * }}}
+   * equal to:
+   * {{{
+   *   <f:example xmlns:f="http://example.com">5</f:example>
+   * }}}
+   */
+  val IgnoreNamespacePrefix: DiffOption.Value = Value
+
+  /**
+   * Ignores XML namespaces completely.
+   *
+   * Enabling this makes this:
+   * {{{
+   *   <t:example xmlns:t="http://example.com">5</t:example>
+   * }}}
+   * equal to:
+   * {{{
+   *   <f:example xmlns:f="http://example.org">5</f:example>
+   * }}}
+   */
+  val IgnoreNamespace: DiffOption.Value = Value
 }

xml-compare/src/main/scala/software/purpledragon/xml/compare/options/package.scala

@@ -1,5 +1,27 @@
+/*
+ * Copyright 2017 Michael Stringer
+ *
+ * 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 software.purpledragon.xml.compare
 
+import software.purpledragon.xml.compare.options.DiffOption.DiffOption
+
 package object options {
-  type DiffOptions = Set[DiffOption.type]
+
+  /**
+   * Shorthand for a collection of [[DiffOption]]s.
+   */
+  type DiffOptions = Set[DiffOption]
 }