This is my review of LEAF as a long-time user and proponent of Boost:
Please provide in your review information you think is valuable to understand your choice to ACCEPT or REJECT including LEAF as a Boost library. Please be explicit about your decision (ACCEPT or REJECT).
ACCEPT
- What is your evaluation of the design?
It's similar to many Boost libraries before it in that it's incredibly rich, nuanced and can give you the most cryptic and hard-to-decipher compiler errors. However, the more I used it and become accustomed to its idioms, the more I found myself enjoying it. `preload` is the most simple and elegant abstraction I've seen for incrementally adding information to an error context as it travels back up the callstack. I've seen similar patterns be attempted in Go and LEAF far and away has the most powerful and type-safe approach. `preload` should, however, have a [[nodiscard]] attribute attached to it. `try_handle_all` is a nicer alternative to exception handling though it can be difficult to tell if an overload is going to be called when trying to match up against errors. I'm assuming this is simply because of my inexperience with the library and is something that will be alleviated with time. The library also works very well with normal exception based code. leaf::catch_ and leaf::exception_to_result are useful abstractions that help the user integrate LEAF piece-by-piece into the codebase which is important when looking at updating existing code. Because users can manually control the error context (including storing it and using RAII-like wrappers to activate it), it's usable in Asio which is a hard requirement for me. Overall, the design of the library is quite powerful and is relatively simple for how much it does.
- What is your evaluation of the implementation?
As a user, the only thing that matters to me is: is it better than I could've done myself? And the answer to that question is a resounding "yes!" Otherwise, the implementation details are best left evaluated by a fellow library author which I am not aiming to be in this instance.
- What is your evaluation of the documentation?
Parts seemed out of line with what was in the examples (I'm thinking of exception_to_result) but overall, the documentation has good styling and goes into quite a bit of depth. The examples in the source repo are quite good as well. As a user, I found myself able to reference things and get a working example relatively quickly that show-cased the power of LEAF.
- What is your evaluation of the potential usefulness of the library?
Incredibly useful. When writing user-facing applications, it's important that one gathers up appropriate data to craft a useful error message to display. It's also incredibly useful because of the type-safe matching in try_handle_all. Error codes are not sufficient many times and LEAF minimizes the amount of boilerplate one would have to use to update existing code.
- Did you try to use the library? With which compiler(s)? Did you have any problems?
I did. It installed perfectly with CMake and was able to be find_package()'d easily. I used gcc 10.0.1 in WSL.
- How much effort did you put into your evaluation? A glance? A quick reading? In-depth study?
I dedicated around 2 to 3 hours playing around with it in addition to spending about an hour last week reading the docs. Even though I'm not fully adept with using the library, I see its potential. Many Boost libs require time to learn and digest and they're fantastic (I'm thinking of Asio, Beast, Spirit) so I'm not holding any stumbles I encountered against it.
- Are you knowledgeable about the problem domain?
If the problem is error handling, I'm decently well-versed. I've written many user-facing applications and have wound up reimplementing what LEAF does a couple of times. Some closing thoughts... LEAF doesn't have to be perfect to be accepted. I think as of now, it's documented and completed enough that it can be picked up and used but more importantly, I think its core goal is worthwhile enough that it should be iterated on and refined by many users trying it out and providing their feedback. I've seen this pattern be re-implemented in Go and in many codebases I've worked on professionally. LEAF far and away has the best implementation I've personally seen and for that reason, I think it should be wholeheartedly accepted into Boost. - Christian