fieldpath

package
v4.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 11, 2024 License: Apache-2.0 Imports: 11 Imported by: 203

Documentation

Overview

Package fieldpath defines a way for referencing path elements (e.g., an index in an array, or a key in a map). It provides types for arranging these into paths for referencing nested fields, and for grouping those into sets, for referencing multiple nested fields.

Index

Constants

This section is empty.

Variables

View Source 
var AssociativeListCandidateFieldNames = []string{
	"key",
	"id",
	"name",
}

AssociativeListCandidateFieldNames lists the field names which are considered keys if found in a list element.

View Source 
var ErrUnknownPathElementType = errors.New("unknown path element type")

Functions

func KeyByFields 

func KeyByFields(nameValues ...interface{}) *value.FieldList

KeyByFields is a helper function which constructs a key for an associative list type. `nameValues` must have an even number of entries, alternating names (type must be string) with values (type must be value.Value). If these conditions are not met, KeyByFields will panic--it's intended for static construction and shouldn't have user-produced values passed to it.

func NewExcludeFilterSetMap added in v4.4.2 

func NewExcludeFilterSetMap(resetFields map[APIVersion]*Set) map[APIVersion]Filter

NewExcludeFilterSetMap converts a map of APIVersion to exclude set to a map of APIVersion to exclude filters.

func SerializePathElement 

func SerializePathElement(pe PathElement) (string, error)

SerializePathElement serializes a path element

Types

type APIVersion 

type APIVersion string

APIVersion describes the version of an object or of a fieldset.

type Filter added in v4.4.2 

type Filter interface {
	// Filter returns a filtered copy of the set.
	Filter(*Set) *Set
}

Filter defines an interface for excluding field paths from a set. NewExcludeSetFilter can be used to create a filter that removes specific field paths and all of their children. NewIncludeMatcherFilter can be used to create a filter that removes all fields except the fields that match a field path matcher. PrefixMatcher and MakePrefixMatcherOrDie can be used to define field path patterns.

func NewExcludeSetFilter added in v4.4.2 

func NewExcludeSetFilter(exclude *Set) Filter

NewExcludeSetFilter returns a filter that removes field paths in the exclude set.

func NewIncludeMatcherFilter added in v4.4.2 

func NewIncludeMatcherFilter(matchers ...*SetMatcher) Filter

NewIncludeMatcherFilter returns a filter that only includes field paths that match. If no matchers are provided, the filter includes all field paths. PrefixMatcher and MakePrefixMatcherOrDie can help create basic matcher.

type ManagedFields 

type ManagedFields map[string]VersionedSet

ManagedFields is a map from manager to VersionedSet (what they own in what version).

func (ManagedFields) Copy 

func (lhs ManagedFields) Copy() ManagedFields

Copy the list, this is mostly a shallow copy.

func (ManagedFields) Difference 

func (lhs ManagedFields) Difference(rhs ManagedFields) ManagedFields

Difference returns a symmetric difference between two Managers. If a given user's entry has version X in lhs and version Y in rhs, then the return value for that user will be from rhs. If the difference for a user is an empty set, that user will not be inserted in the map.

func (ManagedFields) Equals 

func (lhs ManagedFields) Equals(rhs ManagedFields) bool

Equals returns true if the two managedfields are the same, false otherwise.

func (ManagedFields) String 

func (lhs ManagedFields) String() string

type Path 

type Path []PathElement

Path describes how to select a potentially deeply-nested child field given a containing object.

func MakePath 

func MakePath(parts ...interface{}) (Path, error)

MakePath constructs a Path. The parts may be PathElements, ints, strings.

func MakePathOrDie 

func MakePathOrDie(parts ...interface{}) Path

MakePathOrDie panics if parts can't be turned into a path. Good for things that are known at complie time.

func (Path) Compare 

func (fp Path) Compare(rhs Path) int

Less provides a lexical order for Paths.

func (Path) Copy 

func (fp Path) Copy() Path

func (Path) Equals 

func (fp Path) Equals(fp2 Path) bool

Equals returns true if the two paths are equivalent.

func (Path) String 

func (fp Path) String() string

type PathElement 

type PathElement struct {

	// FieldName selects a single field from a map (reminder: this is also
	// how structs are represented). The containing object must be a map.
	FieldName *string

	// Key selects the list element which has fields matching those given.
	// The containing object must be an associative list with map typed
	// elements. They are sorted alphabetically.
	Key *value.FieldList

	// Value selects the list element with the given value. The containing
	// object must be an associative list with a primitive typed element
	// (i.e., a set).
	Value *value.Value

	// Index selects a list element by its index number. The containing
	// object must be an atomic list.
	Index *int
}

