signaling ADLs in selectors

linking/types.go

@@ -37,6 +37,7 @@ type LinkSystem struct {
 	StorageReadOpener  BlockReadOpener
 	TrustedStorage     bool
 	NodeReifier        NodeReifier
+	KnownReifiers      map[string]NodeReifier
 }
 
 // The following three types are the key functionality we need from a "blockstore".

traversal/selector/builder/builder.go

@@ -30,6 +30,7 @@ type SelectorSpecBuilder interface {
 	ExploreIndex(index int64, next SelectorSpec) SelectorSpec
 	ExploreRange(start, end int64, next SelectorSpec) SelectorSpec
 	ExploreFields(ExploreFieldsSpecBuildingClosure) SelectorSpec
+	ExploreInterpretAs(as string, next SelectorSpec) SelectorSpec
 	Matcher() SelectorSpec
 }
 
@@ -150,6 +151,17 @@ func (ssb *selectorSpecBuilder) ExploreFields(specBuilder ExploreFieldsSpecBuild
 	}
 }
 
+func (ssb *selectorSpecBuilder) ExploreInterpretAs(as string, next SelectorSpec) SelectorSpec {
+	return selectorSpec{
+		fluent.MustBuildMap(ssb.np, 1, func(na fluent.MapAssembler) {
+			na.AssembleEntry(selector.SelectorKey_ExploreInterpretAs).CreateMap(1, func(na fluent.MapAssembler) {
+				na.AssembleEntry(selector.SelectorKey_As).AssignString(as)
+				na.AssembleEntry(selector.SelectorKey_Next).AssignNode(next.Node())
+			})
+		}),
+	}
+}
+
 func (ssb *selectorSpecBuilder) Matcher() SelectorSpec {
 	return selectorSpec{
 		fluent.MustBuildMap(ssb.np, 1, func(na fluent.MapAssembler) {

traversal/selector/exploreInterpretAs.go

@@ -0,0 +1,65 @@
+package selector
+
+import (
+	"fmt"
+
+	"github.com/ipld/go-ipld-prime/datamodel"
+)
+
+type ExploreInterpretAs struct {
+	next Selector // selector for element we're interested in
+	adl  string   // reifier for the ADL we're interested in
+}
+
+// Interests for ExploreIndex is just the index specified by the selector node
+func (s ExploreInterpretAs) Interests() []datamodel.PathSegment {
+	return s.next.Interests()
+}
+
+// Explore returns the node's selector if
+// the path matches the index for this selector or nil if not
+func (s ExploreInterpretAs) Explore(n datamodel.Node, p datamodel.PathSegment) (Selector, error) {
+	return s.next, nil
+}
+
+// Decide always returns false because this is not a matcher
+func (s ExploreInterpretAs) Decide(n datamodel.Node) bool {
+	return false
+}
+
+// NamedReifier indicates how this selector expects to Reify the current datamodel.Node.
+func (s ExploreInterpretAs) NamedReifier() string {
+	return s.adl
+}
+
+// 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 Reifiable interface {
+	NamedReifier() string
+}
+
+// ParseExploreInterpretAs assembles a Selector
+// from a ExploreInterpretAs selector node
+func (pc ParseContext) ParseExploreInterpretAs(n datamodel.Node) (Selector, error) {
+	if n.Kind() != datamodel.Kind_Map {
+		return nil, fmt.Errorf("selector spec parse rejected: selector body must be a map")
+	}
+	adlNode, err := n.LookupByString(SelectorKey_As)
+	if err != nil {
+		return nil, fmt.Errorf("selector spec parse rejected: the 'as' field must be present in ExploreInterpretAs clause")
+	}
+	next, err := n.LookupByString(SelectorKey_Next)
+	if err != nil {
+		return nil, fmt.Errorf("selector spec parse rejected: the 'next' field must be present in ExploreInterpretAs clause")
+	}
+	selector, err := pc.ParseSelector(next)
+	if err != nil {
+		return nil, err
+	}
+	adl, err := adlNode.AsString()
+	if err != nil {
+		return nil, err
+	}
+
+	return ExploreInterpretAs{selector, adl}, nil
+}

traversal/selector/fieldKeys.go

@@ -10,6 +10,7 @@ const (
 	SelectorKey_ExploreUnion         = "|"
 	SelectorKey_ExploreConditional   = "&"
 	SelectorKey_ExploreRecursiveEdge = "@"
+	SelectorKey_ExploreInterpretAs   = "~"
 	SelectorKey_Next                 = ">"
 	SelectorKey_Fields               = "f>"
 	SelectorKey_Index                = "i"
@@ -21,5 +22,6 @@ const (
 	SelectorKey_LimitNone            = "none"
 	SelectorKey_StopAt               = "!"
 	SelectorKey_Condition            = "&"
+	SelectorKey_As                   = "as"
 	// not filling conditional keys since it's not complete
 )

traversal/selector/selector.go

@@ -165,6 +165,8 @@ func (pc ParseContext) ParseSelector(n datamodel.Node) (Selector, error) {
 		return pc.ParseExploreRecursive(v)
 	case SelectorKey_ExploreRecursiveEdge:
 		return pc.ParseExploreRecursiveEdge(v)
+	case SelectorKey_ExploreInterpretAs:
+		return pc.ParseExploreInterpretAs(v)
 	case SelectorKey_Matcher:
 		return pc.ParseMatcher(v)
 	default:

traversal/walk.go

@@ -155,6 +155,32 @@ func (prog Progress) walkAdv(n datamodel.Node, s selector.Selector, fn AdvVisitF
 		}
 		prog.Budget.NodeBudget--
 	}
+
+	// refiy the node if advised.
+	if rs, ok := s.(selector.Reifiable); ok {
+		adl := rs.NamedReifier()
+		if prog.Cfg.LinkSystem.KnownReifiers == nil {
+			return fmt.Errorf("adl requested but not supported by link system: %q", adl)
+		}
+		reifier, ok := prog.Cfg.LinkSystem.KnownReifiers[adl]
+		if !ok {
+			return fmt.Errorf("unregistered adl requested: %q", adl)
+		}
+
+		rn, err := reifier(linking.LinkContext{
+			Ctx:      prog.Cfg.Ctx,
+			LinkPath: prog.Path,
+		}, n, &prog.Cfg.LinkSystem)
+		if err != nil {
+			return fmt.Errorf("failed to reify node as %q: %w", adl, err)
+		}
+		s, err = s.Explore(n, datamodel.PathSegment{})
+		if err != nil {
+			return err
+		}
+		n = rn
+	}
+
 	// Decide if this node is matched -- do callbacks as appropriate.
 	if s.Decide(n) {
 		if err := fn(prog, n, VisitReason_SelectionMatch); err != nil {

traversal/walk_test.go

@@ -491,3 +491,40 @@ func TestWalkBlockLoadOrder(t *testing.T) {
 		})
 	})
 }
+
+func TestWalk_ADLs(t *testing.T) {
+	// we'll make a reifier that when it sees a list returns a custom element instead.
+	customReifier := func(_ linking.LinkContext, n datamodel.Node, _ *linking.LinkSystem) (datamodel.Node, error) {
+		if n.Kind() == datamodel.Kind_List {
+			return leafAlpha, nil
+		}
+		return n, nil
+	}
+
+	ssb := builder.NewSelectorSpecBuilder(basicnode.Prototype.Any)
+	ss := ssb.ExploreFields(func(efsb builder.ExploreFieldsSpecBuilder) {
+		efsb.Insert("linkedList", ssb.ExploreInterpretAs("linkJumper", ssb.Matcher()))
+	})
+	s, err := ss.Selector()
+	qt.Check(t, err, qt.IsNil)
+	lsys := cidlink.DefaultLinkSystem()
+	lsys.KnownReifiers = map[string]linking.NodeReifier{"linkJumper": customReifier}
+	lsys.SetReadStorage(&store)
+	var order int
+	err = traversal.Progress{
+		Cfg: &traversal.Config{
+			LinkSystem:                     lsys,
+			LinkTargetNodePrototypeChooser: basicnode.Chooser,
+		},
+	}.WalkMatching(rootNode, s, func(prog traversal.Progress, n datamodel.Node) error {
+		switch order {
+		case 0:
+			qt.Check(t, n, nodetests.NodeContentEquals, basicnode.NewString("alpha"))
+			qt.Check(t, prog.Path.String(), qt.Equals, "linkedList")
+		}
+		order++
+		return nil
+	})
+	qt.Check(t, err, qt.IsNil)
+	qt.Check(t, order, qt.Equals, 1)
+}