Change the public API

[duesee]

Hey, as you know I am currently in the process of preparing imap-proto for a larger merge. I have started to separate all parsers from type definitions and did some minor cleanups. I tried not to change the public interface, but as this is pre-1.0 maybe we can just make this change now.

How do you feel about exposing the following API:

pub use crate::{
    parsers::{self, ParseResult},
    types,

    parse_response,
    resp_metadata,
}

for now?

Later I think adding crate::command, and crate::response makes sense. Those can then contain the code from builders, i.e. use crate::command::CommandBuilder.

Currently, also body, body_structure, and core are exposed on the top-level. I would like to move them all to parsers::.

What do you think?

[djc]

In general, don't worry about changing the public API. Changing the API is mostly fine, especially if they're easy to fix and prove their value in terms of improved usability.

I think the public API for parse_response() should maybe be more like Response::from_bytes(). For ParseResult, ideally we'd wrap over nom's IResult such that nom is no longer part of the public API. types is already public today. Moving body, body_structure and core into parsers sounds good to me. It looks like maybe resp_metadata should be called from the response parser, so that it can also be part of Response::from_bytes() (and similar for any parser that results in a variant of Response).

Some notes on how the process for this should look like:

• Lots of small commits; each commit should individually be rustfmtted and pass the tests. Commits should ideally contain either moving code around or new code, but not both (except to satisfy the previous criterion).
• Although the parser modules are currently ordered the other way around, in the mid- to long term I want to order code with top-level API first, as described in more detail in https://deterministic.space/how-to-order-rust-code.html. For existing code (either in this crate or in another crate that you've created) we can waive this requirement, but would be nice to have.
• BTW, I also want to move to non-macro nom parsers, but haven't found the time to do so for imap-proto, yet.

Does all that make sense?

[duesee]

Yes it absolutely does! Maybe you should paste this into a contributing.md? https://help.github.com/en/github/building-a-strong-community/setting-guidelines-for-repository-contributors

I also think that we should change parse_response and resp_metadata, but wanted to focus on other things first. This was the "... for now" part :-)

We could adopt the terminology from the ABNF definitions and expose three parsers:

• parse::response::data (~which I assume is now resp_metadata~),
• parse::response::done, and
• parse::response::response (which will invoke data* done)

Exposing all functions may be required, as the server can send "unsolicited" data at any time.

Edit: Okay, resp_metadata was something different. Anyway, I think that the rest of the comment makes still sense :-)

Edit 2: Ah okay, I see. parse_response -> Response abstracts over continue, data and done already. That is even better :+1:

[djc]

So then we're in agreement now on this front at least? :)

[duesee]

Oh, I had the feeling that we agree on most fronts so far :-) Maybe we won't regarding &str and Atom, but I find this really difficult, so not sure if I agree with myself either. The PR for this is not merged yet, but I don't mind if you close this issue as it was a question only. Alternatively I can mention this in some commit.

[djc]

Let's close this for now, then.