Add Options to prioritize some set of options over another

Added API:
	Continue() Option
	FilterPriority(opts ...Option) Option

FilterPriority returns a new Option where an option, opts[i],
is only evaluated if no fundamental options remain after applying all filters
in all prior options, opts[:i].

In order to prevent further options from being evaluated, the Continue option
can be used to ensure that some fundamental option remains.

Suppose you have a value tree T, where T1 and T2 are sub-trees within T.
Prior to the addition of FilterPriority, it was impossible to do certain things.

Example 1: You could not make the following compose together nicely.
	* Have a set of options OT1 to affect only values under T1.
	* Have a set of options OT2 to affect only values under T2.
	* Have a set of options OT to affect only T, but not values under T1 and T2.
	* Have a set of options O to affect all other values, but no those in T
	  (and by extension those in T1 and T2).
Solution 1:
	FilterPriority(
		// Since T1 and T2 do not overlap, they could be placed within the
		// same priority level by grouping them in an Options group.
		FilterTree(T1, OT1),
		FilterTree(T2, OT2),
		FilterTree(T, OT),
		O,
	)

Example 2: You could not make the following compose together nicely.
	* Have a set of options O apply on all nodes except those in T1 and T2.
	* Instead, we want the default behavior of cmp on T1 and T2.
Solution 2:
	FilterPriority(
		// Here we show how to group T1 and T2 together to be on the same
		// priority level.
		Options{
			FilterTree(T1, Continue()),
			FilterTree(T2, Continue()),
		},
		O,
	)

Example 3: You have this: type MyStruct struct { *pb.MyMessage; ... }
	* Generally, you want to use Comparer(proto.Equal) to ensure
	  that all proto.Messages within the struct are properly compared.
	  However, this type has an embedded proto (generally a bad idea),
	  which causes the MyStruct to satisfy the proto.Message interface
	  and unintentionally causes Equal to use proto.Equal on MyStruct,
	  which crashes.
	* How can you have Comparer(proto.Equal) apply to all other
	  proto.Message without applying just to MyStruct?
Solution 3:
	FilterPriority(
		// Only for MyStruct, use the default behavior of Equal,
		// which is to recurse into the structure of MyStruct.
		FilterPath(func(p Path) bool {
			return p.Last().Type() == reflect.TypeOf(MyStruct{})
		}, Continue()),

		// Use proto.Equal for all other cases of proto.Message.
		Comparer(proto.Equal),
	)

Author: dsnet

cmp/compare.go

@@ -49,8 +49,8 @@ var nothing = reflect.Value{}
 // • If two values are not of the same type, then they are never equal
 // and the overall result is false.
 //
-// • Let S be the set of all Ignore, Transformer, and Comparer options that
-// remain after applying all path filters, value filters, and type filters.
+// • Let S be the set of all Ignore, Transformer, Comparer, and Continue options
+// that remain after applying all implicit and explicit filters.
 // If at least one Ignore exists in S, then the comparison is ignored.
 // If the number of Transformer and Comparer options in S is greater than one,
 // then Equal panics because it is ambiguous which option to use.

cmp/options.go

@@ -14,11 +14,11 @@ import (
 )
 
 // Option configures for specific behavior of Equal and Diff. In particular,
-// the fundamental Option functions (Ignore, Transformer, and Comparer),
+// the fundamental options (Ignore, Transformer, Comparer, and Continue),
 // configure how equality is determined.
 //
-// The fundamental options may be composed with filters (FilterPath and
-// FilterValues) to control the scope over which they are applied.
+// The fundamental options may be composed with filters (FilterPath, FilterValues,
+// and FilterPriority) to control the scope over which they are applied.
 //
 // The cmp/cmpopts package provides helper functions for creating options that
 // may be used with Equal and Diff.
@@ -33,7 +33,7 @@ type Option interface {
 }
 
 // applicableOption represents the following types:
-//	Fundamental: ignore | invalid | *comparer | *transformer
+//	Fundamental: noop | ignore | invalid | *comparer | *transformer
 //	Grouping:    Options
 type applicableOption interface {
 	Option
@@ -44,7 +44,7 @@ type applicableOption interface {
 }
 
 // coreOption represents the following types:
-//	Fundamental: ignore | invalid | *comparer | *transformer
+//	Fundamental: noop | ignore | invalid | *comparer | *transformer
 //	Filters:     *pathFilter | *valuesFilter
 type coreOption interface {
 	Option
@@ -73,13 +73,17 @@ func (opts Options) filter(s *state, vx, vy reflect.Value, t reflect.Type) (out
 			out = invalid{} // Takes precedence over comparer or transformer
 		case *comparer, *transformer, Options:
 			switch out.(type) {
-			case nil:
+			case nil, noop:
 				out = opt
 			case invalid:
 				// Keep invalid
 			case *comparer, *transformer, Options:
 				out = Options{out, opt} // Conflicting comparers or transformers
 			}
+		case noop:
+			if out == nil {
+				out = noop{} // Takes lowest precedence
+			}
 		}
 	}
 	return out
@@ -107,8 +111,8 @@ func (opts Options) String() string {
 // FilterPath returns a new Option where opt is only evaluated if filter f
 // returns true for the current Path in the value tree.
 //
-// The option passed in may be an Ignore, Transformer, Comparer, Options, or
-// a previously filtered Option.
+// The option passed in may be an Ignore, Transformer, Comparer, Continue,
+// Options, or a previously filtered Option.
 func FilterPath(f func(Path) bool, opt Option) Option {
 	if f == nil {
 		panic("invalid path filter function")
@@ -148,8 +152,8 @@ func (f pathFilter) String() string {
 // If T is an interface, it is possible that f is called with two values with
 // different concrete types that both implement T.
 //
-// The option passed in may be an Ignore, Transformer, Comparer, Options, or
-// a previously filtered Option.
+// The option passed in may be an Ignore, Transformer, Comparer, Continue,
+// Options, or a previously filtered Option.
 func FilterValues(f interface{}, opt Option) Option {
 	v := reflect.ValueOf(f)
 	if !function.IsType(v.Type(), function.ValueFilter) || v.IsNil() {
@@ -187,6 +191,66 @@ func (f valuesFilter) String() string {
 	return fmt.Sprintf("FilterValues(%s, %v)", fn, f.opt)
 }
 
+// FilterPriority returns a new Option where an option, opts[i],
+// is only evaluated if no fundamental options remain after applying all filters
+// in all prior options, opts[:i].
+//
+// In order to prevent further options from being evaluated, the Continue option
+// can be used to ensure that some fundamental option remains.
+//
+// The options passed in may be an Ignore, Transformer, Comparer, Continue,
+// Options, or a previously filtered Option.
+func FilterPriority(opts ...Option) Option {
+	var newOpts []Option
+	for _, opt := range opts {
+		if opt := normalizeOption(opt); opt != nil {
+			newOpts = append(newOpts, opt)
+		}
+	}
+	if len(newOpts) > 0 {
+		return &priorityFilter{opts: newOpts}
+	}
+	return nil
+}
+
+type priorityFilter struct {
+	core
+	opts []Option
+}
+
+func (f priorityFilter) filter(s *state, vx, vy reflect.Value, t reflect.Type) applicableOption {
+	for _, opt := range f.opts {
+		if opt := opt.filter(s, vx, vy, t); opt != nil {
+			return opt
+		}
+	}
+	return nil
+}
+
+func (f priorityFilter) String() string {
+	var ss []string
+	for _, opt := range f.opts {
+		ss = append(ss, fmt.Sprint(opt))
+	}
+	return fmt.Sprintf("FilterPriority(%s)", strings.Join(ss, ", "))
+}
+
+// Continue is an Option that is intended to be combined with FilterPriority
+// and acts as a sentinel type that if applicable can prevent later options
+// from evaluating.
+//
+// Evaluating a Continue is a noop. Other than affecting the evaluation
+// of FilterPriority, its presence has no effect on Equal.
+// If any Ignore, Comparer, or Transformer options are also applicable,
+// they always take precedence over Continue.
+func Continue() Option { return noop{} }
+
+type noop struct{ core }
+
+func (noop) filter(_ *state, _, _ reflect.Value, _ reflect.Type) applicableOption { return noop{} }
+func (noop) apply(_ *state, _, _ reflect.Value) bool                              { return false }
+func (noop) String() string                                                       { return "Continue()" }
+
 // Ignore is an Option that causes all comparisons to be ignored.
 // This value is intended to be combined with FilterPath or FilterValues.
 // It is an error to pass an unfiltered Ignore option to Equal.