source | all docs for version 0.7.pre8 | all versions | oilshell.org

JSON in Oil

JSON is a popular textual interchange format, and a Unix shell needs support for it.

This page describes Oil's JSON support as of December 2019 (version 0.7.pre8). (Note: the help builtin will eventually provide a shorter reference.)

It's likely we'll expand JSON support based on user feedback.

JSON support lives under the json builtin, which has read and write subcommands.

Oil's data structures are like those in Python and JavaScript, so the correspondence between text and structured data is natural.

json read parses from stdin

Usage:

json read FLAGS* VAR_NAME

Flags:
  None for now, but there likely will be one to skip UTF-8 validation.

Examples:

$ cat stats.json
{"count": 42}

# myvar is automtically created in local scope
$ json read :myvar < stats.json

# use = to pretty print it
$ = myvar   
(Dict)    {'count': 42}

# json read can be at the end of a pipeline, e.g. 
echo '{"count": 42}' | json read :myvar

$ echo '[ "incomplete"' | json read :myvar < invalid.json
[ "incomplete"
 ^
json read: premature EOF

$ echo $?   # failure upon invalid parse
1

Notes:

• The usage is consistent with shell's read builtin, which reads a line from a file and splits it into variables.
• Variable names may be prefixed with the optional "sigil" :.
• Only one variable name can be passed.

json write prints to stdout

Usage:

json write FLAGS* VAR_NAME+

Flags:
  -indent=2     Indentation size
  -pretty=true  Whether to add newlines for readability

Examples:

# Oil is like JS in that keys don't require quotes
$ var d = {name: "bob", age: 42}

# by default, newlines are added for readability, with 2 space indentation
$ json write :d
{
  "name": "bob",
  "count": 42
}

$ json write -indent 4 :d
{
    "name": "bob",
    "count": 42
}

$ json write -pretty=F :d
{"name": "bob", "count": 42}

Notes:

• indent is ignored if pretty is false.
• The json builtin is part of the Oil language, so it uses Oil's flag syntax, which is based on Go's. In particular, boolean flags are written -pretty=F rather than -pretty F, but you can write -indent=4 or -indent 4.

Other Data Structures Can Be Printed as JSON

Oil arrays and shell arrays both serialize to a list of strings:

$ sharray=( foo.txt *.py )
$ json write :sharray
["foo.txt", "one.py", "two.py"]

$ var oilarray = @( foo.txt *.py )
$ json write :oilarray
["foo.txt", "one.py", "two.py"]

Bash-style associative arrays are like Dict[Str, Str]:

$ declare -A assoc=(["key"]=value)
$ json write :assoc
{"key": "value"}

Credits

Oil uses yajl under the hood.

(The Python build uses a fork of the py-yajl binding, which should be optimized away in the future.)