jf

README

jf: Json difF

JSON diff library and simple CLI in Go. It can diff two arbitrary complex JSON files if they starts as an json object.

Installation and usage

git clone https://github.com/vyskocilm/jf
cd jf
go test
go build github.com/vyskocilm/jf/cmd/jf
./jf testdata/a.json testdata/b.json
bool       true    false
ints[2]    1       99
number     42      43
string     "hello" "hellp"
strings[1] "world" "worle"

Warning: depends on reflect and gihub.com/stretchr/objx and both CAN panic in some circumstances. Package jf type checks everything before use, so it uses methods like value.MustInt(). However it panics itself if code ends in an impossible (or not yet implemented one) situation. For example if diffing code finds a weird type of interface{}, like Go channel or a pointer. Those can't be passed in JSON.

In any case. Panic of jf is always a sign of a bug or missing feature, so do not forget to create an issue on GitHub if you will find one.

Features

1. compare primitive values, ints, floats, bools and strings
2. allows a specification of float equality function (can be used for int/float coercion)
3. compare arrays and maps
4. null coerce for A/B or both jsons
5. ignore certain keys
6. basic cmdline tool
7. ignore order of arrays

TODO

1. API docs
2. flags for cmdline tool (those starting by x- are temporary only and will be dropped)
3. custom comparator on objx.Value/objx.Value or string???

Simple values

{
 "number": 42,
 "string": "hello",
 "strings": ["hello", "world"],
 "ints": [4, 2, 1]
}
------------------------------
{
 "number": 43,
 "string": "hellp",
 "strings": ["hello", "worle"],
 "ints": [4, 2, 99]
}
------------------------------
ints[2]    1       99
number     42      43
string     "hello" "hellp"
strings[1] "world" "worle"

Nested maps

{
 "key": {
  "subkey": {
   "id": 11,
   "name": "joe"
  }
 }
}
------------------------------
{
 "key": {
  "subkey": {
   "id": 11,
   "name": "Joe"
  }
 }
}
------------------------------
key.subkey.name "joe" "Joe"

See jsondiff_test.go for more examples.

Documentation

Index

• Constants
• type CustomEqualFunc
• type DiffList
  • func Diff(jsonA, jsonB string) (DiffList, error)
• type Differ
  • func NewDiffer() *Differ
  • func (d *Differ) AddCoerceNull(dest ruleDest, selector *regexp.Regexp) *Differ
  • func (d *Differ) AddCustomEqual(selector *regexp.Regexp, fn CustomEqualFunc) *Differ
  • func (d *Differ) AddFloatEqual(selector *regexp.Regexp, fn FloatEqualFunc) *Differ
  • func (d *Differ) AddIgnore(dest ruleDest, selector *regexp.Regexp) *Differ
  • func (d *Differ) AddIgnoreIfZero(dest ruleDest, selector *regexp.Regexp) *Differ
  • func (d *Differ) AddIgnoreOrder(selector *regexp.Regexp) *Differ
  • func (d *Differ) AddStringNumber(selector *regexp.Regexp) *Differ
  • func (d *Differ) Diff(jsonA, jsonB string) (DiffList, error)
• type FloatEqualFunc
• type SingleDiff
  • func (d *SingleDiff) A() string
  • func (d *SingleDiff) B() string
  • func (d *SingleDiff) Selector() string

Constants

const (
	RuleA ruleDest = iota
	RuleB
	RuleAB
)

Types

type CustomEqualFunc

type CustomEqualFunc func(string, *objx.Value, *objx.Value) bool

CustomeEqualFn is a function implementing custom comparsion for a selector and two *obj.Value. If this matches, then

• all other rules does not apply
• jf will stop the recursion to items below
• if applied on items with ignored order, then selector matches either jsonA, either jsonB

type DiffList

type DiffList []SingleDiff

func Diff

func Diff(jsonA, jsonB string) (DiffList, error)

Diff is a shortcut for NewDiffer().Diff, exact diffing without any filters

type Differ

type Differ struct {
	// contains filtered or unexported fields
}

Differ traverse through JSONS and diff each part. It stores actual differences and can apply rules to different parts for comparison

func NewDiffer

func NewDiffer() *Differ

NewDiffer creates new empty differ with no rules. It can get additional processing rules via AddXYZ methods

func (*Differ) AddCoerceNull

func (d *Differ) AddCoerceNull(dest ruleDest, selector *regexp.Regexp) *Differ

AddCoerceNull enables coercion of null value to empty value for given type "key": null will be equivalent of {}, [], "", 0 and false

func (*Differ) AddCustomEqual

func (d *Differ) AddCustomEqual(selector *regexp.Regexp, fn CustomEqualFunc) *Differ

AddCustomEqualFunc adds a function for comparing custom values. Note this function is special and precedes all the other rules except ignore order for arrays. In this specific case provided JSON Path selector applies to jsonA or jsonB

func (*Differ) AddFloatEqual

func (d *Differ) AddFloatEqual(selector *regexp.Regexp, fn FloatEqualFunc) *Differ

AddFloatEqual adds a function for comparing floats. Default function expects numbers to be the same up to 1e-9

func (*Differ) AddIgnore

func (d *Differ) AddIgnore(dest ruleDest, selector *regexp.Regexp) *Differ

AddIgnore adds selectors, which will be ignored in resulting diff

func (*Differ) AddIgnoreIfZero

func (d *Differ) AddIgnoreIfZero(dest ruleDest, selector *regexp.Regexp) *Differ

AddIgnoreIfEmpty adds selectors, which will be ignored in a case value is empty

func (*Differ) AddIgnoreOrder

func (d *Differ) AddIgnoreOrder(selector *regexp.Regexp) *Differ

AddIgnoreRule ignores order of arrays, so [1, 2, 3] == [3, 2, 1]

func (*Differ) AddStringNumber

func (d *Differ) AddStringNumber(selector *regexp.Regexp) *Differ

AddStringNumber equals "1" == 1

func (*Differ) Diff

func (d *Differ) Diff(jsonA, jsonB string) (DiffList, error)

Diff returns a list of individual differences by comparing the jsonA and jsonB inputs supports arbitrary JSON files, if the top level is map of strings

type FloatEqualFunc

type FloatEqualFunc func(float64, float64) bool

FloatEqualFn is a function comparing two floats

type SingleDiff

type SingleDiff struct {
	// contains filtered or unexported fields
}

SingleDiff express the difference of one JSON selector

func (*SingleDiff) A

func (d *SingleDiff) A() string

func (*SingleDiff) B

func (d *SingleDiff) B() string

func (*SingleDiff) Selector

func (d *SingleDiff) Selector() string