Merge pull request #2 from xdotai/fixes

Fixes & readme

Author: cvogt

README.md

@@ -0,0 +1,79 @@
+## diff
+
+A tool to visually compare Scala data structures with out of the box support for arbitrary case classes.
+
+### SBT Dependency
+
+`"ai.x" %% "diff" % "1.0"`
+
+### Usage
+
+```scala
+println(  DiffShow.diff( before, after ).string  )
+```
+
+#### Output
+
+<img width="422" alt="example-output" src="https://cloud.githubusercontent.com/assets/274947/15580477/e46957e6-2336-11e6-919c-3eaf00f60cff.png">
+
+#### Code
+
+```scala
+sealed trait Parent
+case class Bar( s: String, i: Int ) extends Parent
+case class Foo( bar: Bar, b: List[Int], parent: Option[Parent] ) extends Parent
+
+val before: Foo = Foo(
+  Bar( "asdf", 5 ),
+  List( 123, 1234 ),
+  Some( Bar( "asdf", 5 ) )
+)
+val after: Foo = Foo(
+  Bar( "asdf", 66 ),
+  List( 1234 ),
+  Some( Bar( "qwer", 5 ) )
+)
+```
+
+### SBT Dependency
+
+#### Custom comparison
+
+Sometimes you may need to write your own type class instances. For example for non-case classes that don't compare well using ==.
+
+```scala
+implicit def localTimeDiffShow = {
+  val show = ( d: org.joda.time.LocalTime ) => "LocalTime(" + d.toString + ")"
+  DiffShow.create[org.joda.time.LocalTime]( show, ( l, r ) =>
+    if ( l isEqual r ) Identical( show( l ) ) else Different( showChange( show( l ), show( r ) ) ) )
+}
+```
+
+#### Ignore parts of data
+
+Sometimes you may want to ignore some parts of your data during comparison.
+You can do so by type, e.g. for non-deterministic parts like ObjectId, which always differ.
+
+```scala
+def ignore[T] = new DiffShow[T] {
+  def show( t: T ) = t.toString
+  def diff( left: T, right: T ) = Identical( "<not compared>" )
+  override def diffable( left: T, right: T ) = true
+}
+implicit def LocationIdShow = ignore[LocationId]
+```
+
+#### Influence comparison in collections
+
+When comparing collections you can influence if two elements should be compared or treated as completely different.
+Comparing elements shows their partial differences. Not comparing them shows them as added or removed.
+
+```scala
+implicit def PersonDiffShow[L <: HList](
+  implicit
+  labelled:  LabelledGeneric.Aux[Person, L],
+  hlistShow: Lazy[DiffShowFields[L]]
+) = new CaseClassDiffShow[Person, L] {
+  override def diffable( left: Person, right: Person ) = left._id === right._id
+}
+```

build/build.scala

@@ -3,19 +3,21 @@ import java.net._
 import java.io.File
 import scala.collection.immutable.Seq
 
