Skip to content
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

Merged
merged 2 commits into from
Aug 12, 2021

Conversation

warpfork
Copy link
Collaborator

@warpfork warpfork commented Jul 3, 2021

(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 old ParseSelector. 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 of ParseSelector, 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.

@warpfork warpfork requested a review from willscott July 3, 2021 19:40
traversal/selector/helpers.go Outdated Show resolved Hide resolved
traversal/selector/helpers.go Outdated Show resolved Hide resolved
… parse vs parse+compile functions.

Also switch to dag-json rather than plain json, because selectors may include links now (in the condition clauses).
@warpfork
Copy link
Collaborator Author

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... 🤦 )

@warpfork warpfork merged commit e617585 into master Aug 12, 2021
@warpfork
Copy link
Collaborator Author

"no complaints" is good enough for me on this one.

@warpfork warpfork deleted the selector-helpers branch August 12, 2021 11:42
@aschmahmann aschmahmann mentioned this pull request Aug 23, 2021
62 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants