diff

README

diff

A library for diffing golang structures and values.

Utilizing field tags and reflection, it is able to compare two structures of the same type and create a changelog of all modified values. The produced changelog can easily be serialized to json.

Build status

• Master

Installation

go get github.com/r3labs/diff

Changelog Format

When diffing two structures using Diff, a changelog will be produced. Any detected changes will populate the changelog array with a Change type:

type Change struct {
	Type string      // The type of change detected; can be one of create, update or delete
	Path []string    // The path of the detected change; will contain any field name or array index that was part of the traversal
	From interface{} // The original value that was present in the "from" structure
	To   interface{} // The new value that was detected as a change in the "to" structure
}

Given the example below, we are diffing two slices where the third element has been removed:

from := []int{1, 2, 3, 4}
to := []int{1, 2, 4}

changelog, _ := diff.Diff(from, to)

The resultant changelog should contain one change:

Change{
    Type: "delete",
    Path: ["2"],
    From: 3,
    To:   nil,
}

Supported Types

A diffable value can be/contain any of the following types:

• struct
• slice
• string
• int
• bool
• map
• pointer

Tags

In order for struct fields to be compared, they must be tagged with a given name. All tag values are prefixed with diff. i.e. diff:"items".

• - : In the event that you want to exclude a value from the diff, you can use the tag diff:"-" and the field will be ignored.

• identifier : If you need to compare arrays by a matching identifier and not based on order, you can specify the identifier tag. If an identifiable element is found in both the from and to structures, they will be directly compared. i.e. diff:"name,identifier"

• immutable : Will omit this struct field from diffing. When using diff.StructValues() these values will be added to the returned changelog. It's usecase is for when we have nothing to compare a struct to and want to show all of its relevant values.

Usage

Basic Example

Diffing a basic set of values can be accomplished using the diff functions. Any items that specify a "diff" tag using a name will be compared.

import "github.com/r3labs/diff"

type Order struct {
    ID    string `diff:"id"`
    Items []int  `diff:"items"`
}

func main() {
    a := Order{
        ID: "1234",
        Items: []int{1, 2, 3, 4},
    }

    b := Order{
        ID: "1234",
        Items: []int{1, 2, 4},
    }

    changelog, err := diff.Diff(a, b)
    ...
}

In this example, the output generated in the changelog will indicate that the third element with a value of '3' was removed from items. When marshalling the changelog to json, the output will look like:

[
    {
        "type": "delete",
        "path": ["items", "2"],
        "from": 3,
        "to": null
    }
]

Options and Configuration

You can create a new instance of a differ that allows options to be set.

import "github.com/r3labs/diff"

type Order struct {
    ID    string `diff:"id"`
    Items []int  `diff:"items"`
}

func main() {
    a := Order{
        ID: "1234",
        Items: []int{1, 2, 3, 4},
    }

    b := Order{
        ID: "1234",
        Items: []int{1, 2, 4},
    }

	d, err := diff.NewDiffer(diff.SliceOrdering(true))
	if err != nil {
		panic(err)
	}

    changelog, err := d.Diff(a, b)
    ...
}

Supported options are:

SliceOrdering ensures that the ordering of items in a slice is taken into account

Running Tests

make test

Contributing

Please read through our contributing guidelines. Included are directions for opening issues, coding standards, and notes on development.

Moreover, if your pull request contains patches or features, you must include relevant unit tests.

Versioning

For transparency into our release cycle and in striving to maintain backward compatibility, this project is maintained under the Semantic Versioning guidelines.

Copyright and License

Code and documentation copyright since 2015 r3labs.io authors.

Code released under the Mozilla Public License Version 2.0.

Documentation

Index

• Constants
• Variables
• func AreType(a, b reflect.Value, types ...reflect.Type) bool
• func Changed(a, b interface{}) bool
• func CustomValueDiffers(vd ...ValueDiffer) func(d *Differ) error
• func DisableStructValues() func(d *Differ) error
• func SliceOrdering(enabled bool) func(d *Differ) error
• type Change
• type Changelog
  • func Diff(a, b interface{}) (Changelog, error)
  • func StructValues(t string, path []string, s interface{}) (Changelog, error)
  • func (cl *Changelog) Add(t string, path []string, from, to interface{})
  • func (cl *Changelog) Filter(path []string) Changelog
• type Comparative
• type ComparativeList
  • func NewComparativeList() *ComparativeList
• type Differ
  • func NewDiffer(opts ...func(d *Differ) error) (*Differ, error)
  • func (d *Differ) Diff(a, b interface{}) (Changelog, error)
• type ValueDiffer

Examples

