Express selector matching of sub-ranges of bytes or strings (#184)

Primarily useful over ADL composite nodes, the traversal of a node may select only a partial range of the node contents, allowing for selector specification traversals that partially return the nodes backing a unixfs file.

specs/selectors/fixtures/selector-fixtures-adl.md

@@ -0,0 +1,89 @@
+Selector Fixtures (ADL)
+=======================
+
+This file contains a set of selectors that can be used to test the ADL capabilities of selectors (InterpretAs and Slice).
+
+
+### What's the fixture format?
+
+Same as described in [selector-fixtures-1](../selector-fixtures-1/#whats-the-fixture-format).
+
+---
+
+
+Fixtures
+--------
+
+### A slice of a unixfs file.
+
+#### data
+The combination of these five data objects is replicated in `selector-fixtures-adl.car`.
+
+[testmark]:# (adl-interpreted/root)
+```json
+{
+    "Data":{
+        "/":{"bytes":"CAIYgIBAIICAECCAgBAggIAQIICAEA"}
+    },
+    "Links":[
+        {"Hash":{"/":"baguqeera2pkvbqv2slrvh3dswozj6ozoob53idll3rkh3zh5tqsdqjvpzu7q"},"Name":"","Tsize":14},
+        {"Hash":{"/":"baguqeerasc2dhjjhbg6h3rt7rqbgpzlwzng5to3zwxcxtmdajfqt6tdyxscq"},"Name":"","Tsize":14},
+        {"Hash":{"/":"baguqeera7d7gvq7y7rugmmzh3u2552ckh6hyqno3tptbceutb5s3c4vixsua"},"Name":"","Tsize":14},
+        {"Hash":{"/":"baguqeeraxvm7dmqutnagoxxhq2iyghr5qidbjovdi7iqdptw527gifajqlgq"},"Name":"","Tsize":14}
+    ]
+}
+```
+
+the leaves are dag-json encodings of "file chunk a\r\n" through "file chunk d\r\n".
+
+[testmark]:# (adl-interpreted/baguqeera2pkvbqv2slrvh3dswozj6ozoob53idll3rkh3zh5tqsdqjvpzu7q)
+```json
+{
+    "/":{"bytes":"ZmlsZSBjaHVuayBhCgo"}
+}
+```
+[testmark]:# (adl-interpreted/baguqeerasc2dhjjhbg6h3rt7rqbgpzlwzng5to3zwxcxtmdajfqt6tdyxscq)
+```json
+{
+    "/":{"bytes":"ZmlsZSBjaHVuayBiCgo"}
+}
+```
+[testmark]:# (adl-interpreted/baguqeera7d7gvq7y7rugmmzh3u2552ckh6hyqno3tptbceutb5s3c4vixsua)
+```json
+{
+    "/":{"bytes":"ZmlsZSBjaHVuayBjCgo"}
+}
+```
+[testmark]:# (adl-interpreted/baguqeeraxvm7dmqutnagoxxhq2iyghr5qidbjovdi7iqdptw527gifajqlgq)
+```json
+{
+    "/":{"bytes":"ZmlsZSBjaHVuayBkCgo"}
+}
+```
+#### selector
+
+[testmark]:# (adl-interpreted/selector)
+```json
+{
+	"~": {
+        "as": "unixfs",
+        ">": {
+            ".": {
+                "subset": {
+                    "[": 14,
+                    "]": 42
+                }
+            }
+        }
+	}
+}
+```
+
+#### expected visit events
+
+the visit will be to the synthetic node containing the contents: "file chunk b\r\nfile chunk c\r\n"
+
+[testmark]:# (adl-interpreted/expect-visit)
+```text
+{"path": "", "node": {"bytes": {"/":{"bytes":"ZmlsZSBjaHVuayBiCgpmaWxlIGNodW5rIGMKCg"}}}, "matched": true}
+```

specs/selectors/index.md

@@ -201,6 +201,15 @@ type InterpretAs struct {
 	next Selector (rename ">")
 }
 
+## Slice is a predicate that selects only a subset of node.
+## This is applicable primarily in the context of reified nodes based on the
+## InterpetAs clause above, where the primitive (bytes or string) node is actually
+## composed from multiple underlying substrate nodes.
+type Slice struct {
+	from Int (rename "[")
+	to Int (rename "]")
+}
+
 ## 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.)
@@ -213,6 +222,7 @@ type InterpretAs struct {
 type Matcher struct {
 	onlyIf optional Condition # match is true based on position alone if this is not set.
 	label optional String # labels can be used to match multiple different structures in one selection.
+	subset optional Slice # if set, only the subset of the node specified by the slice is matched.
 }
 
 ## Condition is expresses a predicate with a boolean result.