On Sat, Feb 4, 2023 at 7:56 PM Klemens Morgenstern via Boost wrote:

Boost.Mustache is an implementation of Mustache templates in C++11.

I cloned this bad boy into ${BOOST}/libs and then tried to build a Visual Studio Solution for it with: $ cmake -G "Visual Studio 16 2019" -A x64 -B bin64 Unfortunately this failed, and I got a bunch of errors like this: CMake Error at CMakeLists.txt:10 (add_library): Target "boost_mustache" links to target "Boost::config" but the target was not found. Perhaps a find_package() call is missing for an IMPORTED target, or an ALIAS target is missing? Then I was advised by the author to use this command line from the root: cmake -G "Visual Studio 16 2019" -A x64 -B libs/mustache/bin64 -DBOOST_INCLUDE_LIBRARIES=mustache -DBUILD_TESTING=ON This also produced an error: CMake Error: The source "C:/Users/vinnie/src/boost/CMakeLists.txt" does not match the source "C:/Users/vinnie/src/boost/libs/mustache/CMakeLists.txt" used to generate cache. Re-run cmake with a different source directory. Tried adding the path to the lib: cmake -G "Visual Studio 16 2019" -A x64 -B libs/mustache/bin64 -DBOOST_INCLUDE_LIBRARIES=mustache -DBUILD_TESTING=ON libs/mustache Same result. Well I deleted all the cached artifacts and then used this line cmake -G "Visual Studio 16 2019" -A x64 -B bin.v2/vs/mustache -DBOOST_INCLUDE_LIBRARIES=mustache -DBUILD_TESTING=ON libs/mustache Finally I got a Visual Studio solution with some projects in it (see attached image). It builds but the solution and projects have some cosmetic issues: * Every solution built from the root has the same name Boost.sln * Every Visual Studio window that opens Boost.sln has the title "Boost" (can't tell which is which) * mustache .vcxproj files have unnecessary nesting. "Header Files" folder then "boost" then "mustache". * dependencies are thrown together with the library-specific projects It works, but does not bring me joy. Thanks

Hi to everyone. Sorry, I'm a lurker of the mailing list and I almost never reply, but I've a question. Mustache is a library that needs at least C++11, while in another thread (Dropping C++03 support again) you're talking about dropping the support for C++03. But it means that now it's supported, so this library does not satisfy the requirement to be usable by C++03 compilers. What do you do in this case? The C++03 support is needed only for existing libraries or also for new ones? I'm asking because I've some idea for libraries and I'd like to propose one of them someday, but I need to know if they can satisfy the compiler requirements (I usually work only with modern compilers). What do you do with compiler support in this case? Daniele Lupo -----Messaggio originale----- Da: Boost Per conto di Klemens Morgenstern via Boost Inviato: domenica 5 febbraio 2023 04:56 A: boost@lists.boost.org Cc: Klemens Morgenstern Oggetto: [boost] Review of mustache starts today. 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

On Sat, Feb 4, 2023 at 9:56 PM Klemens Morgenstern via Boost wrote:

The formal review of the mustache starts today, Sunday the 5th, and ends next week on Tuesday the 14th.

While I would like to do a review of this library I'm not going to have the time within that time frame. As I'm double booked with work and the WG21 meeting. Can the review be extended to the end of next week? -- -- René Ferdinand Rivera Morell -- Don't Assume Anything -- No Supone Nada -- Robot Dreams - http://robot-dreams.net

On Sat, Feb 4, 2023 at 7:56 PM Klemens Morgenstern via Boost 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/abb722981d1adfc37524abed87c8bb88... 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-esca... * 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

I wanted to raise a concern on allocations before emitting my review. I've gone ahead and modified the html.cpp example to install a "spying" memory_resource as a quick and dirty way of visualizing allocations. I've refactored the code to something like this: // Let's call this the "init" section boost::json::value vars = boost::json::value_from(ref, spy_ptr); boost::json::value partials ( { { "header", header }, { "footer", footer }, { "item", item }, { "body", body } }, spy_ptr ); // "renderer_ctor" section boost::mustache::renderer rd (std::move(vars), std::move(partials), spy_ptr); // "parsing" section rd.render_some( html, dummy ); rd.finish( dummy ); This yielded the following results on allocations: section | total bytes | total allocations ------------------------------------------------- init | 1550 | 31 renderer_ctor | 1582 | 32 parsing | 1900 | 39 I was surprised by the number of allocations that the actual parsing does. Is this because renderer::render_some must assume that the input buffer may not outlive the actual parsing? If I am not mistaken, renderer_ctor's allocations happen because value_from is invoked unconditionally, even if a json::value&& is passed in, which yields in a copy. My other point to note is about HTML escaping. I want to note this point as a reference for other reviewers, as the author is already aware of this. Some special characters should be HTML encoded, additionally to the ones that are being escaped today. I've reviewed other Mustache libraries looking for how did they handle this topic and whether they had any known vulnerability. The most active one seems the JavaScript one (https://github.com/janl/mustache.js). Looking into the Synk vulnerability database, I've found https://security.snyk.io/vuln/npm:mustache:20151207 (CVE-2015-8862), which leads to XSS exploits and does affect Boost.Mustache, too. Two exploits are possible: * The backtick character seems to have special meaning in ancient versions of IE (https://html5sec.org/#59, https://github.com/janl/mustache.js/pull/388) * When using HTML unquoted attributes (e.g. <a href={{user_data}}>), escaping the equal sign can mitigate the risk of attribute injection. (IMHO attributes without quotes make kittens die, but this is listed as a vulnerability). The JavaScript library performs this replacement: * Backtick is replaced by ` * Equal sign is replaced by = They also escape the forward slash (#x2f;). I haven't found a vulnerability to point you too, but I guess that could be added as additional hardening, if you like. Many thanks, Ruben.

On Sun, 5 Feb 2023 at 04:56, Klemens Morgenstern via Boost wrote:

The formal review of the mustache starts today, Sunday the 5th, and ends next week on Tuesday the 14th.

Hi all, This is my review of Boost.Mustache. First of all, thanks Peter for submitting the library, and Klemens for volunteering as review manager.

- Does this library bring real benefit to C++ developers for real world use-case?

This is a utility library, and as such I do believe it has a place in Boost. Although Mustache is not super-popular, it comes up in certain contexts. I think having a robust Mustache engine, compatible with Describe and JSON, brings benefits to users.

- Do you have an application for this library?

Not right now. I'm thinking of writing a PoC pentesting software which may require templating HTTP requests with a list of payloads. If that happens to be the case, I'd use this library for that.

- Does the API match with current best practices?

It has a very small API surface, which I am really glad to see. It uses JSON as input format for data, which has both advantages (it's simple) and disadvantages (it doesn't allow to implement lambdas, it's not that extensible, and in its current form, it requires a lot of copying). I value simplicity a lot, so I'm alright with using JSON. However, I think the last point should be solved somehow. Template data is purely read-only, and efficiency should be a goal in a library like this. For these reasons, an API that allows the user to pass input data with minimal copies should exist. The partials argument doesn't seem to have the right type, as it must be a mapping from string to string, and the API declares it as a JSON object. If I'm not mistaken, by using JSON you're forcing the usage of UTF-8 for the input document. I think this is perfectly fine, but it should be documented. It may be worth exploring the option of providing a renderer::reset method that allows to recycle the same renderer, improving memory re-use. Is there any use case for passing a different output_ref to renderer::render_some and renderer::finish? If there isn't, output_ref could be passed to renderer's constructor.

- Did you try to use it? What problems or surprises did you encounter?

I've built the library, the tests and the examples with b2, Linux, gcc11 and with cmake, Linux, clang15 and libc++ with no problems. I had to add the example manually to the CMakeLists.txt, as cmake doesn't currently build the examples (the author is already aware of that). I've tried to break the library in every possible way I've imagined (especially with buffer overruns and XSS payloads) and I have failed, which is good. As described in previous emails, I found a couple of possible escaping-related problems that can constitute vulnerabilities. These are described in https://github.com/pdimov/mustache/issues/6 and should be easy to fix.

- What is your evaluation of the implementation?

I've navigated through most of it using a debugger, and I think it's fine. It seemed to me that it performed a lot of copies, so I performed some measurements. I measured the number and size of allocations performed through the storage_ptr's and I found it higher than expected. Input data being converted into json::value is one source for such allocations, and should be solved by the view-based API. The renderer class also performs a lot of copying while rendering. These allocations, however, seem to be avoidable without changing the interface. I've raised https://github.com/pdimov/mustache/issues/7 to address it.

- Is the documentation helpful and clear?

I've found reading the source code more helpful. This is what I would add: * A discussion section, similar to what URL does. I would include these sections: * Introductory usage example. Without Boost.Describe (as plain JSON is easier to understand for a newcomer). I would include some explanations on the Mustache features being used. I don't think a full section on Mustache is necessary, but saying "this is a tag", "this is a partial" would be useful. * Using the library with user-defined types - with Describe now. * Using renderer to render with render_some. * Using string types as output. * A section on escaping (the magic word "security" may help here). All other libraries have a bunch of open issues by users not understanding that escaping happens by default. Also, I would describe what "HTML escape" means in this context (the spec doesn't say it and different libs do different things). * A proper reference section, with links and human-readable explanations. Taking output_ref as an example, I would like to see: * A URL for output_ref, so you can reference it from other places in docs. * A human-readable explanation (e.g. "a polymorphic reference to either a string or a I/O stream that can be used to output a rendered Mustache template"). * Explanations of what St and Os mean (ideally, pointing to its own section). * When you reference other functions/classes (e.g. renderer in the render() description), please do provide links to them. Otherwise, the user ends up having to CTRL+F it, which is extremely frustrating (real story from mp11). * Doxygen comments (or similar). Pressing F12 and seeing comments on the function you're using helps. * Comparison to other libraries. Specially to the one listed by the official Mustache page, even if it seems to be unmaintained. * The documentation should state the exact version of the Mustache API that it's implementing. It would be good to briefly describe what "mandatory features" are in the spec, what optional features aren't implemented but are in the roadmap, and which ones won't happen. The spec is very difficult to read as a user, so don't expect people will read it.

- How much effort did you put into your evaluation? A glance? A quick reading? In-depth study?

I've dedicated around 10h to this review. I've read the docs, the Mustache discussion and spec, reviewed the Node library, built and run the examples, tried to break them, navigated through the impl via debugger and done the allocation study.

- Are you knowledgeable about the problem domain?

I briefly met Mustache when working with a swagger-codegen project (https://github.com/swagger-api/swagger-codegen). Given an OpenAPI spec, swagger-codegen generates stub code for you in different languages. I haven't used it from C++ or in production.

Please explicitly state that you either *accept* or *reject* the inclusion of this library into boost.

My recommendation is to **CONDITIONALLY ACCEPT** this library into Boost, with the following conditions: 1. The partials argument must be typed according to the data structure it requires. 2. A view-based API should be added or, at least, should be addable without breaking changes. 3. The found vulnerabilities must be fixed. 4. Proper documentation must be written. Some other minor points (these are not acceptance conditions): * The link to mustache.github.io in the docs is HTTP instead of HTTPS. * Calling a type in the examples "reference" may not be the best idea. I stared at it thinking "why is this not dangling" until I figured out what "reference" meant in that context. * Is the config header supposed to be included by users? If not, move to detail/ * Is output_ref::write supposed to be called by users? If not, make it private. * Not being able to load the CML without the superproject contributes to the feeling of living in a monolith. * Your copyright is out of date ;) Regards, Ruben.

On Sat, Feb 4, 2023 at 9:56 PM Klemens Morgenstern via Boost wrote:

Review ========

Please explicitly state that you either *accept* or *reject* the inclusion of this library into boost. The accept can be conditional.

The documentation is not usable as it is. There's just too much missing to use the library past the simplest use cases. Having said that, the implementation is good and up to par for Boost, AFAICT. My conclusion is to CONDITIONALLY ACCEPT. The condition being to write all the missing documentation.

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

I spent about 4 hours in total reviewing the library. I read the documentation, playing around with the examples, and reading the code. I made some minor changes to the build files to incorporate into my ongoing work to adjust the Boost libraries to be fully modular with B2. The project built without warnings, errors, or any problems at all. So kudos for that.

Some questions to consider:

- Does this library bring real benefit to C++ developers for real world use-case?

Yes. Some form of templating output is ubiquitous if one needs to do any form of input processing to generate textual output.

- Do you have an application for this library?

Not immediately. I have some near future use cases for tooling that I was considering something like this. Specifically in generating data matching tooling metadata (compile commands data, package description data, compiler response data, for ecosystem IS reference implementations). My use cases required being able to exchange the output format without changing the input so that I could output XML, JSON, YAML, etc by only changing the templates (ideally).

- Does the API match with current best practices?

What I understand of the API, yes. But that's just the "render" and using Json.

- Is the documentation helpful and clear?

No. While I'm okay with the documentation only referencing the mustache spec. I'm not fine with the essentially zero explanation of what the facility does. Some questions I had while reading the documentation: * How would it work if I don't use Boost.Describe? * Should I know where in the Json docs I should look for further answers? * How do I use "render_some"? * Why should I care about the "output_ref" API? I.e: What's for other than it's the argument to "render_some"? I did figure out most of the answers to the questions after reading the test sources and implementation. But one shouldn't need to do that to use a library.

- Did you try to use it? What problems or surprises did you encounter?

No. Looking at the examples and tests was enough for me to understand what was going on. And more importantly if it would fit the use cases I'm looking to solve.

- What is your evaluation of the implementation?

It is clean and straightforward. I learned some things about core::string_view I didn't know (which I might use in B2 since I copied that implementation for use there). While the comments are minimal. They are also sufficient. -- -- René Ferdinand Rivera Morell -- Don't Assume Anything -- No Supone Nada -- Robot Dreams - http://robot-dreams.net

Are you knowledgeable about the problem domain? I have been using several text templating engines written in Python in

This is my review of Boost.Mustache. 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.

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

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. 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 :

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