JSHON(1) | 1 (jshon manual) | JSHON(1) |
jshon
— JSON
parser for the shell
jshon |
-[P|S|Q|V|C|I|0] [-F path] -[t|l|k|u|p|a] -[s|n] value -[e|i|d] index |
jshon
parses, reads and creates JSON. It
is designed to be as usable as possible from within the shell and replaces
fragile adhoc parsers made from grep/sed/awk as well as heavyweight one-line
parsers made from perl/python.
jshon
loads json text from stdin, performs
actions, then displays the last action on stdout. Some of the options output
json, others output plain text summaries. Because Bash has very poor nested
datastructures, jshon
does not return the JSON as a
native object as a typical library would. Instead
jshon
retains a history of edits in a stack, and you
manipulate the topmost JSON element.
Each action takes the form of a short option. Some require
arguments. While many instances of jshon
can be
piped through each other, actions should be chained sequentially to reduce
calls. All examples use this json sample:
{"a":1,"b":[true,false,null,"str"],"c":{"d":4,"e":5}}
jshon [actions] < sample.json
Most common read-only uses will only need several
-e
actions and one -a
in the
middle of them.
-t
jshon -t -> object
-l
jshon -l -> 3
-k
jshon -k -> a b c
-e
index
jshon -e c -> {"d":4,"e":5}
-a
-a
calls can
be nested, though the need is rare in practice.
jshon -e b -a -t -> bool bool null string
-s
value
jshon -s "back\slash" -> "back\\slash"
-n
value
jshon -n object -> {}
-u
jshon -e b -e 3 -u -> str
-p
jshon -e c -e d -u -p -e e -u -> 4 5
-d
index
jshon -d b -> {"a":1,"c":{"d":4,"e":5}}
-i
index
jshon -e a -i a -> the orginal json
jshon -s one -i a -> {"a":"one", ...}
Arrays are handled in a special manner. Passing integers will
insert a value without overwriting. Negative integers are acceptable, as
is the string 'append'. To overwrite a value in an array: delete the
index, -n/s
the new value, and then insert at
the index.
jshon -e b -d 0 -s q -i 0 -> {"b":"q",false,null,"str"}
There are several meta-options that do not directly edit json. Call these at most once per invocation.
-F
<path>
-P
-S
-Q
-V
jshon
running several times slower while using
several times more memory. However by-value is safer than by-reference and
generally causes less surprise. By-reference is enabled by default because
there is no risk during read-only operations and generally makes editing
json more convenient.
jshon -e c -n 7 -i d -p -> c["d"] == 7
jshon -V -e c -n 7 -i d -p -> c["d"] == 5
jshon -V -e c -n 7 -i d -i c -> c["d"] == 7
With -V
, changes must be manually
inserted back through the stack instead of simply popping off the
intermediate values.
-C
-I
-0
--version
jshon
always outputs one field per line.
Many unix tools expect multiple tab separated fields per line. Pipe the
output through 'paste' to fix this. However, paste can not handle empty
lines so pad those with a placeholder. Here is an example:
jshon ... | sed 's/^$/-/' | paste -s -d '\t\t\n'
This replaces blanks with '-' and merges every three lines into one.
There are more and more tools that produce json output. Often
these use a line-oriented json/plaintext hybrid where each line is an
independent json structure. Sadly this means the output as a whole is not
legitimate json. Either loop though the data line by line (calling
jshon
once for each line) or convert it to a
legitimate json array. For example:
while read line; do jshon <<< "$line"; done < <(journalctl -o json)
journalctl -o json | sed -e '1i[' -e '$!s/$/,/' -e '$a]' | jshon
If you care about extremely short one liners, arguments can be
condensed when it does not cause ambiguity. The example from
-p(op)
can be golfed as follows:
jshon -e c -e d -u -p -e e -u == jshon -ec -ed -upee -u
I do not recommend doing this (it makes things much harder to understand) but some people golf despite the consequences.
jshon
can create json by passing an empty
object as input:
jshon -s one -i a <<< "{}"
jshon
was written by Kyle
Keen ⟨keenerd@gmail.com⟩ with patches from
Dave Reisner ⟨d@falconindy.com⟩,
AndrewF (BSD, OSX, jsonp, sorting), and
Jean-Marc A (solaris).
Numerous! Floats may lose precision. Could be more convenient to use. Documentation is brief.
September 1, 2013 | Debian |