selector

package
v0.21.0 Latest Latest
Warning

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

 Go to latest Published: Aug 10, 2023 License: MIT Imports: 6 Imported by: 117

Documentation

Index

Constants

View Source 
const (
	SelectorKey_Matcher              = "."
	SelectorKey_ExploreAll           = "a"
	SelectorKey_ExploreFields        = "f"
	SelectorKey_ExploreIndex         = "i"
	SelectorKey_ExploreRange         = "r"
	SelectorKey_ExploreRecursive     = "R"
	SelectorKey_ExploreUnion         = "|"
	SelectorKey_ExploreConditional   = "&"
	SelectorKey_ExploreRecursiveEdge = "@"
	SelectorKey_ExploreInterpretAs   = "~"
	SelectorKey_Next                 = ">"
	SelectorKey_Fields               = "f>"
	SelectorKey_Index                = "i"
	SelectorKey_Start                = "^"
	SelectorKey_End                  = "$"
	SelectorKey_Sequence             = ":>"
	SelectorKey_Limit                = "l"
	SelectorKey_LimitDepth           = "depth"
	SelectorKey_LimitNone            = "none"
	SelectorKey_StopAt               = "!"
	SelectorKey_Condition            = "&"
	SelectorKey_As                   = "as"
	SelectorKey_Subset               = "subset"
	SelectorKey_From                 = "["
	SelectorKey_To                   = "]"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Condition added in v0.11.0 

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

Condition provides a mechanism for matching and limiting matching and exploration of selectors. Not all types of conditions which are imagined in the selector specification are encoded at present, instead we currently only implement a subset that is sufficient for initial pressing use cases.

func (*Condition) Match added in v0.11.0 

func (c *Condition) Match(n datamodel.Node) bool

Match decides if a given datamodel.Node matches the condition.

type ConditionMode added in v0.11.0 

type ConditionMode string

A ConditionMode is the keyed representation for the union that is the condition 

const (
	ConditionMode_Link ConditionMode = "/"
)

type ExploreAll 

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

ExploreAll is similar to a `*` -- it traverses all elements of an array, or all entries in a map, and applies a next selector to the reached nodes.

func (ExploreAll) Decide 

func (s ExploreAll) Decide(n datamodel.Node) bool

Decide always returns false because this is not a matcher

func (ExploreAll) Explore 

func (s ExploreAll) Explore(n datamodel.Node, p datamodel.PathSegment) (Selector, error)

Explore returns the node's selector for all fields

func (ExploreAll) Interests 

func (s ExploreAll) Interests() []datamodel.PathSegment

Interests for ExploreAll is nil (meaning traverse everything)

func (ExploreAll) Match added in v0.16.0 

func (s ExploreAll) Match(node datamodel.Node) (datamodel.Node, error)

Match always returns false because this is not a matcher

type ExploreFields 

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

ExploreFields traverses named fields in a map (or equivalently, struct, if traversing on typed/schema nodes) and applies a next selector to the reached nodes.

Note that a concept of "ExplorePath" (e.g. "foo/bar/baz") can be represented as a set of three nexted ExploreFields selectors, each specifying one field. (For this reason, we don't have a special "ExplorePath" feature; use this.)

ExploreFields also works for selecting specific elements out of a list; if a "field" is a base-10 int, it will be coerced and do the right thing. ExploreIndex or ExploreRange is more appropriate, however, and should be preferred.

func (ExploreFields) Decide 

func (s ExploreFields) Decide(n datamodel.Node) bool

Decide always returns false because this is not a matcher

func (ExploreFields) Explore 

func (s ExploreFields) Explore(n datamodel.Node, p datamodel.PathSegment) (Selector, error)

Explore returns the selector for the given path if it is a field in the selector node or nil if not

func (ExploreFields) Interests 

func (s ExploreFields) Interests() []datamodel.PathSegment

Interests for ExploreFields are the fields listed in the selector node

func (ExploreFields) Match added in v0.16.0 

func (s ExploreFields) Match(node datamodel.Node) (datamodel.Node, error)

Match always returns false because this is not a matcher

type ExploreIndex 

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

ExploreIndex traverses a specific index in a list, and applies a next selector to the reached node.

func (ExploreIndex) Decide 

func (s ExploreIndex) Decide(n datamodel.Node) bool

Decide always returns false because this is not a matcher

func (ExploreIndex) Explore 

func (s ExploreIndex) Explore(n datamodel.Node, p datamodel.PathSegment) (Selector, error)

Explore returns the node's selector if the path matches the index for this selector or nil if not

func (ExploreIndex) Interests 

func (s ExploreIndex) Interests() []datamodel.PathSegment

Interests for ExploreIndex is just the index specified by the selector node

func (ExploreIndex) Match added in v0.16.0 

func (s ExploreIndex) Match(node datamodel.Node) (datamodel.Node, error)

Match always returns false because this is not a matcher

type ExploreInterpretAs added in v0.14.4 

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

func (ExploreInterpretAs) Decide added in v0.14.4 

func (s ExploreInterpretAs) Decide(n datamodel.Node) bool

Decide always returns false because this is not a matcher

func (ExploreInterpretAs) Explore added in v0.14.4 

func (s ExploreInterpretAs) Explore(n datamodel.Node, p datamodel.PathSegment) (Selector, error)

Explore returns the node's selector if the path matches the index for this selector or nil if not

func (ExploreInterpretAs) Interests added in v0.14.4 

func (s ExploreInterpretAs) Interests() []datamodel.PathSegment

Interests for ExploreIndex is just the index specified by the selector node

func (ExploreInterpretAs) Match added in v0.16.0 

func (s ExploreInterpretAs) Match(node datamodel.Node) (datamodel.Node, error)

Match always returns false because this is not a matcher

func (ExploreInterpretAs) NamedReifier added in v0.14.4 

func (s ExploreInterpretAs) NamedReifier() string

NamedReifier indicates how this selector expects to Reify the current datamodel.Node.

type ExploreRange 

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

ExploreRange traverses a list, and for each element in the range specified, will apply a next selector to those reached nodes.

func (ExploreRange) Decide 

func (s ExploreRange) Decide(n datamodel.Node) bool

Decide always returns false because this is not a matcher

func (ExploreRange) Explore 

func (s ExploreRange) Explore(n datamodel.Node, p datamodel.PathSegment) (Selector, error)

Explore returns the node's selector if the path matches an index in the range of this selector

func (ExploreRange) Interests 

func (s ExploreRange) Interests() []datamodel.PathSegment

Interests for ExploreRange are all path segments within the iteration range

func (ExploreRange) Match added in v0.16.0 

func (s ExploreRange) Match(node datamodel.Node) (datamodel.Node, error)

Match always returns false because this is not a matcher

type ExploreRecursive 

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

ExploreRecursive traverses some structure recursively. To guide this exploration, it uses a "sequence", which is another Selector tree; some leaf node in this sequence should contain an ExploreRecursiveEdge selector, which denotes the place recursion should occur.

In implementation, whenever evaluation reaches an ExploreRecursiveEdge marker in the recursion sequence's Selector tree, the implementation logically produces another new Selector which is a copy of the original ExploreRecursive selector, but with a decremented maxDepth parameter, and continues evaluation thusly.

It is not valid for an ExploreRecursive selector's sequence to contain no instances of ExploreRecursiveEdge; it *is* valid for it to contain more than one ExploreRecursiveEdge.

ExploreRecursive can contain a nested ExploreRecursive! This is comparable to a nested for-loop. In these cases, any ExploreRecursiveEdge instance always refers to the nearest parent ExploreRecursive (in other words, ExploreRecursiveEdge can be thought of like the 'continue' statement, or end of a for-loop body; it is *not* a 'goto' statement).

Be careful when using ExploreRecursive with a large maxDepth parameter; it can easily cause very large traversals (especially if used in combination with selectors like ExploreAll inside the sequence).

func (ExploreRecursive) Decide 

func (s ExploreRecursive) Decide(n datamodel.Node) bool

Decide if a node directly matches

func (ExploreRecursive) Explore 

func (s ExploreRecursive) Explore(n datamodel.Node, p datamodel.PathSegment) (Selector, error)

Explore returns the node's selector for all fields

func (ExploreRecursive) Interests 

func (s ExploreRecursive) Interests() []datamodel.PathSegment

Interests for ExploreRecursive is empty (meaning traverse everything)

func (ExploreRecursive) Match added in v0.16.0 

func (s ExploreRecursive) Match(node datamodel.Node) (datamodel.Node, error)

Match always returns false because this is not a matcher

type ExploreRecursiveEdge 

type ExploreRecursiveEdge struct{}

ExploreRecursiveEdge is a special sentinel value which is used to mark the end of a sequence started by an ExploreRecursive selector: the recursion goes back to the initial state of the earlier ExploreRecursive selector, and proceeds again (with a decremented maxDepth value).

An ExploreRecursive selector that doesn't contain an ExploreRecursiveEdge is nonsensical. Containing more than one ExploreRecursiveEdge is valid. An ExploreRecursiveEdge without an enclosing ExploreRecursive is an error.

func (ExploreRecursiveEdge) Decide 

func (s ExploreRecursiveEdge) Decide(n datamodel.Node) bool

Decide should almost never get called for an ExploreRecursiveEdge selector

func (ExploreRecursiveEdge) Explore 

func (s ExploreRecursiveEdge) Explore(n datamodel.Node, p datamodel.PathSegment) (Selector, error)

Explore should ultimately never get called for an ExploreRecursiveEdge selector

func (ExploreRecursiveEdge) Interests 

func (s ExploreRecursiveEdge) Interests() []datamodel.PathSegment

Interests should almost never get called for an ExploreRecursiveEdge selector

func (ExploreRecursiveEdge) Match added in v0.16.0 

func (s ExploreRecursiveEdge) Match(node datamodel.Node) (datamodel.Node, error)

Match always returns false because this is not a matcher

type ExploreUnion 

type ExploreUnion struct {
	Members []Selector
}

ExploreUnion allows selection to continue with two or more distinct selectors while exploring the same tree of data.

ExploreUnion can be used to apply a Matcher on one node (causing it to be considered part of a (possibly labelled) result set), while simultaneously continuing to explore deeper parts of the tree with another selector, for example.

func (ExploreUnion) Decide 

func (s ExploreUnion) Decide(n datamodel.Node) bool

Decide returns true for a Union selector if any of the member selectors return true

func (ExploreUnion) Explore 

func (s ExploreUnion) Explore(n datamodel.Node, p datamodel.PathSegment) (Selector, error)

Explore for a Union selector calls explore for each member selector and returns: - a new union selector if more than one member returns a selector - if exactly one member returns a selector, that selector - nil if no members return a selector

func (ExploreUnion) Interests 

func (s ExploreUnion) Interests() []datamodel.PathSegment

Interests for ExploreUnion is: - nil (aka all) if any member selector has nil interests - the union of values returned by all member selectors otherwise

func (ExploreUnion) Match added in v0.16.0 

func (s ExploreUnion) Match(n datamodel.Node) (datamodel.Node, error)

Match returns true for a Union selector based on the matched union.

type Matcher 

type Matcher struct {
	*Slice
}

Matcher marks a node to be included in the "result" set. (All nodes traversed by a selector are in the "covered" set (which is a.k.a. "the merkle proof"); the "result" set is a subset of the "covered" set.)

In libraries using selectors, the "result" set is typically provided to some user-specified callback.

A selector tree with only "explore*"-type selectors and no Matcher selectors is valid; it will just generate a "covered" set of nodes and no "result" set. TODO: From spec: implement conditions and labels

func (Matcher) Decide 

func (s Matcher) Decide(n datamodel.Node) bool

Decide is always true for a match cause it's in the result set Deprecated: use Match instead

func (Matcher) Explore 

func (s Matcher) Explore(n datamodel.Node, p datamodel.PathSegment) (Selector, error)

Explore will return nil because a matcher is a terminal selector

func (Matcher) Interests 

func (s Matcher) Interests() []datamodel.PathSegment

Interests are empty for a matcher (for now) because It is always just there to match, not explore further

func (Matcher) Match added in v0.16.0 

func (s Matcher) Match(node datamodel.Node) (datamodel.Node, error)

Match is always true for a match cause it's in the result set

type ParseContext 

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

ParseContext tracks the progress when parsing a selector

func (ParseContext) ParseCondition added in v0.11.0 

func (pc ParseContext) ParseCondition(n datamodel.Node) (Condition, error)

ParseCondition assembles a Condition from a condition selector node

func (ParseContext) ParseExploreAll 

func (pc ParseContext) ParseExploreAll(n datamodel.Node) (Selector, error)

ParseExploreAll assembles a Selector from a ExploreAll selector node

func (ParseContext) ParseExploreFields 

func (pc ParseContext) ParseExploreFields(n datamodel.Node) (Selector, error)

ParseExploreFields assembles a Selector from a ExploreFields selector node

func (ParseContext) ParseExploreIndex 

func (pc ParseContext) ParseExploreIndex(n datamodel.Node) (Selector, error)

ParseExploreIndex assembles a Selector from a ExploreIndex selector node

func (ParseContext) ParseExploreInterpretAs added in v0.14.4 

func (pc ParseContext) ParseExploreInterpretAs(n datamodel.Node) (Selector, error)

ParseExploreInterpretAs assembles a Selector from a ExploreInterpretAs selector node

func (ParseContext) ParseExploreRange 

func (pc ParseContext) ParseExploreRange(n datamodel.Node) (Selector, error)

ParseExploreRange assembles a Selector from a ExploreRange selector node

func (ParseContext) ParseExploreRecursive 

func (pc ParseContext) ParseExploreRecursive(n datamodel.Node) (Selector, error)

ParseExploreRecursive assembles a Selector from a ExploreRecursive selector node

func (ParseContext) ParseExploreRecursiveEdge 

func (pc ParseContext) ParseExploreRecursiveEdge(n datamodel.Node) (Selector, error)

ParseExploreRecursiveEdge assembles a Selector from a exploreRecursiveEdge selector node

func (ParseContext) ParseExploreUnion 

func (pc ParseContext) ParseExploreUnion(n datamodel.Node) (Selector, error)

ParseExploreUnion assembles a Selector from an ExploreUnion selector node

func (ParseContext) ParseMatcher 

func (pc ParseContext) ParseMatcher(n datamodel.Node) (Selector, error)

ParseMatcher assembles a Selector from a matcher selector node TODO: Parse labels and conditions

func (ParseContext) ParseSelector 

func (pc ParseContext) ParseSelector(n datamodel.Node) (Selector, error)

ParseSelector creates a Selector from an IPLD Selector Node with the given context

func (ParseContext) PushParent 

func (pc ParseContext) PushParent(parent ParsedParent) ParseContext

PushParent puts a parent onto the stack of parents for a parse context

type ParsedParent 

type ParsedParent interface {
	Link(s Selector) bool
}

ParsedParent is created whenever you are parsing a selector node that may have child selectors nodes that need to know it

type RecursionLimit added in v0.0.2 

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

RecursionLimit is a union type that captures all data about the recursion limit (both its type and data specific to the type)

func RecursionLimitDepth added in v0.0.2 

func RecursionLimitDepth(depth int64) RecursionLimit

RecursionLimitDepth returns a depth limited recursion to the given depth

func RecursionLimitNone added in v0.0.2 

func RecursionLimitNone() RecursionLimit

RecursionLimitNone return recursion with no limit

func (RecursionLimit) Depth added in v0.0.2 

func (rl RecursionLimit) Depth() int64

Depth returns the depth for a depth recursion limit, or 0 otherwise

func (RecursionLimit) Mode added in v0.0.2 

func (rl RecursionLimit) Mode() RecursionLimit_Mode

Mode returns the type for this recursion limit

type RecursionLimit_Mode added in v0.0.2 

type RecursionLimit_Mode uint8

RecursionLimit_Mode is an enum that represents the type of a recursion limit -- either "depth" or "none" for now 

const (
	// RecursionLimit_None means there is no recursion limit
	RecursionLimit_None RecursionLimit_Mode = 0
	// RecursionLimit_Depth mean recursion stops after the recursive selector
	// is copied to a given depth
	RecursionLimit_Depth RecursionLimit_Mode = 1
)

type Reifiable added in v0.14.4 

type Reifiable interface {
	NamedReifier() string
}

Reifiable provides a feature detection interface on selectors to understand when and if Reification of the datamodel.node should be attempted when performing traversals.

type SegmentIterator 

type SegmentIterator interface {
	Next() (pathSegment datamodel.PathSegment, value datamodel.Node, err error)
	Done() bool
}

SegmentIterator iterates either a list or a map, generating PathSegments instead of indexes or keys

func NewSegmentIterator 

func NewSegmentIterator(n datamodel.Node) SegmentIterator

NewSegmentIterator generates a new iterator based on the node type

type Selector 

type Selector interface {

	// Interests should return either a list of PathSegment we're likely interested in,
	// **or nil**, which indicates we're a high-cardinality or expression-based selection clause and thus we'll need all segments proposed to us.
	// Note that a non-nil zero length list of PathSegment is distinguished from nil: this would mean this selector is interested absolutely nothing.
	//
	// Traversal will call this before calling Explore, and use it to try to call Explore less often (or even avoid iterating on the data node at all).
	Interests() []datamodel.PathSegment

	// Explore is told about the node we're at, and the pathSegment inside it to consider,
	// and returns either nil, if we shouldn't explore that path any further,
	// or returns a Selector, which should then be used to explore the child at that path.
	//
	// Note that the node parameter is not the child, it's the node we're currently at.
	// (Often, this is sufficient information: consider ExploreFields,
	// which only even needs to regard the pathSegment, and not the node at all.)
	//
	// Remember that Explore does **not** iterate `node` itself; the visits to any children of `node` will be driven from the outside, by the traversal function.
	// (The Selector's job is just guiding that process by returning information.)
	// The architecture works this way so that a sufficiently clever traversal function could consider several reasons for exploring a node before deciding whether to do so.
	Explore(node datamodel.Node, child datamodel.PathSegment) (subsequent Selector, err error)

	// Decide returns true if the subject node is "matched".
	//
	// Only "Matcher" clauses actually implement this in a way that ever returns "true".
	// See the Selector specs for discussion on "matched" vs "reached"/"visited" nodes.
	Decide(node datamodel.Node) bool

	// Match is an extension to Decide allowing the matcher to `decide` a transformation of
	// the matched node. This is used for `Subset` match behavior. If the node is matched,
	// the first argument will be the matched node. If it is not matched, the first argument
	// will be null. If there is an error, the first argument will be null.
	Match(node datamodel.Node) (datamodel.Node, error)
}

Selector is a "compiled" and executable IPLD Selector. It can be put to work with functions like traversal.Walk, which will use the Selector's guidance to decide how to traverse an IPLD data graph. A user will not generally call any of the methods of Selector themselves, nor implement the interface; it is produced by "compile" functions in this package, and used by functions in the `traversal` package.

A Selector is created by parsing an IPLD Data Model document that declares a Selector (this is accomplished with functions like CompileSelector). To make this even easier, there is a `parse` subpackage, which contains helper methods for parsing direction from a JSON Selector document to a compiled Selector value. Alternatively, there is a `builder` subpackage, which may be useful if you would rather create the Selector declaration programmatically in golang (however, we recommend using this sparingly, because part of what makes Selectors cool is their language-agnostic declarative nature).

There is no way to go backwards from this "compiled" Selector type into the declarative IPLD data model information that produced it. That declaration information is discarded after compilation in order to limit the amount of memory held. Therefore, if you're building APIs about Selector composition, keep in mind that you'll probably want to approach this be composing the Data Model declaration documents, and you should *not* attempt to be composing this type, which is only for the "compiled" result.

func CompileSelector added in v0.11.0 

func CompileSelector(dmt datamodel.Node) (Selector, error)

CompileSelector accepts a datamodel.Node which should contain data that declares a Selector. The data layout expected for this declaration is documented in https://datamodel.io/specs/selectors/ .

If the Selector is compiled successfully, it is returned. Otherwise, if the given data Node doesn't match the expected shape for a Selector declaration, or there are any other problems compiling the selector (such as a recursion edge with no enclosing recursion declaration, etc), then nil and an error will be returned.

func ParseSelector 

func ParseSelector(dmt datamodel.Node) (Selector, error)

ParseSelector is an alias for CompileSelector, and is deprecated. Prefer CompileSelector.

type Slice added in v0.16.0 

type Slice struct {
	From int64
	To   int64
}

Slice limits a result node to a subset of the node. The returned node will be limited based on slicing the specified range of the node into a new node, or making use of the `AsLargeBytes` io.ReadSeeker to restrict response with a SectionReader.

Slice supports [From,To) ranges, where From is inclusive and To is exclusive. Negative values for From and To are interpreted as offsets from the end of the node. If To is greater than the node length, it will be truncated to the node length. If From is greater than the node length or greater than To, the result will be a non-match.

func (Slice) Slice added in v0.16.0 

func (s Slice) Slice(n datamodel.Node) (datamodel.Node, error)

Source Files

View all Source files

Directories

Path Synopsis
selectorparse package contains some helpful functions for parsing the serial form of Selectors.
 selectorparse package contains some helpful functions for parsing the serial form of Selectors.

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.