+// cbt:https://github.com/cvogt/cbt.git#cf7a66b7dfde8bb4386efe93a41f68996335db35
 class Build(context: cbt.Context) extends cbt.PublishBuild(context){
-  override def scalaVersion = "2.11.7"
+  override def defaultScalaVersion = "2.11.8"
 
-  override def version = "1.0-SNAPSHOT"
-  override def artifactId = "diff_2.11"
+  override def defaultVersion = "1.0"
+  override def artifactId = "diff"
   override def groupId = "ai.x"
 
   override def runClass: String = "ai.x.diff.Test"
 
-  override def dependencies = super.dependencies :+ MavenRepository.central.resolve(
-    "com.chuusai" %% "shapeless" % "2.1.0",
-    "org.cvogt" %% "scala-extensions" % "0.4.1"
-  )
+  override def dependencies = super.dependencies ++
+    Resolver( mavenCentral ).bind(
+      "com.chuusai" %% "shapeless" % "2.3.1",
+      "org.cvogt" %% "scala-extensions" % "0.4.1"
+    )
   override def scalacOptions = Seq( "-language:experimental.macros" )
 
   override def url = new URL("http://github.com/xdotai/diff")

diff.scala

@@ -1,16 +1,21 @@
 package ai.x.diff
-import scala.collection.immutable.SortedMap
 import shapeless._, record._, shapeless.syntax._, labelled._, ops.record._, ops.hlist._
 import org.cvogt.scala.string._
 
 object `package` {
-  def red( s: String ) = Console.RED ++ s ++ Console.RESET
-  def green( s: String ) = Console.GREEN ++ s ++ Console.RESET
-  def blue( s: String ) = Console.BLUE ++ s ++ Console.RESET
-  def pad( s: Any, i: Int = 5 ) = ( " " * ( i - s.toString.size ) ) ++ s.toString
-  def arrow( l: String, r: String ) = l ++ " -> " ++ r
-  def showChange( l: String, r: String ) = red( l ) ++ " -> " ++ green( r )
+  def red( s: String ) = Console.RED + s + Console.RESET
+  def green( s: String ) = Console.GREEN + s + Console.RESET
+  def blue( s: String ) = Console.BLUE + s + Console.RESET
+  def pad( s: Any, i: Int = 5 ) = ( " " * ( i - s.toString.size ) ) + s
+  def arrow( l: String, r: String ) = l + " -> " + r
+  def showChange( l: String, r: String ) = red( l ) + " -> " + green( r )
 }
+/*
+Loose TODO:
+- replace many of the manual type classes with shapeless type class derivation
+- introduce intermediate representation to allow alternative String renderings and allow easy testability of added/removed
+- split Show and Diff
+*/
 
 abstract class Comparison {
   def string: String
@@ -164,16 +169,17 @@ abstract class DiffShowInstances extends DiffShowInstancesLowPriority {
       val ( left, right ) = ( _left.toList, _right.toList )
       val removed = left.filterNot( l => right.exists( r => DiffShow.diffable( l, r ) ) )
       val added = right.filterNot( r => left.exists( l => DiffShow.diffable( l, r ) ) )
-      val comparable = left.filter( l => right.exists( r => DiffShow.diffable( l, r ) ) )
+      val comparableLeft = left.filter( l => right.exists( r => DiffShow.diffable( l, r ) ) )
+      val comparableRight = right.filter( l => left.exists( r => DiffShow.diffable( l, r ) ) )
       val identical = for {
-        l <- comparable
-        r <- comparable if DiffShow.diffable( l, r )
+        l <- comparableLeft
+        r <- comparableRight if DiffShow.diffable( l, r )
         Identical( s ) <- DiffShow.diff( l, r ) :: Nil
       } yield l
 
       val changed = for {
-        l <- comparable diff identical
-        r <- comparable diff identical if DiffShow.diffable( l, r )
+        l <- comparableLeft diff identical
+        r <- comparableRight diff identical if DiffShow.diffable( l, r )
         // The pattern match here is fishy. It should really only contain Different ones, but might not if == is screwed up.
         Different( s ) <- DiffShow.diff( l, r ) :: Nil
       } yield s
@@ -221,7 +227,6 @@ abstract class DiffShowInstances extends DiffShowInstancesLowPriority {
             show( added ).map( ( arrow _ ).tupled ).map( green )
           ).flatten.map( s => Option( ( "", s ) ) )
         )
-
       if ( removed.isEmpty && added.isEmpty && changed.isEmpty )
         Identical( string )
       else

example-output.png

@@ -1,4 +1,5 @@
 import ai.x.diff._
+import scala.collection.immutable.SortedMap
 object Main extends App {
   sealed trait Parent
   case class Bar( s: String, i: Int ) extends Parent
@@ -18,4 +19,59 @@ object Main extends App {
   println(
     DiffShow.diff( before, after ).string
   )
+
+  {
+    implicit def StringDiffShow = new DiffShow[String] {
+      def show( t: String ) = t
+      def diff( left: String, right: String ) = if(left == right) Identical(left) else Different(left, right)
+      override def diffable( left: String, right: String ) = left.lift(0) == right.lift(0)
+    }
+
+    println(
+      DiffShow.diff(
+        "adsf" :: "qwer" :: Nil,
+        "axx" :: "yxcv" :: Nil
+      ).string
+    )
+  }
+
+  /*
+
+  //import pprint.Config.Defaults._
+
+  val actual = compare( before, after )
+  val expected = Different(
+    Tree( before ),
+    Tree( after ),
+    SortedMap(
+      "bar" -> Different(
+        Tree( Bar( "asdf", 5 ) ),
+        Tree( Bar( "asdf", 66 ) ),
+        SortedMap(
+          "s" -> Identical( Leaf( "asdf" ) ),
+          "i" -> Different(
+            Leaf( 5 ), Leaf( 66 ), SortedMap()
+          )
+        )
+      ),
+      "b" -> Different(
+        Leaf( 123 :: 1234 :: Nil ), Leaf( 1234 :: Nil ), SortedMap()
+      )
+    )
+  )
+  //pprint.pprintln( ( Generic[Bar] to Bar( "asdf", 5 ) ) delta ( Generic[Bar] to Bar( "asdf", 66 ) ) )
+  assert( actual == expected, "expected\n:" + pprint.tokenize( expected ).mkString + "\n\nactual:\n" + pprint.tokenize( actual ).mkString )
+
+  println( expected.show() )
+
+  """
+  Foo(
+    b   = List( 123 +, 1234 ),
+    bar = Bar(
+      s = asdf,
+      i = -5 +66
+    )
+  )
+  """
+  */
 }