Re: Review of mustache starts today.

From: Vinnie Falco (vinnie.falco_at_[hidden])
Date: 2023-02-07 17:41:07

On Sat, Feb 4, 2023 at 7:56 PM Klemens Morgenstern via Boost
<boost_at_[hidden]> wrote:
> Please explicitly state that you either *accept* or *reject* the inclusion
> of this library into boost.

I am deeply appreciative of the years I have spent working with the
author on the C++ language Slack (at https://slack.cpp.al/) and the
benefits this has brought to my libraries. However, I must REJECT this
library.

> Also please indicate the time & effort spent on the evaluation and give the
> reasons for your decision.

I spent quite a lot of time. 20% of it was wrestling with the cmake
scripts. 40% was wrestling with authoring a boost::buffers::source,
which came out terribly:

<https://github.com/vinniefalco/http_io/blob/abb722981d1adfc37524abed87c8bb88720ac9ec/example/server/mustache_source.hpp#L28>

And the other 40% was figuring out what and how to write this review,
which I will try to keep brief.

"What makes a good Boost library candidate?"

I believe that when a library is accepted into Boost, it has to walk
on water. That means it can't just work, it has to work well and it
needs to have some unique qualities which distinguish it from all
other libraries in its class. For example here are some of the reasons
that my libraries and other libraries are a cut above:

Boost.Beast: First HTTP/Websocket library using idiomatic Asio
Boost.JSON: The only streaming parser/serializer for JSON with performant DOM
Boost.URL: Superior interface (class url_view) and manipulation
capability (class url)
Boost.Aedis: Beautiful multiplexing of concurrent requests and
responses onto a single socket
Boost.Describe: C++14 Reflection today, instead of 20 years from now.

Unfortunately Boost.Mustache does not distinguish itself by
demonstrating excellence. If there is a subsequent re-review, I would
like to see:

* Better documentation on what Mustache is, for people who don't know
  - The author has already acknowledged this on the list

* Better documentation for public APIs
  - The meaning of each parameter, in clear terms
  - How to pass nothing for T2 in render and renderer
    + or better yet, a way to omit T2 entirely
  - Examples of correct syntax and usage for each function

* Explanation and example code for specific use-cases:
  - Streaming the template from a file incrementally
  - Using native Boost.JSON objects in T1 and T2

* Implement the output streaming interface described here:
  - <https://github.com/pdimov/mustache/issues/2>

* Better APIs than what is on offer:
  - A way to transfer ownership of JSON objects into the renderer
without copying, e.g.
        renderer::renderer( json::object&& data, json::object&&
partials ) noexcept;
  - A way to use user-defined types for T1 and T2 which do not require
constructing a json::value
        + but capturing native types with full fidelity, instead of using
            JSON as a crutch for thorough type-erasure (i.e. not
json::value_view).
  - Exploration or full implementation of lambdas
  - Exploration of on-demand partials as described here:
        + https://github.com/pdimov/mustache/issues/1

* HTML escaping support (maybe its already there?)
  + <https://stackoverflow.com/questions/7381974/which-characters-need-to-be-escaped-in-html>

* I need to be able to write a great buffers::source implementation
for Boost.Mustache.

"Exploration" above means either a full implementation at Boost
quality, or some kind of report of the results of experimentation
indicating how the feature might be implemented in a future version or
why the feature is not practical or a good match for C++.

I know that "pretty" Visual Studio solutions are not a requirement,
and that I'm an outlier in terms of using the IDE exclusively, but if
the CMLs could at least organize the source files and have some kind
of lib-as-root setting that would be a really great "plus" and a way
for Boost to distinguish itself as walking on water instead of just
providing the minimum "working" build scripts.

>  - Does this library bring real benefit to C++ developers for real world
> use-case?
>  - Do you have an application for this library?

Yes I think templating is a great fit for Boost now that we have these
other network component. The Mustache spec seems as good as anything
else.

>  - Is the documentation helpful and clear?

It is the bare minimum and it doesn't do the library any favors.
Someone who is new to Mustache and of average C++ skill is going to
have a challenging experience with the documentation in its current
state.

> ...

Thank you very much Peter for putting this together, I hope that this
review will be seen constructively and I very much hope to review or
use a better version of this library soon.

Thanks