Greetings!

*** Hadmut Danisch [2024-03-13 00:53]:
>2. alternatively allow use of either YAML file format, because YAML is
>designed to be easy human-readible and easy human-editable

Absolutely not. Really, honestly, did you try using it? I dealt with it
for years in various projects and completely confident that it is the
worst format in terms of friendliness to human. I saw numerous times how
people (including me) just can not interpret and understand what they
see on the screen: is it a list of dictionaries, or vice versa, and
similar kind of questions arose. Sorry, but YAML is just insanely
complex to read and interpret by human, because of his rich set of
expressions.

* well-known "problem with Norway"

    countries:
    - GB
    - IE
    - FR
    - DE
    - NO

* just a version:

    python: 3.5.3
    postgres: 9.3

* just a surname:

    first name: Christopher
    surname: Null

* just a fear how all of that could be interpreted:

    server_config:
      port_mapping:
        # Expose only ssh and http to the public internet.
        - 22:22
        - 80:80
        - 443:443

      serve:
        - /robots.txt
        - /favicon.ico
        - *.html
        - *.png
        - !.git  # Do not expose our Git repository to the entire world.

      flush_cache:
        on: [push, memory_pressure]
        priority: background

* here is bet game:

    ipv4-address: 192.0.2.16
    ipv6-address: 2001:db8::210

I used YAML in NNCP and several our of my personal projects, because of
its ability to use templates and DRY your configuration file. But no, it
is unusable because of those complexities with rich interpretation and
abilities to expression yourself. I met too often how I and other people
just were not able to tell what is encoded in YAML. In JSON you clearly
see that "{}" gives your a dictionary, "[]" a list, '""' is about
strings, nothing more.

I think that YAML library's source code size was bigger than the whole
NNCP project. And not all libraries support all set of features
(equally) -- I saw that some of them did not support templates/references
and one of the YAML's killer-feature is lost. And there are many
revisions of YAML format itself. https://yaml.org/spec/1.2.2/ -- sorry,
but that is just pure insanity to call that amount of text needed to be
read by human as friendly to him. And without reading all of that: I
will shoot myself in the foot.

I also played with TOML format in NNCP. Do not remember did I leave the
commit with it in the source code tree. It looked much more easier and
simpler, but:

    [[foo.bar]]
    baz = 123

    [[foo.bar]]
    abc = 123

becomes:

    {
      "foo": {
        "bar": [
          {"baz": 123 },
          {"abc": 123 }
        ]
      }
    }

that is not-trivial to interpret in my opinion. Moreover those
"[[foo.XXX]]" can be distributed across the whole configuration file. It
is easy to deal by machine, but slightly more complex structures would
be impossible for humans to conveniently create. Simple
structures/configs are ok in TOML, but deeply nested like in NNCP were
just barely readable.

Maybe that is just because we are used to see all those "{}", "[]" in
languages like Python and in widespread JSON and it is matter of taste?
With TOML -- maybe. But YAML is just a no-no beast of complexity.

For safer YAML usage there is Strict YAML subset. Also you can just wrap
everything in quotes, to assure that it will be interpreted like a
string. But here you would make some kind of JSON out of YAML already.

>And, YAML is a common standard for configuration files.

Popularity is pretty bad measurement. Microsoft Windows and JavaScript
can be treated like standard (de-facto, by default) OS and programming
language. Even not talking about systemd and Docker.

>If not YAML, then regular JSON, because there's tools for it (like jq).

Exactly that is why I use Hjson: it is interoperable with all JSON-aware
tools. Its libraries are designed to convert it to/from JSON and then
using ordinary JSON tools. http://www.nncpgo.org/Configuration.html
contains a note, that Hjson can be trivially converted to JSON. That is
why NNCP includes third-party hjson-cli utility for that purpose.
Moreover, JSON is literally a valid subset of Hjson, so you can use it
directly without any conversion.

Anyway, none of those formats are truly convenient to be processed by
machine. Once I started to write integration tests for NNCP and even
with JSON it is pretty cumbersome to write all those *jq commands to
generate a JSON file with multiple nested structures. It is possible,
without any doubts, but not so easy, doing it with *jq utilities in
shell. That is why I added possibility to use directory layout for the
whole configuration: http://www.nncpgo.org/Configuration-directory.html
Basically, each dictionary becomes a directory, each key is a filename,
its contents is the value.

-- 
Sergey Matveev (http://www.stargrave.org/)
OpenPGP: 12AD 3268 9C66 0D42 6967  FD75 CB82 0563 2107 AD8A