Git, JSON and Markdown Walk Into Bar

<pre><code> var , var2 , var3 , var4 </code></pre>

  [ "or"
  , "alternatively"
  , [ "the"
    , "first"
    , "item"
    ]
  , "could"
  , "behave"
  , "differently"
  ]

Comma-first syntax is especially convenient in SQL, which has the forbidden-trailing-comma problem and several analogous problems. In C if I have a long Boolean conjunction

  if (unpleasantly long boolean expression &&
      another unpleasantly long boolean expression &&
      yet another unpleasantly long boolean expression) {

  if (  unpleasantly long boolean expression
     && another unpleasantly long boolean expression
     && yet another unpleasantly long boolean expression
     ) {

  where unpleasantly long boolean expression
    and another unpleasantly long boolean expression
    and yet another unpleasantly long boolean expression

In Meta5ix http://www.canonical.org/~kragen/sw/dev3/meta5ixrun.py I experimented with using item initiators for rules in a grammar, like Markdown uses for bulleted lists. I'm not pleased with the rest of the syntactic decisions I tried in Meta5ix, but I do think that one was a good tradeoff; here's about a quarter of the Meta5ix compiler:

    - terms: term ["," {continue $choice} term] @choice
    - term: (factor {else $seq}, output) [factor {assert}, output] @seq
    - factor: string {literal $it}
           , "(" terms ")"
           , "[" @many terms {continue $many} "]"

    let rec walk (s : env) = function
      | Vart (Var x) when Env.mem x s -> walk s (Env.find x s)
      | u -> u

I've been recently using dyff [0] to diff YAMLs in an order invariant way, and it's been absolutely liberating. Couldn't help with version control, but it's still night and day.

[0] https://github.com/homeport/dyff

I prefer leading commas to having a final comma with an empty clause, though some people hate that and they don't really solve all the final-entry issues (they address some of them, but others are just moved to being first-entry issues).

The convenience it offers for diffing is just a manifestation of the positive interaction with grammars and language tools. The convention of humans using trailing commas in lists, along with one item per line, is relatively new, though. Stylistically, this used to be frowned upon as long definition lists made source files longer, slower to scroll through, and worsened code locality from the perspective of someone using, e.g., a 25 row terminal.

It still looks good even without any formatting! (And btw. I thought that was the intention of markdown …)

That is not as practical with markdown though, as you are working with a limited set of practical character combinations.

> Styles, like words, can have several meanings

This is one of the reasons why there are many markdown alternatives that behave slightly differently: not everyone writes plain text mark-up with the same intentions.

This isn't something you can solve with a single markdown version, so we have to accept that each could, and probably will, work a little differently.

    { foo :"bar" baz :"bak" quux :[ a,b,c,d ] lol :9.7E+42 }

> Commas exist mostly to help JSON be human-readable. They have no real syntactic purpose as one could make their own notation without the commas and it'd work just fine.

https://stackoverflow.com/a/36104693

Elsewhere such commas can be optional, e.g. in clojure: https://guide.clojure.style/#opt-commas-in-map-literals

https://orgmode.org/worg/org-contrib/babel/

I'm more partial to YAML for readability, but I don't think JSON configs are an awful anti pattern.

> It's not code.

package.json has a field literally called 'scripts' where the values are shell one-liners.

If I have a structure like this JSON:

  {
    "foo": "bar",
    "nested": {
      "nested_foo": "nested_bar",
    }
  }

  <foo>
    bar
  </foo>
  <nested>
    <nested_foo>
      nested_bar
    </nested_foo>
  </nested>

  <foo>
    bar
  </foo>
  <nested nested_foo="nested_bar"/>

To me, JSON is nice because it's essentially the minimum viable way of encoding a C-style struct (floating point behavior notwithstanding.) XML has extras like attributes, schemas, and DTDs, which may be useful, but they come at the cost of having additional syntax (<!DOCTYPE ...>, etc), which is auxiliary to the goal of encoding data structures, and thus makes it no longer as minimal.

To me, JSON's approach of having a separate out-of-band definitions of schema (e.g. JSON schema) is the better approach because it's less opinionated, you only pay for it when you need it, and it doesn't require separate syntax. Leave validation to a validation step, my data is my data.

I had been tasked at least several times in my past jobs to develop XSLT scripts to transform data into user-readable content. I don't know of anyone that uses XSLT today and I have no idea if there is a JSON equivalent.

Easier to write than JSON.

But weirdly harder to get right in other ways, especially for nesting things.

Almost made the mistake of becoming simple to parse.

Alas, defeat was again snatched from the jaws of victory on that one…

1: Standardization was made by committee lovers and/or architecture astronauts leaving us with overly convoluted (sometimes to fit lacklustre object models in early OO languages) and complex ways of working.

2: Complexity that introduced security vulnerabilities

Sure, there was some great tooling available, but how much of it was needed because all complexity made it hopeless to work with without the tooling?

I used it for configuration and serialization in some projects, and it was actually great but I almost always diverged from the bloated norms and defaults for readability/writeability (that made it a bit annoying to specify serialization rules).

I mean, why did people prefer?

  <object><property name="somename"><int32>123</int32></property></object>

  <object somename="123"/>

JSON was and is so far the best popular compromise between "just plain data" and "some" structure to make automated processing non-painful.

Also as an improvement over XML collections (do you created a container element to specify container target leading to bloat or just map some of the sub-elements to specific collections and hope you don't run into ambiguities?) is that collections are just specific lists to a property.

The biggest drawback of JSON is that we never had a way to handle type specializations/subtyping but had we done that we might have not gotten the universal acceptance across languages.

Yes, comments but whenever you need that you can make a single-line regexp to strip a useful subset of them without affecting anything by the standard by removing matches of

  /^\s*\/\/[^\r\n]*/mg

But you are being mean. Also, the guy who wrote the article is no amateur, but a seasoned veteran who's likely been storing floats in files for decades. Check him out, you might be surprised.

https://www.grumpygamer.com/about/

  {
    "uhh": "nope"
  }