compare

Documentation

Overview

Package compare has utilities for comparing values. The DeepEquals and Diff functions are the main entry points.

Index

• Constants
• Variables
• func Compare(reference, value interface{}, handler Handler)
• func DeepEqual(reference, value interface{}) bool
• func IsNil(o interface{}) bool
• func Register(f interface{})
• type Action
• type Comparator
  • func (t Comparator) AddDiff(reference, value interface{})
  • func (t Comparator) Compare(reference, value interface{})
  • func (t Comparator) With(p Path) Comparator
• type Custom
  • func (c *Custom) Compare(reference, value interface{}, handler Handler)
  • func (c *Custom) Diff(reference, value interface{}, limit int) []Path
  • func (c *Custom) Register(f interface{})
• type EntryOp
  • func (e EntryOp) Format(f fmt.State, r rune)
• type Fragment
• type Handler
• type Hidden
  • func (i Hidden) Format(f fmt.State, r rune)
• type IndexOp
  • func (i IndexOp) Format(f fmt.State, r rune)
• type LengthOp
• type MemberOp
  • func (m MemberOp) Format(f fmt.State, r rune)
• type MissingOp
• type NilOp
• type Path
  • func Diff(reference, value interface{}, limit int) []Path
  • func (p Path) Diff(reference, value interface{}) Path
  • func (p Path) Entry(key, reference, value interface{}) Path
  • func (p Path) Format(f fmt.State, r rune)
  • func (p Path) Index(i int, reference, value interface{}) Path
  • func (p Path) Length(reference, value interface{}) Path
  • func (p Path) Member(name string, reference, value interface{}) Path
  • func (p Path) Missing(reference, value interface{}) Path
  • func (p Path) Nil(reference, value interface{}) Path
  • func (p Path) Type(reference, value interface{}) Path
• type TypeOp

Constants

const (
	Length = LengthOp("·length")
	Type   = TypeOp("·type")
	Nil    = NilOp("nil")
	Key    = MissingOp("key")
)

const (
	// Missing is used when values are found to be missing from a container
	Missing = invalid("Missing")
)

Variables

var (
	// LimitReached the value panic is given to abort a comparison early.
	LimitReached = diffLimit{}
)

Functions

func Compare

func Compare(reference, value interface{}, handler Handler)

Compare delivers all the differences it finds to the specified Handler. If the reference and value are equal, the handler will never be invoked.

func DeepEqual

func DeepEqual(reference, value interface{}) bool

DeepEqual compares a value against a reference and returns true if they are equal.

func IsNil

func IsNil(o interface{}) bool

IsNil returns true if o is nil (either directly or a boxed nil).

func Register

func Register(f interface{})

Register assigns the function f with signature func(comparator, T, T) to be used as the default comparator for instances of type T. f may return nothing or a CompareAction. Register will panic if f does not match the expected signature, or if a custom comparator for type T has already been registered.

Types

type Action

type Action int

Action is the optional return value type of functions passes to Register and Custom.Register.

const (
	// Done is returned by custom comparison functions when the two objects
	// require no further comparisons.
	Done Action = iota

	// Fallback is returned by custom comparison functions when the comparison of
	// the two objects should continue with the fallback comparison method.
	Fallback
)

type Comparator

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

Comparator is passed to custom comparison functions holding the current comparison context.

func (Comparator) AddDiff

func (t Comparator) AddDiff(reference, value interface{})

AddDiff can be used by custom comparison functions to register a new difference. The current handler will be invoked with the current path plus a Diff fragment.

func (Comparator) Compare

func (t Comparator) Compare(reference, value interface{})

Compare can be called by custom comparison functions to recurse into children.

func (Comparator) With

func (t Comparator) With(p Path) Comparator

With returns a new Comparator based on t but with the specified Path.

type Custom

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

Custom is a collection of custom comparators that will be used instead of the default comparison methods when comparing objects of the registered types.

func (*Custom) Compare

func (c *Custom) Compare(reference, value interface{}, handler Handler)

