Human-readable description of the decoding steps

[baltpeter]

We need to explain the decoding steps on the site. In #1, I have already implemented a pseudo code rendering of them:

But we also want to describe them as continuous text.

[baltpeter]

Here's my go at what the description for the steps from the parent comment might look like:

1. Parse (the request body) as JSON.
2. Get the property at JSONPath batch_app_id in (the return value of line 1). Store that in (the result for the body at batch_app_id).
3. Parse (the property at JSONPath batch in the return value of line 2) as JSON.
4. Get the property relative_url for every element in (the return value of line 3).
5. Parse (the return value of line 4) as a query string. Store that in (the result for the body).

The values in parentheses are "blanks". The sentence needs to work with an arbitrary "identifier" put there.

There's three categories of identifiers that we can encounter, and here's how I would put those into text:

• properties from the request (i.e. the input): the request body/the property at JSONPath a.b.c in the request path/the request query string
• variables (temporary values only used in the decoding process but not returned at the end): the return value of line 2/the property at JSONPath a.b.c in the return value of line 3
• the result object, grouped by context: the result for the request body/the result for the request path at a.b.c

I'm pretty happy with this concept, I think that should work for just about anything and it reads okay.
I don't even want to think about how we would translate that, though…

[baltpeter]

Oh, actually, I think we might need to abandon the idea of replacing temporary variable names with "the return value of line n". I'm not sure whether that's possible since we allow writing to arbitrarily nested paths within variables. Consider (a bit contrived, but just to demonstrate what I'm thinking):

b = base64Decode(body)
b.a.c = something(b.a.c)
b = parseJson(b)
b.a.c = parseQueryString(b.a.c)
res.body.b.a = something(b.a)

Generating a description for b.a.c in line 4 would already be annoying, but still doable. We'd have to walk backwards from that line and find the first instance where any prefix of b.a.c is written to. So, it would have to be "the property at JSONPath a.c in the return value of line 3", since that overrides the b.a.c = ... from line 2.

But for b.a in line 5, it's really not clear what the description should even be. It's a combination of the return values of lines 3 and 4…

While I'm quite sad about that, I think we need to stick with "the variable something", at least for now.

[baltpeter]

OK, the very first (and basic) implementation is done in 9e0c572:

Currently, the identifiers are just pasted in as-is.

[baltpeter]

And now we also have identifier descriptions:

That genuinely wasn't too bad, even though I implemented it as Hugo templates.

[baltpeter]

One slight improvement:

can be a little less verbose and robot-y:

[baltpeter]

Mostly fixed with #1 but translations are still pending.