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
    }
]

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 AddCustomCmpType(typ reflect.Type, fn func(a, b interface{}) bool)
• func AddInterfaceCmpType(typ reflect.Type)
• func Changed(a, b interface{}) bool
• type Change
• type Changelog
  • func Diff(a, b interface{}) (Changelog, error)
  • func StructValues(t string, path []string, s interface{}) (Changelog, error)
  • func (cl *Changelog) Filter(path []string) Changelog
• type Comparative
• type ComparativeList
  • func NewComparativeList() *ComparativeList

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 AddCustomCmpType

func AddCustomCmpType(typ reflect.Type, fn func(a, b interface{}) bool)

AddCustomCmpType for custom comparison

func AddInterfaceCmpType

func AddInterfaceCmpType(typ reflect.Type)

AddInterfaceCmpType if new type

func Changed

func Changed(a, b interface{}) bool

Changed : returns true if both values differ

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) 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