Design Front Facing Interface

[ttocsneb]

With the new changes proposed on how the engine will work. It isn't very clear how exactly we will implement the engine. To help with that, I think creating the interface users will use might be helpful.

This would be function/type stubs with some docs on how they will be used.

[ttocsneb]

I have made a pretty extensive item implementation on ttocsneb-api (docs). I'm feeling pretty good about it.

I took inspiration from 0.2.0 mbon items and added some options which would allow for hinting at the internal storage of the items.

Such as with Item, there is set_ptr, set_boxed, and set_normal. These tell mbon to store either as a pointer, boxed value, or as itself. If none of these are set, then mbon is free to decide how it wants to store it.

In List and Map, there are options to try_set_normalized and with maps: set_struct. These similarly hint at whether the item should be stored as its more efficient version or as a struct. With try_set_normalized, it will check whether all of the contained items are actually normalized. Any modification to the item would cause the normalized flag to be reset.

There are no implementations for normalization yet, but I have some ideas on how it might be done. I feel like there might be more that could be added, but I'm not sure yet.

[tryoxiss]

One minor thing I noticed, the docs say 0.3.0+nightly, but the + in Semver is to add build specific info (that will be unique to every build, as in only that one build is likely to ever have it, almost always commit hash). The correct way to add a tag to a build such as nightly is with a -, so 0.3.0-nightly.

its also notable that Engine and Item is a generic term which is likely to be confused. Other libraries use soemthing which is difficult or impossible to confuse, such as JsonValue in serde_json. By convention, I would reccommend MbonEngine for the main read/writer as it can be shared in a static variable instead of at each site, (at least it seems so), MbonValue for values, and Mbon for a complete file with all file-complete data, produced by the engine (if needed).

It will also need to be decided if sync or async-tokio is default, or neither. If one is specified, no-default-features=true would need to be specified.

[ttocsneb]

There isn't much information I could find online, and it seemed like +nightly is reserved for nightly builds while everything else would use - which seems a bit odd. Thanks for clearing that up!

That sounds good, I will prefix types with Mbon.

I want to have neither sync or async-tokio be default specifically so that no-default-features=true isn't needed. In cargo.toml, I have those commented out default features for my lsp. Do you know if there is a way to configure rust-analyzer to assume a set of features?

[tryoxiss]

There isn't much information I could find online, and it seemed like +nightly is reserved for nightly builds while everything else would use - which seems a bit odd. Thanks for clearing that up!

No problem! There really isn't much info, but its mentioned in the semver spec section 10, diffrently from pre-releases which are denoted with a -. I may be wrong but its what my reading points to.

I want to have neither sync or async-tokio be default specifically so that no-default-features=true isn't needed. In cargo.toml, I have those commented out default features for my lsp. Do you know if there is a way to configure rust-analyzer to assume a set of features?

I don't know of a way for it to assume a set of features directly, no. However you can use tests/ in the project root to create "integration tests", which I believe are just cargo projects that use the library in question. So you could set one up for sync and one for async-tokio to ensure API/Functionality parity.