• Diff

Constants

const (
	// CREATE represents when an element has been added
	CREATE = "create"
	// UPDATE represents when an element has been updated
	UPDATE = "update"
	// DELETE represents when an element has been removed
	DELETE = "delete"
)

Variables

var (
	// ErrTypeMismatch Compared types do not match
	ErrTypeMismatch = errors.New("types do not match")
	// ErrInvalidChangeType The specified change values are not unsupported
	ErrInvalidChangeType = errors.New("change type must be one of 'create' or 'delete'")
)

Functions

func AreType

func AreType(a, b reflect.Value, types ...reflect.Type) bool

func Changed

func Changed(a, b interface{}) bool

Changed returns true if both values differ

func CustomValueDiffers

func CustomValueDiffers(vd ...ValueDiffer) func(d *Differ) error

CustomValueDiffers allows you to register custom differs for specific types

func DisableStructValues

func DisableStructValues() func(d *Differ) error

DisableStructValues disables populating a separate change for each item in a struct, where the struct is being compared to a nil value

func SliceOrdering

func SliceOrdering(enabled bool) func(d *Differ) error

SliceOrdering determines whether the ordering of items in a slice results in a change

Types

type Change

type Change struct {
	Type string      `json:"type"`
	Path []string    `json:"path"`
	From interface{} `json:"from"`
	To   interface{} `json:"to"`
}

Change stores information about a changed item

type Changelog

type Changelog []Change

Changelog stores a list of changed items

func Diff

func Diff(a, b interface{}) (Changelog, error)

Diff returns a changelog of all mutated values from both

Example

type Tag struct {
	Name  string `diff:"name,identifier"`
	Value string `diff:"value"`
}

type Fruit struct {
	ID        int      `diff:"id"`
	Name      string   `diff:"name"`
	Healthy   bool     `diff:"healthy"`
	Nutrients []string `diff:"nutrients"`
	Tags      []Tag    `diff:"tags"`
}

a := Fruit{
	ID:      1,
	Name:    "Green Apple",
	Healthy: true,
	Nutrients: []string{
		"vitamin c",
		"vitamin d",
	},
	Tags: []Tag{
		{
			Name:  "kind",
			Value: "fruit",
		},
	},
}

b := Fruit{
	ID:      2,
	Name:    "Red Apple",
	Healthy: true,
	Nutrients: []string{
		"vitamin c",
		"vitamin d",
		"vitamin e",
	},
	Tags: []Tag{
		{
			Name:  "popularity",
			Value: "high",
		},
		{
			Name:  "kind",
			Value: "fruit",
		},
	},
}

changelog, err := Diff(a, b)
if err != nil {
	panic(err)
}

fmt.Printf("%#v", changelog)
// Produces: diff.Changelog{diff.Change{Type:"update", Path:[]string{"id"}, From:1, To:2}, diff.Change{Type:"update", Path:[]string{"name"}, From:"Green Apple", To:"Red Apple"}, diff.Change{Type:"create", Path:[]string{"nutrients", "2"}, From:interface {}(nil), To:"vitamin e"}, diff.Change{Type:"create", Path:[]string{"tags", "popularity"}, From:interface {}(nil), To:main.Tag{Name:"popularity", Value:"high"}}}

func StructValues

func StructValues(t string, path []string, s interface{}) (Changelog, error)

StructValues gets all values from a struct values are stored as "created" or "deleted" entries in the changelog, depending on the change type specified

func (*Changelog) Add

func (cl *Changelog) Add(t string, path []string, from, to interface{})

func (*Changelog) Filter

func (cl *Changelog) Filter(path []string) Changelog

Filter filter changes based on path. Paths may contain valid regexp to match items

type Comparative

type Comparative struct {
	A, B *reflect.Value
}

Comparative ...

type ComparativeList

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

ComparativeList : stores indexed comparative

func NewComparativeList

func NewComparativeList() *ComparativeList

NewComparativeList : returns a new comparative list

type Differ

type Differ struct {
	SliceOrdering       bool
	DisableStructValues bool
	// contains filtered or unexported fields
}

Differ a configurable diff instance

func NewDiffer

func NewDiffer(opts ...func(d *Differ) error) (*Differ, error)

NewDiffer creates a new configurable diffing object

func (*Differ) Diff

func (d *Differ) Diff(a, b interface{}) (Changelog, error)

Diff returns a changelog of all mutated values from both

type ValueDiffer

type ValueDiffer interface {
	Match(a, b reflect.Value) bool
	Diff(cl *Changelog, path []string, a, b reflect.Value) error
}

ValueDiffer is an interface for custom differs