-
Notifications
You must be signed in to change notification settings - Fork 50
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
selectors: docs enhancements, new construction helpers. #199
Conversation
a723765
to
27bdce1
Compare
… parse vs parse+compile functions. Also switch to dag-json rather than plain json, because selectors may include links now (in the condition clauses).
27bdce1
to
3eb2c31
Compare
I've pushed this around a bit to a state I think I'm happy with. Contains much more docs now. I did move things to a sub-package so we can also merge this while remaining fairly noncommittal to it, and feel relatively free to iterate for a bit. I think I'd like to merge this now? Even if there's nothing earthshattering here, incremental improvement to the docs would be nice to have on master now. (I almost accidentally started writing docs improvements again before realizing there are some on this branch... 🤦 ) |
"no complaints" is good enough for me on this one. |
(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.