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.
Fixes #224
Make all of the AST public, rooted at
CozoScript
Make
cozo::parse::parse_script
publicAdd methods
db.run_script_ast
anddb.get_fixed_rules
to db to allow executing ASTs directly. These are used under the hood by the existing methods.Some of the interfaces are a bit raw, and while it seemed pretty clean to me some of the stuff that's exposed (
FixedRule
traits) could be considered internal, so I explicitly documentedcozo::parse
and theparse_script
methods as unstable to warn users that they might change in any future release.Design notes and concerns
I don't think exposing
get_fixed_rules
is great. The rules are embedded in the AST during parsing and I thought this might be an optimization thing, so I left it.A cleaner solution might be to just embed the names in the AST, and have the database look up the fixed rules when translating/executing the query (raising an error if they don't exist at that time). It'd also make the AST objects more portable so generic functions could return them without knowing which DB backend it'll be used in, and might pave the way to serializing/deserializing scripts as JSON.
For now though since the performance question is unanswered I think this is good enough.
Parameters are also inlined. It means an AST can't be reused with different parameters, but I'm not sure how actually common that is, so I think this is fine.
Current validity is passed in both during parsing and during execution, and I'm not sure if this is necessary, but I didn't dig too deep.
Documentation - I left most things undocumented. A decent amount corresponds to terminology in the online documentation, and I added some docstrings for things that I actually encountered and couldn't figure out at a glance. I don't think it's practical to document everything atm, and since maintenance isn't super active on this library I don't think it's reasonable to expect everything to be documented from the start. Incrementally adding documentation as people have questions or make PRs to document should be an OK compromise I think.
I added a
cozo-core-examples
module, with examples of usingcozo-core
, parsing an AST, and running an AST directly. The reason I made it a separate module is becauseexamples
etc inherits the parent dependencies, so it can hide issues with macro dependencies and other things, and having separate dependencies serves as a better reference for users.