PathElement describes how to select a child field given a containing object.

func DeserializePathElement 

func DeserializePathElement(s string) (PathElement, error)

DeserializePathElement parses a serialized path element

func (PathElement) Compare 

func (e PathElement) Compare(rhs PathElement) int

Compare provides an order for path elements.

func (PathElement) Equals 

func (e PathElement) Equals(rhs PathElement) bool

Equals returns true if both path elements are equal.

func (PathElement) Less 

func (e PathElement) Less(rhs PathElement) bool

Less provides an order for path elements.

func (PathElement) String 

func (e PathElement) String() string

String presents the path element as a human-readable string.

type PathElementMap added in v4.4.0 

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

PathElementValueMap is a map from PathElement to interface{}.

func MakePathElementMap added in v4.4.0 

func MakePathElementMap(size int) PathElementMap

func (*PathElementMap) Get added in v4.4.0 

func (s *PathElementMap) Get(pe PathElement) (interface{}, bool)

Get retrieves the value associated with the given PathElement from the map. (nil, false) is returned if there is no such PathElement.

func (*PathElementMap) Insert added in v4.4.0 

func (s *PathElementMap) Insert(pe PathElement, v interface{})

Insert adds the pathelement and associated value in the map. If insert is called twice with the same PathElement, the value is replaced.

type PathElementMatcher added in v4.4.2 

type PathElementMatcher struct {
	// Wildcard indicates that all PathElements are matched by this matcher.
	// If set, PathElement is ignored.
	Wildcard bool

	// PathElement indicates that a PathElement is matched if it is Equal
	// to this PathElement.
	PathElement
}

PathElementMatcher defined a path matcher for a PathElement.

func MatchAnyPathElement added in v4.4.2 

func MatchAnyPathElement() PathElementMatcher

MatchAnyPathElement returns a PathElementMatcher that matches any path element.

func (PathElementMatcher) Compare added in v4.4.2 

func (p PathElementMatcher) Compare(p2 PathElementMatcher) int

func (PathElementMatcher) Equals added in v4.4.2 

func (p PathElementMatcher) Equals(p2 PathElementMatcher) bool

func (PathElementMatcher) Less added in v4.4.2 

func (p PathElementMatcher) Less(p2 PathElementMatcher) bool

type PathElementSet 

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

PathElementSet is a set of path elements. TODO: serialize as a list.

func MakePathElementSet 

func MakePathElementSet(size int) PathElementSet

func (*PathElementSet) Difference 

func (s *PathElementSet) Difference(s2 *PathElementSet) *PathElementSet

Difference returns a set containing elements which appear in s but not in s2.

func (*PathElementSet) Equals 

func (s *PathElementSet) Equals(s2 *PathElementSet) bool

Equals returns true if s and s2 have exactly the same members.

func (*PathElementSet) Has 

func (s *PathElementSet) Has(pe PathElement) bool

Has returns true if pe is a member of the set.

func (*PathElementSet) Insert 

func (s *PathElementSet) Insert(pe PathElement)

Insert adds pe to the set.

func (*PathElementSet) Intersection 

func (s *PathElementSet) Intersection(s2 *PathElementSet) *PathElementSet

Intersection returns a set containing elements which appear in both s and s2.

func (*PathElementSet) Iterate 

func (s *PathElementSet) Iterate(f func(PathElement))

Iterate calls f for each PathElement in the set. The order is deterministic.

func (*PathElementSet) Size 

func (s *PathElementSet) Size() int

Size retuns the number of elements in the set.

func (*PathElementSet) Union 

func (s *PathElementSet) Union(s2 *PathElementSet) *PathElementSet

Union returns a set containing elements that appear in either s or s2.

type PathElementValueMap 

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

PathElementValueMap is a map from PathElement to value.Value.

TODO(apelisse): We have multiple very similar implementation of this for PathElementSet and SetNodeMap, so we could probably share the code.

func MakePathElementValueMap 

func MakePathElementValueMap(size int) PathElementValueMap

func (*PathElementValueMap) Get 

func (s *PathElementValueMap) Get(pe PathElement) (value.Value, bool)

Get retrieves the value associated with the given PathElement from the map. (nil, false) is returned if there is no such PathElement.

func (*PathElementValueMap) Insert 

func (s *PathElementValueMap) Insert(pe PathElement, v value.Value)

Insert adds the pathelement and associated value in the map. If insert is called twice with the same PathElement, the value is replaced.

type Set 

type Set struct {
	// Members lists fields that are part of the set.
	// TODO: will be serialized as a list of path elements.
	Members PathElementSet

	// Children lists child fields which themselves have children that are
	// members of the set. Appearance in this list does not imply membership.
	// Note: this is a tree, not an arbitrary graph.
	Children SetNodeMap
}

