Re: Review of mustache starts today.

From: Дмитрий Архипов (grisumbras_at_[hidden])
Date: 2023-02-18 13:49:17

This is my review of Boost.Mustache.

> Are you knowledgeable about the problem domain?
I have been using several text templating engines written in Python in
the past, and I still use them occasionally for small tasks.

> How much effort did you put into your evaluation? A glance? A quick reading? In-depth study?
Overall, about 8 hours over several days.

> Does this library bring real benefit to C++ developers for real world use-case?
Generating text from a template has a multitude of applications.

> Do you have an application for this library?
I thought I do, but turns out that I don't. And this has to do with
the severe inadequacy of the Mustache language. It is very simple and
minimal and is very cute in its simplicity. But this simplicity makes
it almost impossible to do very common tasks.

I started this review with an attempt to reimplement an existing
script that I had that created an HTML page. But the very first
templating element I needed was inexpressible in Mustache, because I
needed to have a special case for the first element of a list. I
realised that I had to tailor my input data for the specific needs of
Mustache language.

My second attempt was focused on trying to do that: structuring data
in the way Mustache can handle. This is where I realised that Mustache
doesn't play nice with the way Boost.JSON converts maps. If a map has
unique string-like keys Boost.JSON converts it to a json::object. But
Mustache doesn't treat them as sequences, it treats them as context
switches. I briefly considered switching to multimaps, which can have
non-unique keys and thus are converted to json::array of pairs. But
pairs are also converted to arrays by Boost.JSON, and as we've
previously established, Mustache cannot have a special treatment of
the first or the last element of a sequence.

> Does the API match with current best practices?
When reading documentation I considered it strange that there is no
non-throwing versions of render and render_some. Turns out this is
because parsing never fails, or at least, this is my impression,
because I've not managed to make it fail. I find this weird. I think
that syntax errors should be reported to the user. I also find it very
useful, when failed variable lookup is reported, and so I believe,
there needs to be some mechanism to enable that.

I think that using Boost.JSON containers for rendering context was a
very interesting decision, particularly because it enables a lot of
synergy. I believe the amount of copying it results in should be
negligible for most applications, and for others often a good
allocator would greatly reduce the amount of actual memory
allocations, so I'm not concerned with that too much. On the other
hand, the use of Boost.JSON did result in inability to support
Mustache lambdas, which could somewhat alleviate the language's
inadequacy.

> Is the documentation helpful and clear?
The documentation is too minimalistic. There should be more examples
starting with the most simple tasks, and gradually introducing more
complexity.

> What is your evaluation of the implementation?
I haven't spent much time looking through the implementation.

> Do you think the library should be accepted as a Boost library?
I think the library should be REJECTED almost entirely due to the
weakness of the Mustache language. There is a variation of Mustache
called Handlebars that has more features. In particular, it can
iterate over objects, allows accessing the iteration number in a loop,
has an if statement, and allows registering custom functions and
custom statements (which solves the lack of Mustache lambdas). I would
encourage Peter to implement that language and submit the new library
for review.

вс, 5 февр. 2023 г. в 06:56, Klemens Morgenstern via Boost
<boost_at_[hidden]>:
>
> The formal review of the mustache starts today, Sunday the 5th, and ends
> next week on Tuesday the 14th.
>
> The library was developed & submitted by Peter Dimov.
>
> Boost.Mustache is an implementation of Mustache templates in C++11.
>
> The master branch is frozen during the review and can be found here
> https://github.com/pdimov/mustache
>
> The current documentation can be found here:
> https://pdimov.github.io/mustache/doc/html/mustache.html
>
> Boost.Mustache is an implementation of Mustache templates in C++11.
>
> The documentation of Mustache templates is here: https://mustache.github.io/
>
> Review
> ========
>
> Please explicitly state that you either *accept* or *reject* the inclusion
> of this library into boost.
> The accept can be conditional.
>
> Also please indicate the time & effort spent on the evaluation and give the
> reasons for your decision.
>
> The review is open to anyone who is prepared to put in the work of
> evaluating and reviewing the library. Prior experience in contributing to
> Boost reviews is not a requirement.
>
> Some questions to consider:
>
>  - Does this library bring real benefit to C++ developers for real world
> use-case?
>  - Do you have an application for this library?
>  - Does the API match with current best practices?
>  - Is the documentation helpful and clear?
>  - Did you try to use it? What problems or surprises did you encounter?
>  - What is your evaluation of the implementation?
>
> More information about the Boost Formal Review Process can be found
> at: http://www.boost.org/community/reviews.html
>
> Reviews can also be submitted directly to me.
>
> Thank you Peter for submitting yet another boost library & thanks for all
> the reviews in advance.
>
>
> Building boost.mustache
> =======================
>
> Here's how to build the library, starting from scratch:
>
> 1. Clone Boost from Github:
>
> git clone --recurse-submodules https://github.com/boostorg/boost
>
> 2. Clone the Mustache library into the Boost tree:
>
> cd boost/libs
> git clone https://github.com/pdimov/mustache
> cd ..
>
> 3. Build b2:
>
> ./bootstrap.sh
>
> (We assume Linux and g++ from now on. On Windows,
> it's just `booststrap`.)
>
> 4. Generate the header links in the boost/ directory:
>
> ./b2 headers
>
> 5. Build the Mustache library and its dependencies (e.g. JSON):
>
> ./b2 --with-mustache
>
> This will place the compiled libraries into the stage/lib
> directory. It should contain libboost_container.a/.so,
> libboost_json.a/.so, and liboost_mustache.a/.so.
>
> You can now build and run the Mustache examples by using e.g.
>
> g++ libs/mustache/example/html.cpp -o html -I . -L stage/lib
> -lboost_mustache -lboost_json
>
> ./html
>
> _______________________________________________
> Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost