selectors: docs enhancements, new construction helpers. #199
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
(This PR is probably a discussion started first and foremost, but might actually also just be minimally useful.)
Tried to enhance the Selector type docs a bit more. This is feeling easier to talk about having looked at other systems we've built in IPLD and coming back to it now: there's a couple recurring themes: we've got a "compiled" type and a data model tree ("dmt") type again. (In the case of selectors, the latter still doesn't really have a type in the golang signatures here -- it's just
Node
, which is fairly unspecific -- but someday we could make this more strongly typed, and probably would like to.)I added a
CompileSelector
function, which is exactly the same as the oldParseSelector
. I think I'd like to push this naming convention, though. "parse" (at least in my mind) connotes something that has much more to do with codecs than this function's behavior actually does -- it's no codec, it's just dmt->compiled. I didn't get rid ofParseSelector
, because I think slow change rollout is becoming valuable, but I commented it as deprecated, and consider this a "move" operation.I added a
CompileJSONSelector
function as well. This function does more work in one step: you give it a json string, it parses json->dmt, and then it compiles dmt->compiled selector. Should be a nice usability enhancement, but there's a couple things about it that are bikeshedable, and a couple things that are debatable -- I'll start comment threads on the diff for those.Finally, started adding some constants of selectors that are "common", as @willscott has been advocating for for a while now :) These are using JSON string literals as their constructors, which I think will make them useful for educational purposes -- folks looking at them can see this clearly serializable thing that they can copy, edit, and paste, even paste into APIs (rather than being limited to use in golang code)... I think that should be worth about a thousand words of other docs.