Provide API to programmatically interpret differences

[deinspanjer]

I have config objects in a DSL that are described via a series of structs. As an example:
https://play.golang.org/p/NQfRr0iJy8s

Given two different instances of the Quiz struct, I'd like to be able to find out starting at any particular level, if there are differences.

If I used the cmp.Diff() method, I think I could parse out the syntax to determine what the actual changes, adds, and deletes are, but not only does this feel fragile, it is explicitly warned against in the docs.

So, is there a better way?

[dsnet]

It seems that what you're asking for is a programmatic way to interpret the diff. Is that correct?

[deinspanjer]

I believe that sounds right. What my code is attempting to return is a set of results containing any adds, removes, or changes as discrete sets so that the consumer of this result object can perform whatever operations are necessary upon the objects that had those changes.

[nhooyr]

This would be really nice for structured logging of diffs as well.

[dsnet]

Would API like the following suffice?

// Reporter wraps the provided reporter as an Option. 
func Reporter(interface {
	// PushStep is called when a tree-traversal operation is performed
	// and provides the sub-values of x and y after applying the operation.
	// The PathStep is valid until the step is popped, while the reflect.Values
	// are valid while the entire tree is still being traversed.
	//
	// Equal and Diff always call PushStep at the start to provide an
	// operation-less PathStep used to report the root values.
	PushStep(ps PathStep, x, y reflect.Value)

	// Report is called at exactly once on leaf nodes to report whether the
	// comparison identified the node as equal, unequal, or ignored.
	// A leaf node is one that is immediately preceded by and followed by
	// a pair of PushStep and PopStep calls.
	Report(ReportFlags)

	// PopStep ascends back up the value tree.
	// There is always a matching pop call for every push call.
	PopStep()
}) Option

// ReportFlags is bit-set of reporting information about the comparison.
type ReportFlags uint

const (
	// ReportIgnored reports whether the node was ignored.
	ReportIgnored ReportFlags = iota
	// ReportEqual reports whether the node is equal.
	ReportEqual
	// reportUnequal reports whether the node is not equal.
	ReportUnequal
)

This API allows the user to pass in their own reporter and get a structured representation of the diff. The internal default reporter is being switched to use an API like this.

See report.go for an example of an implementation of this API that only report differences similar to what it does today.

[SVenky]

@dsnet : Is this already available? If so do we have an example or test code to refer on how to use it? if not available yet, any timeline of when we can expect the same. Thanks a lot!

[dsnet]

It's here at #123. I wanted to seriously think through the implications of the final API before merging, but anticipate that it will happen next week.

See here for an example: https://github.com/google/go-cmp/pull/123/files#diff-723c10615c952a994128a9cf62e6ca49

[dsnet]

Fixed by #123.