Compare delivers all the differences it finds to the specified Handler. Compare uses the list of custom comparison handlers registered with Custom.Register(), falling back to the default comparison method for the type when no custom comparison function has been registered with this custom. If the reference and value are equal, the handler will never be invoked.

func (*Custom) Diff

func (c *Custom) Diff(reference, value interface{}, limit int) []Path

Diff returns the differences between the reference and the value. Diff uses the list of custom comparison handlers registered with Custom.Register(), falling back to the default comparison method for the type when no custom comparison function has been registered with this custom. The maximum number of differences is controlled by limit, which must be >0. If they compare equal, the length of the returned slice will be 0.

func (*Custom) Register

func (c *Custom) Register(f interface{})

Register assigns the function f with signature func(comparator, T, T) to be used as the comparator for instances of type T when using Custom.Compare(). f may return nothing or a CompareAction. Register will panic if f does not match the expected signature, or if a comparator for type T has already been registered with this Custom.

type EntryOp

type EntryOp struct {
	Key interface{} // The map key
}

EntryOp is the fragment operation type for map entry comparisons.

func (EntryOp) Format

func (e EntryOp) Format(f fmt.State, r rune)

type Fragment

type Fragment struct {
	// Operation holds the operation occurring at this level in the path.
	Operation interface{}
	// Reference holds the entry in the reference hierarchy to apply the operation to
	Reference interface{}
	// Value holds the equivalent entry in the value hierarchy to apply the the operation to
	Value interface{}
}

Fragment is an entry in a Path

type Handler

type Handler func(Path)

Handler is the type for a callback that differences are delivered to. It may panic with LimitReached to abort further difference processing.

type Hidden

type Hidden struct {
	Value interface{}
}

Hidden is used when values are found to be different, but had hidden fields so cannot be directly returned

func (Hidden) Format

func (i Hidden) Format(f fmt.State, r rune)

type IndexOp

type IndexOp int

IndexOp is the fragment operation type for array / slice index comparisons.

func (IndexOp) Format

func (i IndexOp) Format(f fmt.State, r rune)

type LengthOp

type LengthOp string

LengthOp is the fragment operation type for array / slice length comparisons.

type MemberOp

type MemberOp string

MemberOp is the fragment operation type for member comparisons.

func (MemberOp) Format

func (m MemberOp) Format(f fmt.State, r rune)

type MissingOp

type MissingOp string

MissingOp is the fragment operation type for absent entries in arrays, slices and maps.

type NilOp

type NilOp string

NilOp is the fragment operation type for nil-equality comparisons.

type Path

type Path []Fragment

Path represents a path from the root of an object hierarchy

func Diff

func Diff(reference, value interface{}, limit int) []Path

Diff returns the differences between the reference and the value. The maximum number of differences is controlled by limit, which must be >0. If they compare equal, the length of the returned slice will be 0.

func (Path) Diff

func (p Path) Diff(reference, value interface{}) Path

Diff returns a new Path with a terminal diff fragment appended.

func (Path) Entry

func (p Path) Entry(key, reference, value interface{}) Path

Entry returns a new Path with a map entry fragment appended.

func (Path) Format

func (p Path) Format(f fmt.State, r rune)

func (Path) Index

func (p Path) Index(i int, reference, value interface{}) Path

Index returns a new Path with an array/slice index fragment appended.

func (Path) Length

func (p Path) Length(reference, value interface{}) Path

Length returns a new Path with a length query fragment appended.

func (Path) Member

func (p Path) Member(name string, reference, value interface{}) Path

Member returns a new Path with a member access fragment appended.

func (Path) Missing

func (p Path) Missing(reference, value interface{}) Path

Missing returns a new Path with a missing value fragment appended.

func (Path) Nil

func (p Path) Nil(reference, value interface{}) Path

Nil returns a new Path with a nil query fragment appended.

func (Path) Type

func (p Path) Type(reference, value interface{}) Path

Type returns a new Path with a type query fragment appended.

type TypeOp

type TypeOp string

TypeOp is the fragment operation type for type comparisons.