Enum forest_filecoin::ipld::selector::Selector

pub enum Selector {
    Matcher,
    ExploreAll {
        next: Box<Selector>,
    },
    ExploreFields {
        fields: IndexMap<String, Selector>,
    },
    ExploreIndex {
        index: usize,
        next: Box<Selector>,
    },
    ExploreRange {
        start: usize,
        end: usize,
        next: Box<Selector>,
    },
    ExploreRecursive {
        sequence: Box<Selector>,
        limit: RecursionLimit,
        stop_at: Option<Condition>,
        current: Option<Box<Selector>>,
    },
    ExploreUnion(Vec<Selector>),
    ExploreRecursiveEdge,
}

Selectors are expressions that identify and select a subset of data from an IPLD DAG. Selectors are themselves IPLD and can be serialized and de-serialized as such.

Variants

Matcher

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.

ExploreAll

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.

Fields

next: Box<Selector>

ExploreFields

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

Note that a concept of exploring a whole path (e.g. “path/to/file”) can be represented as a set of three nested ExploreFields selectors, each specifying one field.

Fields insertion order is maintained and traversed using that order.

Fields

fields: IndexMap<String, Selector>

ExploreIndex

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

Fields

index: usize

next: Box<Selector>

ExploreRange

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

Fields

start: usize

end: usize

next: Box<Selector>

ExploreRecursive

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 depth parameter for limit (if limit is of type depth), and continues evaluation.

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 depth limit parameter; it can easily cause very large traversals (especially if used in combination with selectors like ExploreAll inside the sequence).

limit is a union type – it can have an integer depth value (key “depth”) or no value (key “none”). If limit has no value it is up to the implementation library using selectors to identify an appropriate max depth as necessary so that recursion is not infinite

Fields

sequence: Box<Selector>

limit: RecursionLimit

stop_at: Option<Condition>

if a node matches, we won’t match it nor explore its children.

current: Option<Box<Selector>>

Used to index current

ExploreUnion(Vec<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 labeled) result set), while simultaneously continuing to explore deeper parts of the tree with another selector, for example.

ExploreRecursiveEdge

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.

Trait Implementations

impl Clone for Selector

fn clone(&self) -> Selector

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Selector

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Selector

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Selector

fn eq(&self, other: &Selector) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Selector

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Selector