Add “json”, “toml” and “yaml” string functions

[begoon]

The API for all three functions is the same.

m := json(var, k1, k2, …, kn)

Each sub-index is either a string to index a sub-map or an integer to index a sub-list.

If the var is invalid for a given format or the index (k1, k2, …, kn) is not found, the function returns an empty string.

The examples below are for JSON but represent TOML and YAML, too, because of their semantic equality.

Assume the following input string with JSON:

s := '
{
    "a": 100,
    "b": ["1", "2", "3"],
    "c": {
         "c1": true,
         "c2": "ABC",
    }
}
'

All scalar values are converted to strings.

Proposed API, v1 -- variadic index and individual functions for each map representation

There are three functions: json(), yaml(), toml(). All three have the same parameters. The example below uses json.

v := json(s, "a") -> "100"
v := json(s, "b", 1) -> "2" // "1" is an array index
v := json(s", "c", "c1") -> "true" // booleans are converted to "true" and "false" strings
v := json(s", "c", "c2") -> "ABC"

v := json(s, "X") -> "" // not found
v := json(s, "c") -> "" // an incomplete index because "c" is also a map

Proposed API, v2 -- generic map type and a single string index:

There is one map() function for all three formats. The index is a single string with sub-indexes separated by a delimiter (the default is .).

map(input, format, index, delimiter = ".")

• "input" is an input string
• "format" is "json", "yaml" or "toml"
• "index" is a single string index with sub-indexes, separated by "delimiter"

v := map(s, "json", "a") -> 100

v := map(s, "json", "b.1") -> "2" // "1" is an array index
v := map(s, "json", "b:1", ":") -> "2" // "1" is an array index, "delimiter" is ":"

v := map(s, "json", "c.c2") -> "ABC", default delimiter "."
v := map(s, "json", "c:c2", ":") -> "ABC", "delimiter" is ":"

v := map(s, "json", "X") -> "" // not found
v := map(s, "json", "c") -> "" // incomplete/non-existant index

[casey]

Can you give some examples invocations, with arguments and output?

[begoon]

@casey I have added examples and split the proposal into two APIs.

[begoon]

Any thoughts on the design?

I am happy to take over the development.

[casey]

I think it's probably too complex of a function for me to be comfortable adding it. just has very strong backwards compatibility guarantees, so for a function like this, I would be worried that it wouldn't be ideal on the first try, but we wouldn't be able to fix it.

Also, the user could mimic this with the shell function and calls to jq.

I think that before this, I'd like to see user-defined functions, see #1059, which would let users easily write this as a custom function.