NAME

     jshon — JSON parser for the shell

SYNOPSIS

     jshon -[P|S|Q|V|C|I|0] [-F path] -[t|l|k|u|p|a] -[s|n] value -[e|i|d] index

DESCRIPTION

     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.

ACTIONS

     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  (type) returns string, object, array, number, bool, null

           jshon -t -> object

     -l  (length) returns an integer.  Only works on string, object, array.

           jshon -l -> 3

     -k  (keys) returns a newline separated list of keys.  Only works on object.

           jshon -k -> a b c

     -e index
         (extract) returns json value at "index".  Only works on object, array.  The index of an
         array is an integer.

           jshon -e c -> {"d":4,"e":5}

     -a  (across) maps the remaining actions across the selected element.  Only works on objects
         and arrays.  Multiple -a calls can be nested, though the need is rare in practice.

           jshon -e b -a -t -> bool bool null string

     -s value
         (string) returns a json encoded string.  Can later be (-i)nserted to an existing
         structure.

           jshon -s "back\slash" -> "back\\slash"

     -n value
         (nonstring/number) returns a json element.  Can later be (-i)nserted to an existing
         structure.  Valid values are 'true', 'false', 'null', 'array', 'object', integers and
         floats.  Abbreviations t, f, n, [] and {} respectively also work.

           jshon -n object -> {}

     -u  (unstring) returns a decoded string.  Only works on simple types: string, int, real,
         boolean, null.

           jshon -e b -e 3 -u -> str

     -p  (pop) pops the last manipulation from the stack, rewinding the history.  Useful for
         extracting multiple values from one object.

          jshon -e c -e d -u -p -e e -u -> 4 5

     -d index
         (delete) removes an item in an array or object.  Negative array indexes will wrap
         around.

           jshon -d b -> {"a":1,"c":{"d":4,"e":5}}

     -i index
         (insert) is complicated.  It is the reverse of extract.  Extract puts a json sub-element
         on the stack.  Insert removes a sub-element from the stack, and inserts that bit of json
         into the larger array/object underneath.  Use extract to dive into the json tree,
         delete/string/nonstring to change things, and insert to push the changes back into the
         tree.

           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"}

NON-MANIPULATION

     There are several meta-options that do not directly edit json.  Call these at most once per
     invocation.

     -F <path>
         (file) reads from a file instead of stdin.  The only non-manipulation option to take an
         argument.

     -P  (jsonp) strips a jsonp callback before continuing normally.

     -S  (sort) returns json sorted by key, instead of the original ordering.

     -Q  (quiet) disables error reporting on stderr, so you don't have to sprinkle "2> /dev/null"
         throughout your script.

     -V  (by-value) enables pass-by-value on the edit history stack.  In extreme cases with
         thousands of deeply nested values this may result in 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  (continue) on potentially recoverable errors.  For example, extracting values that don't
         exist will add 'null' to the edit stack instead of aborting.  Behavior may change in the
         future.

     -I  (in-place) file editing.  Requires a file to modify and so only works with -F.  This is
         meant for making slight changes to a json file.  When used, normal output is suppressed
         and the bottom of the edit stack is written out.

     -0  (null delimiters)  Changes the delimiter of -u from a newline to a null.  This option
         only affects -u because that is the only time a newline may legitimately appear in the
         output.

     --version
         Returns a YYYYMMDD timestamp and exits.

OTHER TOOLS

     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

GOLF

     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.

CREATING JSON

     jshon can create json by passing an empty object as input:

      jshon -s one -i a <<< "{}"

AUTHORS

     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).

BUGS

     Numerous!  Floats may lose precision.  Could be more convenient to use.  Documentation is
     brief.

                                        September 1, 2013