Re: [mustache] The docs

From: Peter Dimov (pdimov_at_[hidden])
Date: 2023-02-07 15:00:06

Andrzej Krzemienski wrote:
> 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.

You are right, the MVP in this case turned out to be too M. I should add a
documentation section that describes the Mustache syntax.

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

These are described here: https://github.com/mustache/spec

> 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?

At the moment the supported data sources are json::value and types
convertible to json::value via json::value_from. What these types are is
explained here:

https://www.boost.org/doc/libs/1_81_0/libs/json/doc/html/json/conversion.html

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

I'm not sure I understand this question. Do you mean things like

{{#foo}}
  {{#foo}}
    {{foo}}
  {{/foo}}
{{/foo}}

?

If so, the way this works is that every element of data["foo"] is pushed to
the top of the so-called "context stack", where entities are looked up. If
this element itself contains a member "foo", this member will be used for
the nested {{#foo}}. (If not, the parent "foo" will be used.)