var (
// Break breaks traversal of children in the current value.
// It has no effect when traversing values that are not composite types
// (e.g., messages, lists, and maps).
Break = errors.New("break traversal of children in current value")
// Terminate terminates the entire range operation.
// All necessary Pop operations continue to be called.
Terminate = errors.New("terminate range operation")
)
func Range(m protoreflect.Message, f func(protopath.Values) error) error
Range performs a depth-first traversal over reachable values in a message.
See Options.Range for details.
Options configures traversal of a message value tree.
type Options struct {
// Stable specifies whether to visit message fields and map entries
// in a stable ordering. If false, then the ordering is undefined and
// may be non-deterministic.
//
// Message fields are visited in ascending order by field number.
// Map entries are visited in ascending order, where
// boolean keys are ordered such that false sorts before true,
// numeric keys are ordered based on the numeric value, and
// string keys are lexicographically ordered by Unicode codepoints.
Stable bool
// Resolver is used for looking up types when expanding google.protobuf.Any
// messages. If nil, this defaults to using protoregistry.GlobalTypes.
// To prevent expansion of Any messages, pass an empty protoregistry.Types:
//
// Options{Resolver: (*protoregistry.Types)(nil)}
//
Resolver interface {
protoregistry.ExtensionTypeResolver
protoregistry.MessageTypeResolver
}
}
func (o Options) Range(m protoreflect.Message, push, pop func(protopath.Values) error) error
Range performs a depth-first traversal over reachable values in a message. The first push and the last pop are to push/pop a protopath.Root step. If push or pop return any non-nil error (other than Break or Terminate), it terminates the traversal and is returned by Range.
The rules for traversing a message is as follows:
For messages, iterate over every populated known and extension field. Each field is preceded by a push of a protopath.FieldAccess step, followed by recursive application of the rules on the field value, and succeeded by a pop of that step. If the message has unknown fields, then push an protopath.UnknownAccess step followed immediately by pop of that step.
As an exception to the above rule, if the current message is a google.protobuf.Any message, expand the underlying message (if resolvable). The expanded message is preceded by a push of a protopath.AnyExpand step, followed by recursive application of the rules on the underlying message, and succeeded by a pop of that step. Mutations to the expanded message are written back to the Any message when popping back out.
For lists, iterate over every element. Each element is preceded by a push of a protopath.ListIndex step, followed by recursive application of the rules on the list element, and succeeded by a pop of that step.
For maps, iterate over every entry. Each entry is preceded by a push of a protopath.MapIndex step, followed by recursive application of the rules on the map entry value, and succeeded by a pop of that step.
Mutations should only be made to the last value, otherwise the effects on traversal will be undefined. If the mutation is made to the last value during to a push, then the effects of the mutation will affect traversal. For example, if the last value is currently a message, and the push function populates a few fields in that message, then the newly modified fields will be traversed.
The protopath.Values provided to push functions is only valid until the corresponding pop call and the values provided to a pop call is only valid for the duration of the pop call itself.