Set identifies a set of fields.

func NewSet 

func NewSet(paths ...Path) *Set

NewSet makes a set from a list of paths.

func SetFromValue 

func SetFromValue(v value.Value) *Set

SetFromValue creates a set containing every leaf field mentioned in v.

func (*Set) Difference 

func (s *Set) Difference(s2 *Set) *Set

Difference returns a Set containing elements which: * appear in s * do not appear in s2

In other words, for leaf fields, this acts like a regular set difference operation. When non leaf fields are compared with leaf fields ("parents" which contain "children"), the effect is: * parent - child = parent * child - parent = {empty set}

func (*Set) Empty 

func (s *Set) Empty() bool

Empty returns true if there are no members of the set. It is a separate function from Size since it's common to check whether size > 0, and potentially much faster to return as soon as a single element is found.

func (*Set) EnsureNamedFieldsAreMembers added in v4.0.3 

func (s *Set) EnsureNamedFieldsAreMembers(sc *schema.Schema, tr schema.TypeRef) *Set

EnsureNamedFieldsAreMembers returns a Set that contains all the fields in s, as well as all the named fields that are typically not included. For example, a set made of "a.b.c" will end-up also owning "a" if it's a named fields but not "a.b" if it's a map.

func (*Set) Equals 

func (s *Set) Equals(s2 *Set) bool

Equals returns true if s and s2 have exactly the same members.

func (*Set) FilterIncludeMatches added in v4.4.2 

func (s *Set) FilterIncludeMatches(pattern *SetMatcher) *Set

FilterIncludeMatches returns a Set with only the field paths that match.

func (*Set) FromJSON 

func (s *Set) FromJSON(r io.Reader) error

FromJSON clears s and reads a JSON formatted set structure.

func (*Set) Has 

func (s *Set) Has(p Path) bool

Has returns true if the field referenced by `p` is a member of the set.

func (*Set) Insert 

func (s *Set) Insert(p Path)

Insert adds the field identified by `p` to the set. Important: parent fields are NOT added to the set; if that is desired, they must be added separately.

func (*Set) Intersection 

func (s *Set) Intersection(s2 *Set) *Set

Intersection returns a Set containing leaf elements which appear in both s and s2. Intersection can be constructed from Union and Difference operations (example in the tests) but it's much faster to do it in one pass.

func (*Set) Iterate 

func (s *Set) Iterate(f func(Path))

Iterate calls f once for each field that is a member of the set (preorder DFS). The path passed to f will be reused so make a copy if you wish to keep it.

func (*Set) Leaves added in v4.1.0 

func (s *Set) Leaves() *Set

Leaves returns a set containing only the leaf paths of a set.

func (*Set) RecursiveDifference 

func (s *Set) RecursiveDifference(s2 *Set) *Set

RecursiveDifference returns a Set containing elements which: * appear in s * do not appear in s2

Compared to a regular difference, this removes every field **and its children** from s that is contained in s2.

For example, with s containing `a.b.c` and s2 containing `a.b`, a RecursiveDifference will result in `a`, as the entire node `a.b` gets removed.

func (*Set) Size 

func (s *Set) Size() int

Size returns the number of members of the set.

func (*Set) String 

func (s *Set) String() string

String returns the set one element per line.

func (*Set) ToJSON 

func (s *Set) ToJSON() ([]byte, error)

func (*Set) ToJSONStream 

func (s *Set) ToJSONStream(w io.Writer) error

func (*Set) Union 

func (s *Set) Union(s2 *Set) *Set

Union returns a Set containing elements which appear in either s or s2.

func (*Set) WithPrefix 

func (s *Set) WithPrefix(pe PathElement) *Set

WithPrefix returns the subset of paths which begin with the given prefix, with the prefix not included.

type SetMatcher added in v4.4.2 

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

SetMatcher defines a matcher that matches fields in a Set. SetMatcher is structured much like a Set but with wildcard support.

func MakePrefixMatcherOrDie added in v4.4.2 

func MakePrefixMatcherOrDie(parts ...interface{}) *SetMatcher

MakePrefixMatcherOrDie is the same as PrefixMatcher except it panics if parts can't be turned into a SetMatcher.

func MatchAnySet added in v4.4.2 

func MatchAnySet() *SetMatcher

MatchAnySet returns a SetMatcher that matches any set.

func NewSetMatcher added in v4.4.2 

func NewSetMatcher(wildcard bool, members ...*SetMemberMatcher) *SetMatcher

NewSetMatcher returns a new SetMatcher. Wildcard members take precedent over non-wildcard members; all non-wildcard members are ignored if there is a wildcard members.

