• Stars
    star
    295
  • Rank 140,902 (Top 3 %)
  • Language
    Clojure
  • License
    Eclipse Public Li...
  • Created about 6 years ago
  • Updated 9 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Deep diff Clojure data structures and pretty print the result

lambdaisland/deep-diff2

CircleCI cljdoc badge Clojars Project bb compatible

Recursively compare Clojure or ClojureScript data structures, and produce a colorized diff of the result.

screenshot showing REPL example

Deep-diff2 is foremost intended for creating visual diffs for human consumption, if you want to programatically diff/patch Clojure data structures then Editscript may be a better fit, see this write-up by Huahai Yang.

 

 

Support Lambda Island Open Source

deep-diff2 is part of a growing collection of quality Clojure libraries and tools released on the Lambda Island label. If you are using this project commercially then you are expected to pay it forward by becoming a backer on Open Collective, so that we may continue to enjoy a thriving Clojure ecosystem.

 

 

Installation

deps.edn

lambdaisland/deep-diff2 {:mvn/version "2.8.190"}

project.clj

[lambdaisland/deep-diff2 "2.8.190"]

Use

(require '[lambdaisland.deep-diff2 :as ddiff])

(ddiff/pretty-print (ddiff/diff {:a 1 :b 2} {:a 1 :c 3}))

Diffing

lambdaisland.deep-diff2/diff takes two arguments and returns a "diff", a data structure that contains markers for insertions, deletions, or mismatches. These are records with - and + fields.

(ddiff/diff {:a 1 :b 2} {:a 1 :b 3})
{:a 1, :b #lambdaisland.deep_diff.diff.Mismatch{:- 2, :+ 3}}

Printing

You can pass this diff to lambdaisland.deep-diff2/pretty-print. This function uses Puget and Fipp to format the diff and print the result to standard out.

For fine grained control you can create a custom Puget printer, and supply it to pretty-print.

(def narrow-printer (ddiff/printer {:width 10}))

(ddiff/pretty-print (ddiff/diff {:a 1 :b 2} {:a 1 :b 3}) narrow-printer)

For more advanced uses like incorporating diffs into your own Fipp documents, see lambdaisland.deep-diff2.printer/format-doc, lambdaisland.deep-diff2.printer/print-doc.

Minimizing

If you are only interested in the changes, and not in any values that haven't changed, then you can use ddiff/minimize to return a more compact diff.

This is especially useful for potentially large nested data structures, for example a JSON response coming from a web service.

(-> (ddiff/diff {:a "apple" :b "pear"} {:a "apple" :b "banana"})
    ddiff/minimize
    ddiff/pretty-print)
;; {:b -"pear" +"banana"}

Print handlers for custom or built-in types

In recent versions deep-diff2 initializes its internal copy of Puget with {:print-fallback :print}, meaning it will fall back to using the system printer, which you can extend by extending the print-method multimethod.

This also means that we automatically pick up additional handlers installed by libraries, such as time-literals.

You can also register print handlers for deep-diff2 specifically by using lambdaisland.deep-diff2.printer-impl/register-print-handler!, or by passing an :extra-handlers map to printer.

If you are dealing with printing of custom types you might find that there are multiple print implementations you need to keep up-to-date, see lambdaisland.data-printers for a high-level API that can work with all the commonly used print implementations.

Example of a custom type

See repl_sessions/custom_type.clj for the full code and results.

(deftype Degrees [amount unit]
  Object
  (equals [this that]
    (and (instance? Degrees that)
         (= amount (.-amount that))
         (= unit (.-unit that)))))

;; Using system handler fallback
(defmethod print-method Degrees [degrees out]
  (.write out (str (.-amount degrees) "°" (.-unit degrees))))
  
;; OR Using a Puget-specific handler
(lambdaisland.deep-diff2.printer-impl/register-print-handler!
 `Degrees
 (fn [printer value]
   [:span
    (lambdaisland.deep-diff2.puget.color/document printer :number (str (.-amount value)))
    (lambdaisland.deep-diff2.puget.color/document printer :tag "°")
    (lambdaisland.deep-diff2.puget.color/document printer :keyword (str (.-unit value)))]))

Set up a custom print handler with different colors by utilizing Puget library

Sometimes, we need to tune the colors to:

  • Ensure adequate contrast on a different background.
  • Ensure readability by people who are colorblind.
  • Match your editor or main diff tool's color scheme.

Config of Puget

Fortunately, the Puget library included in deep-diff2 already allows customization through a custom printer.

In the Puget libray, 8-bit scheme is expressed via [:fg-256 5 n] where n is between 0 and 255. We can combine foreground and background, for example, like so: [:fg-256 5 226 :bg-256 5 56].

24-bit scheme is expressed via [:fg-256 2 r g b] where r g b are each between 0 and 255. Foreground and background can be combined, for example: [:fg-256 2 205 236 255 :bg-256 2 110 22 188].

An example of customizing color

For example, if we change the :lambdaisland.deep-diff2.printer-impl/deletion from [:red] to [:bg-256 5 13], the color code it outputs will change from \u001b[31m to \u001b[48;5;13m

user=> (use 'lambdaisland.deep-diff2)
nil
user=> (def color-printer (printer {:color-scheme {:lambdaisland.deep-diff2.printer-impl/deletion [:bg-256 5 13]}}))
#'user/color-printer
user=> (pretty-print (diff {:a 1} {:b 2}) color-printer)
{+:b 2, -:a 1}

That results in the following highlighting: screenshot showing color customization

Time, data literal

A common use case is diffing and printing Java date and time objects (java.util.Date, java.time.*, java.sql.Date|Time|DateTime).

Chances are you already have print handlers (and data readers) set up for these via the time-literals library (perhaps indirectly by pulling in tick. In that case these should just work.

(ddiff/diff #inst "2019-04-09T14:57:46.128-00:00"
            #inst "2019-04-10T14:57:46.128-00:00")

or

(import '[java.sql Timestamp])
(ddiff/diff (Timestamp. 0)
            (doto (Timestamp. 1000) (.setNanos 101)))

If you need to diff a rich set of time literal, using

(require '[time-literals.read-write])
(require '[lambdaisland.deep-diff2 :as ddiff])
(time-literals.read-write/print-time-literals-clj!)
(ddiff/pretty-print (ddiff/diff #time/date "2039-01-01" #time/date-time "2018-07-05T08:08:44.026"))

Deep-diff 1 vs 2

The original deep-diff only worked on Clojure, not ClojureScript. In porting the code to CLJC we were forced to make some breaking changes. To not break existing consumers we decided to move both the namespaces and the released artifact to new names, so the old and new deep-diff can exist side by side.

We also had to fork Puget to make it cljc compatible. This required breaking changes as well, making it unlikely these changes will make it upstream, so instead we vendor our own copy of Puget under lambdaisland.deep-diff2.puget.*. This does mean we don't automatically pick up custom Puget print handlers, unless they are also registered with our own copy of Puget. See above for more info on that.

When starting new projects you should use lambdaisland/deep-diff2. However if you have existing code that uses lambdaisland/deep-diff and you don't need the ClojureScript support then it is not necessary to upgrade. The old version still works fine (on Clojure).

You can upgrade of course, simply by replacing all namespace names from lambdaisland.deep-diff to lambdaisland.deep-diff2. If you are only using the top-level API (diff, printer, pretty-print) and you aren't using custom print handlers, then things should work exactly the same. If you find that deep-diff 2 behaves differently then please file an issue, you may have found a regression.

The old code still lives on the deep-diff-1 branch, and we do accept bugfix patches there, so we may put out bugfix releases of the original deep-diff in the future. When in doubt check the CHANGELOG.

Contributing

Everyone has a right to submit patches to deep-diff2, and thus become a contributor.

Contributors MUST

  • adhere to the LambdaIsland Clojure Style Guide
  • write patches that solve a problem. Start by stating the problem, then supply a minimal solution. *
  • agree to license their contributions as EPL 1.0.
  • not break the contract with downstream consumers. **
  • not break the tests.

Contributors SHOULD

  • update the CHANGELOG and README.
  • add tests for new functionality.

If you submit a pull request that adheres to these rules, then it will almost certainly be merged immediately. However some things may require more consideration. If you add new dependencies, or significantly increase the API surface, then we need to decide if these changes are in line with the project's goals. In this case you can start by writing a pitch, and collecting feedback on it.

* This goes for features too, a feature needs to solve a problem. State the problem it solves, then supply a minimal solution.

** As long as this project has not seen a public release (i.e. is not on Clojars) we may still consider making breaking changes, if there is consensus that the changes are justified.

Credits

This library builds upon clj-diff, which implements a diffing algorithm for sequences, and clj-arrangements, which makes disparate types sortable.

Pretty printing and colorization are handled by Puget and Fipp.

This library was originally developed as part of the Kaocha test runner.

Another library that implements a form of data structure diffing is editscript.

License

Copyright © 2018-2020 Arne Brasseur and contributors

Available under the terms of the Eclipse Public License 1.0, see LICENSE.txt

More Repositories

1

kaocha

Full featured next gen Clojure test runner
Clojure
792
star
2

regal

Royally reified regular expressions
Clojure
326
star
3

uri

A pure Clojure/ClojureScript URI library
Clojure
243
star
4

trikl

Terminal UI library for Clojure
Clojure
145
star
5

witchcraft

Clojure API for manipulating Minecraft, based on Bukkit
Clojure
135
star
6

fetch

ClojureScript wrapper for the JavaScript fetch API
Clojure
122
star
7

glogi

A ClojureScript logging library based on goog.log
Clojure
119
star
8

ornament

Clojure Styled Components
Clojure
118
star
9

uniontypes

Union Types (ADTs, sum types) built on clojure.spec
Clojure
115
star
10

launchpad

Clojure/nREPL launcher
Clojure
87
star
11

classpath

Classpath/classloader/deps.edn related utilities
Clojure
84
star
12

corgi

Emacs Lisp
75
star
13

metabase-datomic

Datomic driver for Metabase
Clojure
65
star
14

chui

Clojure
62
star
15

npmdemo

Demo of using Node+Express with ClojureScript
Clojure
60
star
16

funnel

Transit-over-WebSocket Message Relay
Clojure
58
star
17

deja-fu

ClojureScript local time/date library with a delightful API
Clojure
48
star
18

facai

Factories for fun and profit. 恭喜發財!
Clojure
45
star
19

open-source

A collection of Clojure/ClojureScript tools and libraries
Clojure
43
star
20

witchcraft-workshop

materials and code for the ClojureD 2022 workshop on Minecraft+Clojure
Clojure
40
star
21

kaocha-cljs

ClojureScript support for Kaocha
Clojure
40
star
22

cljbox2d

Clojure
40
star
23

thirdpartyjs

Demonstration of how to use third party JS in ClojureScript
Clojure
38
star
24

kaocha-cucumber

Cucumber support for Kaocha
Clojure
37
star
25

dom-types

Implement ClojureScript print handlers, as well Datify/Navigable for various built-in browser types.
Clojure
36
star
26

kaocha-cloverage

Code coverage analysis for Kaocha
Clojure
32
star
27

ansi

Parse ANSI color escape sequences to Hiccup syntax
Clojure
31
star
28

embedkit

Metabase as a Dashboard Engine
Clojure
30
star
29

plenish

Clojure
30
star
30

pennon

A feature flag library for Clojure
Clojure
30
star
31

hiccup

Enlive-backed Hiccup implementation (clj-only)
Clojure
28
star
32

edn-lines

Library for dealing with newline separated EDN files
Shell
27
star
33

kaocha-cljs2

Run ClojureScript tests from Kaocha (major rewrite)
Clojure
26
star
34

witchcraft-plugin

Add Clojure support (and an nREPL) to any Bukkit-based Minecraft server
Clojure
23
star
35

cli

Opinionated command line argument handling, with excellent support for subcommands
Clojure
22
star
36

garden-watcher

A component that watches-and-recompiles your Garden stylesheets.
Clojure
22
star
37

reitit-jaatya

Freeze your reitit routes and create a static site out of it
Clojure
21
star
38

nrepl-proxy

Proxy for debugging nREPL interactions
Clojure
18
star
39

data-printers

Quickly define print handlers for tagged literals across print/pprint implementations.
Clojure
18
star
40

lambdaisland-guides

In depth guides into Clojure and ClojureScript by Lambda Island
TeX
17
star
41

specmonstah-malli

Clojure
17
star
42

faker

Port of the Ruby Faker gem
Clojure
15
star
43

puck

ClojureScript wrapper around Pixi.js, plus other game dev utils
Clojure
15
star
44

kaocha-junit-xml

JUnit XML output for Kaocha
Clojure
11
star
45

aoc_2020

Advent of Code 2020
Clojure
11
star
46

harvest

Flexible factory library, successor to Facai
Clojure
11
star
47

gaiwan_co

Website for Gaiwan GmbH
Clojure
8
star
48

nrepl

Main namespace for starting an nREPL server with `clj`
Clojure
8
star
49

zipper-viz

Visualize Clojure zippers using Graphviz
Clojure
8
star
50

exoscale

Clojure/Babashka wrapper for the Exoscale HTTP API
Clojure
7
star
51

webstuff

The web as it was meant to be
Clojure
7
star
52

birch

A ClojureScript/Lumo version of the Unix "tree" command
Clojure
7
star
53

funnel-client

Websocket client for Funnel + examples
Clojure
7
star
54

corgi-packages

Emacs Packages developed as part of Corgi
Emacs Lisp
7
star
55

kanban

Episode 9. Reagent
Clojure
6
star
56

react-calculator

A calculator built with ClojureScript and React
JavaScript
6
star
57

souk

Clojure
6
star
58

logback-clojure-filter

Logback appender filter that takes a Clojure expression
Clojure
6
star
59

breakout

The retro game "Breakout". re-frame/Reagent/React/SVG.
Clojure
5
star
60

activities

Clojure
5
star
61

booklog

Keep track of the books you read (Auth with Buddy)
Clojure
5
star
62

li40-ultimate

Code from episode 40: The Ultimate Dev Setup
Shell
5
star
63

l33t

Demo ClojureScript+Node.js app
JavaScript
5
star
64

ep47-interceptors

Accompanying code to Lambda Island episode 47. Interceptors.
Clojure
5
star
65

daedalus

"Path finding and Delaunay triangulation in 2D, cljs wrapper for hxdaedalus-js"
Clojure
5
star
66

component_example

Example code for the Lambda Island episodes about Component
Clojure
4
star
67

ep43-data-science-kixi-stats

Clojure
4
star
68

lambwiki

A small wiki app to demonstrate Luminus
Clojure
4
star
69

new-project

Template for new projects
Emacs Lisp
3
star
70

kaocha-boot

Kaocha support for Boot
Clojure
3
star
71

datomic-quick-start

Datomic Quickstart sample code
Clojure
3
star
72

redolist

TodoMVC in re-frame
Clojure
3
star
73

rolodex-gui

Reagent app for testing the Rolodex API
Clojure
2
star
74

ep33testcljs

Testing ClojureScript with multiple backends
Clojure
2
star
75

elpa

Lambda Island Emacs Lisp Package Archive
Emacs Lisp
2
star
76

datalog-benchmarks

Clojure
2
star
77

kaocha-doctest

Doctest test type for Kaocha
Clojure
1
star
78

morf

Clojure
1
star
79

land-of-regal

Playground for Regal
Clojure
1
star
80

compobook

An example Compojure app
Clojure
1
star
81

ep41-react-components-reagent

Demo code from Episode 41, using React Components from Reagent
Clojure
1
star
82

repl-tools

Clojure
1
star
83

li45_polymorphism

Code for Lambda Island episode 45 and 46 about Polymorphism
Clojure
1
star
84

dotenv

Clojure
1
star
85

kaocha-midje

Midje integration for Kaocha
Clojure
1
star
86

rolodex

Clojure
1
star
87

laoban

Clojure
1
star
88

cookie-cutter

Auto-generate Clojure test namespaces in bulk.
Clojure
1
star
89

shellutils

Globbing and other shell/file utils
Clojure
1
star
90

kaocha-cljs2-demo

Example setups for kaocha-cljs2. WIP
Clojure
1
star
91

kaocha-demo

Clojure
1
star
92

kaocha-nauseam

Example project with a large (artificial) test suite
Clojure
1
star
93

li39-integrant

Accompanying code for Lambda Island episode 38 about Integrant
Clojure
1
star
94

webbing

Clojure
1
star
95

slack-backfill

Save Slack history to JSON files
Clojure
1
star
96

janus

Parser for Changelog files
Clojure
1
star
97

xdemo

Demo of xforms/redux/kixi.stats
Clojure
1
star
98

ep23deftype

Code for Lambda Island Episode 23, deftype and definterface
Clojure
1
star
99

ep24defrecord

Code for Lambda Island Episode 24, defrecord and defprotocol
Clojure
1
star
100

ep32testing

Code for Lambda Island Episode 32, Introduction to Clojure Testing
Clojure
1
star