Add methods db.run_script_ast and db.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 documented cozo::parse and the parse_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 using cozo-core, parsing an AST, and running an AST directly. The reason I made it a separate module is because examples 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.
Fixes #224
Make all of the AST public, rooted at
CozoScriptMake
cozo::parse::parse_scriptpublicAdd methods
db.run_script_astanddb.get_fixed_rulesto 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 (
FixedRuletraits) could be considered internal, so I explicitly documentedcozo::parseand theparse_scriptmethods as unstable to warn users that they might change in any future release.Design notes and concerns
I don't think exposing
get_fixed_rulesis 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-examplesmodule, with examples of usingcozo-core, parsing an AST, and running an AST directly. The reason I made it a separate module is becauseexamplesetc 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.