func PrefixMatcher added in v4.4.2 

func PrefixMatcher(parts ...interface{}) (*SetMatcher, error)

PrefixMatcher creates a SetMatcher that matches all field paths prefixed by the given list of matcher path parts. The matcher parts may any of:

  • PathElementMatcher - for wildcards, `MatchAnyPathElement()` can be used as well.
  • PathElement - for any path element
  • value.FieldList - for listMap keys
  • value.Value - for scalar list elements
  • string - For field names
  • int - for array indices

func (*SetMatcher) Merge added in v4.4.2 

func (s *SetMatcher) Merge(s2 *SetMatcher) *SetMatcher

Merge merges s and s2 and returns a SetMatcher that matches all field paths matched by either s or s2. During the merge, members of s and s2 with the same PathElementMatcher merged into a single member with the children of each merged by calling this function recursively.

type SetMemberMatcher added in v4.4.2 

type SetMemberMatcher struct {
	// Path provides a matcher to match members of a Set.
	// If Path is a wildcard, all members of a Set are included in the match.
	// Otherwise, if any Path is Equal to a member of a Set, that member is
	// included in the match and the children of that member are matched
	// against the Child matcher.
	Path PathElementMatcher

	// Child provides a matcher to use for the children of matched members of a Set.
	Child *SetMatcher
}

SetMemberMatcher defines a matcher that matches the members of a Set. SetMemberMatcher is structured much like the elements of a SetNodeMap, but with wildcard support.

type SetNodeMap 

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

SetNodeMap is a map of PathElement to subset.

func (*SetNodeMap) Descend 

func (s *SetNodeMap) Descend(pe PathElement) *Set

Descend adds pe to the set if necessary, returning the associated subset.

func (*SetNodeMap) Difference 

func (s *SetNodeMap) Difference(s2 *Set) *SetNodeMap

Difference returns a SetNodeMap with members that appear in s but not in s2.

func (*SetNodeMap) Empty 

func (s *SetNodeMap) Empty() bool

Empty returns false if there's at least one member in some child set.

func (*SetNodeMap) EnsureNamedFieldsAreMembers added in v4.0.3 

func (s *SetNodeMap) EnsureNamedFieldsAreMembers(sc *schema.Schema, tr schema.TypeRef) *SetNodeMap

EnsureNamedFieldsAreMembers returns a set that contains all the named fields along with the leaves.

func (*SetNodeMap) Equals 

func (s *SetNodeMap) Equals(s2 *SetNodeMap) bool

Equals returns true if s and s2 have the same structure (same nested child sets).

func (*SetNodeMap) FilterIncludeMatches added in v4.4.2 

func (s *SetNodeMap) FilterIncludeMatches(pattern *SetMatcher) *SetNodeMap

FilterIncludeMatches returns a SetNodeMap with only the field paths that match the matcher.

func (*SetNodeMap) Get 

func (s *SetNodeMap) Get(pe PathElement) (*Set, bool)

Get returns (the associated set, true) or (nil, false) if there is none.

func (*SetNodeMap) Intersection 

func (s *SetNodeMap) Intersection(s2 *SetNodeMap) *SetNodeMap

Intersection returns a SetNodeMap with members that appear in both s and s2.

func (*SetNodeMap) Iterate 

func (s *SetNodeMap) Iterate(f func(PathElement))

Iterate calls f for each PathElement in the set.

func (*SetNodeMap) Leaves added in v4.1.0 

func (s *SetNodeMap) Leaves() *SetNodeMap

Leaves returns a SetNodeMap containing only setNodes with leaf PathElements.

func (*SetNodeMap) RecursiveDifference 

func (s *SetNodeMap) RecursiveDifference(s2 *Set) *SetNodeMap

RecursiveDifference returns a SetNodeMap with members that appear in s but not in s2.

Compared to a regular difference, this removes every field **and its children** from s that is contained in s2.

For example, with s containing `a.b.c` and s2 containing `a.b`, a RecursiveDifference will result in `a`, as the entire node `a.b` gets removed.

func (*SetNodeMap) Size 

func (s *SetNodeMap) Size() int

Size returns the sum of the number of members of all subsets.

func (*SetNodeMap) Union 

func (s *SetNodeMap) Union(s2 *SetNodeMap) *SetNodeMap

Union returns a SetNodeMap with members that appear in either s or s2.

type VersionedSet 

type VersionedSet interface {
	Set() *Set
	APIVersion() APIVersion
	Applied() bool
}

func NewVersionedSet 

func NewVersionedSet(set *Set, apiVersion APIVersion, applied bool) VersionedSet

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.