Re: [mustache] The docs

From: Andrzej Krzemienski (akrzemi1_at_[hidden])
Date: 2023-02-07 20:21:22

wt., 7 lut 2023 o 15:31 Andrzej Krzemienski <akrzemi1_at_[hidden]> napisał(a):

> Hi Everyone,
>
> I wanted to share my initial thoughts after reading the docs for the
> proposed Boost.Mustache.
>
> If some library docs said "I am implementing JSON", I more-less know what
> to expect, because JSON is popular, I used it, so one can reliably predict
> what the library delivers.
>
> This is not the case with Mustache. It is the first time I have heard this
> name. Apparently, it is a less popular thing. Therefore, I would expect
> some more introduction than just an external link. The linked page also
> doesn't contain sufficient information  but further links. For instance to
> https://mustache.github.io/mustache.5.html, but this information also
> doesn't help me find answers to my questions:
>
> 1. What is considered an "optional part" of mustache? Boost.Mustache says
> it only implements the non-optional parts, but docs in mustache(5) do not
> indicate the optional parts.
>
> 2. It is clear to me that the procedure takes a template (with mustaches)
> and the data to be replaced. But what is the range of the acceptable
> formats of this data? The examples show that it is JSON, but does it have
> to be JSON? Boost.Mustache docs say it could be 'described' classes? But is
> that all? How about Boost.PropertyTree? What does the specification for
> Mustache say about it?
>
> 3. I do not see any specification (neither in Boost.Mustache docc, nor in
> the linked  mustache(5)) for what is the required behavior when I have
> nested mustashes with the same name, or a JSON file with nested elements of
> the same name.
>
> Or did I miss this description?
>

Some further notes on the documentation

https://pdimov.github.io/mustache/doc/html/mustache.html#overview_description
"At the moment it doesn’t implement any of the extensions.".

This seems to imply that in the future the plan is to support the
extensions. The only extension that I am aware of is lambdas. But I do not
see how lambdas can be implemented in the library if it is using
boost::json for providing data.

Lambdas are not part of the JSON format at all. Which indicates that
mustache templates do not typically use JSON for providing the data.
This SO question shows that other languages pass data (including lambdas)
directly.

https://stackoverflow.com/questions/16950587/how-does-one-use-lambdas-on-the-mustache-js-demo-page

Putting JSON as the only data type seems to set the limits on future
extensions. Or is the plan to extend the data formats beyond JSON?

Next, going back to the nested objects, in the description of renderer
constructor we have:
(https://pdimov.github.io/mustache/doc/html/mustache.html#ref_constructor)

Converts data to boost::json::value by boost::json::value_from(data, sp)
and stores it at the top of the *context stack*.

It refers to "context stack",  but this term is never explained.

Next, in the same section we have:

Converts partials to boost::json::object by boost::json::value_from(partials,
sp).as_object() and stores it.

It is far from obvious to me why the 'partials' should be converted to a
json::value. Conceptually, you should only require a map of names onto
texts. But json::value allows too much. According to the specs, the
following should is valid:

boost::mustache::render( html, std::cout, ref,
        { {"header", header}, {"footer", 1}, {"item", true}, {"body",
nullptr} } );

But it shouldn't be valid. Or amI wrong?

Regards,
&rzej;