cmp

Documentation

Index

• type Change
  • func (c Change) String() string
• type ChangeType
• type Comparator
• type CompareFunc
• type DiffNode
  • func NewEmptyNode(t reflect.Type, k reflect.Kind) *DiffNode
  • func (n *DiffNode) ChangeType() ChangeType
  • func (n *DiffNode) Child(key any) *DiffNode
  • func (n *DiffNode) Children() []*DiffNode
  • func (n *DiffNode) ChildrenKeys() []string
  • func (n *DiffNode) ChildrenKeysSorted() []string
  • func (n *DiffNode) HasChanged() bool
  • func (n *DiffNode) IsLeaf() bool
  • func (n *DiffNode) IsRoot() bool
  • func (n *DiffNode) Parent() *DiffNode
  • func (n *DiffNode) ParentByPath(path string) *DiffNode
  • func (n *DiffNode) Path() string
  • func (n *DiffNode) ToChange() Change
• type FormatOptions
• type Options
• type Pair
  • func (p *Pair) StringKey() string
• type Pairs
  • func NewPairs(t reflect.Type) Pairs
• type Result
  • func Compare(a any, b any, options ...Options) (*Result, error)
  • func (r Result) Changes() []Change
  • func (r Result) DistinctChanges() []Change
  • func (r Result) HasChanges() bool
  • func (r Result) ToYaml(options ...FormatOptions) string
  • func (r Result) Tree() *DiffNode
• type TypeMismatchError
  • func NewTypeMismatchError(aKind, bKind reflect.Kind) *TypeMismatchError
  • func (e *TypeMismatchError) Error() string

Types

type Change

type Change struct {
	Type ChangeType

	// Change paths.
	Path       string
	StructPath string

	// Metadata of compared values.
	ValueType   reflect.Type `cmp:"-"`
	ValueKind   reflect.Kind `cmp:"-"`
	ValueBefore any
	ValueAfter  any
}

func (Change) String

func (c Change) String() string

String returns change as a string.

type ChangeType

type ChangeType string

ChangeType represents the type of change detected between two values.

const (
	// Any indicates that the change type is unknown or unspecified.
	// In context of event rules, this change type is used to match any
	// other change type.
	Any ChangeType = ""

	// None indicates that no change has occurred between the two values.
	None ChangeType = "none"

	// Create indicates that a new field or value has been added to
	// the structure.
	Create ChangeType = "create"

	// Delete indicates that a field or value has been removed from
	// the structure.
	Delete ChangeType = "delete"

	// Modify indicates that an existing field or value the has been
	// altered.
	Modify ChangeType = "modify"
)

type Comparator

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

type CompareFunc

type CompareFunc func(reflect.Value, reflect.Value) (*DiffNode, error)

type DiffNode

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

DiffNode forms the comparison tree, capturing the differences between corresponding values in two data structures. A single DiffNode can act as the root of the tree or as any subsequent node.

func NewEmptyNode

func NewEmptyNode(t reflect.Type, k reflect.Kind) *DiffNode

func (*DiffNode) ChangeType

func (n *DiffNode) ChangeType() ChangeType

ChangeType returns type of the node's change.

func (*DiffNode) Child

func (n *DiffNode) Child(key any) *DiffNode

Child returns a Child node with a matching key and nil otherwise.

func (*DiffNode) Children

func (n *DiffNode) Children() []*DiffNode

ChildrenKeys returns keys of node's children.

func (*DiffNode) ChildrenKeys

func (n *DiffNode) ChildrenKeys() []string

ChildrenKeys returns keys of node's children.

func (*DiffNode) ChildrenKeysSorted

func (n *DiffNode) ChildrenKeysSorted() []string

ChildrenKeysSorted returns alphabetically sorted keys of node's children.

func (*DiffNode) HasChanged

func (n *DiffNode) HasChanged() bool

HasChanged returns true if node's change type indicates a change within the node itself or any of its children.

func (*DiffNode) IsLeaf

func (n *DiffNode) IsLeaf() bool

IsLeaf returns true if node has no children.

func (*DiffNode) IsRoot

func (n *DiffNode) IsRoot() bool

IsRoot returns true if node has no parent.

func (*DiffNode) Parent

func (n *DiffNode) Parent() *DiffNode

Parent returns node's parent or nil if node is root.

func (*DiffNode) ParentByPath

func (n *DiffNode) ParentByPath(path string) *DiffNode

ParentByPath searches upwards from the current node to find a node matching the given path. Returns the matching node or nil if none is found.

func (*DiffNode) Path

func (n *DiffNode) Path() string

Path returns node's path as a string with each section being separated with a dot.

func (*DiffNode) ToChange

func (n *DiffNode) ToChange() Change

ToChange returns the diff node as Change.

type FormatOptions

type FormatOptions struct {
	// ShowDiffOnly omits unchanged fields.
	ShowDiffOnly bool

	// ShowColor emphasizes changes with colors.
	ShowColor bool

	// ShowChangeTypePrefix adds change type prefix to each shown line.
	ShowChangeTypePrefix bool
}

FormatOptions contains configurations that control the result output.

type Options

type Options struct {
	// Tag specifies the primary tag from which the field name and options
	// are derived.
	Tag string

	// ExtraNameTags lists additional tags checked for field names. The
	// primary Tag always takes precedence.
	ExtraNameTags []string

	// RespectSliceOrder, when set, enforces slice comparison by index.
	// Otherwise, slice's fields are first checked if they contain id tag
	// option.
	RespectSliceOrder bool

	// IgnoreEmptyChanges, when set, omits tracking fields that remain nil
	// both before and after a change.
	IgnoreEmptyChanges bool

	// PopulateAllNodes ensures that 'before' and 'after' values are
	// retained even for non-leaf changes.
	PopulateAllNodes bool
}

Options define configurations that influence how the comparison is executed.

type Pair

type Pair struct {
	A reflect.Value
	B reflect.Value
	// contains filtered or unexported fields
}

Pair represents a pair of values from two Maps or Slices. The 'key' denotes the location in the parent map or slice. For maps, 'key' is the map key. For slices, it represents the slice ID or index.

func (*Pair) StringKey

func (p *Pair) StringKey() string

type Pairs

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

Pairs encapsulates the differences between two corresponding data structures (either Maps or Slices). It provides metadata about the type and kind of pairs it contains, and offers control over how changes are represented within the collection.

func NewPairs

func NewPairs(t reflect.Type) Pairs

type Result

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

Result wraps the DiffNode and exposes only certain set of operations.

func Compare

func Compare(a any, b any, options ...Options) (*Result, error)

Compare initializes default comparator, compares given values and returns a comparison tree.

func (Result) Changes

func (r Result) Changes() []Change

Changes extracts changes from the leaf nodes of the tree, ignoring changes in intermediary nodes.

func (Result) DistinctChanges

func (r Result) DistinctChanges() []Change

DistinctChanges extracts changes from the result tree, filtering out propagated changes. The extraction behavior is determined by the change type:

• Create/Delete: The change is returned without further traversal into child nodes, as all descendants have the same change type.
• Modify: If the node is a leaf, the change is returned; otherwise, the function descends further into child nodes.

func (Result) HasChanges

func (r Result) HasChanges() bool

HasChanges returns true if compared values contain any difference.

func (Result) ToYaml

func (r Result) ToYaml(options ...FormatOptions) string

ToYaml returns comparison result in YAML like format.

func (Result) Tree

func (r Result) Tree() *DiffNode

Tree returns the root node of the comparison result.

type TypeMismatchError

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

TypeMismatchError represents a type mismatch error when comparing two values of different types.

func NewTypeMismatchError

func NewTypeMismatchError(aKind, bKind reflect.Kind) *TypeMismatchError

func (*TypeMismatchError) Error

func (e *TypeMismatchError) Error() string