1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209
|
% JO(1) User Manuals
# NAME
jo - JSON output from a shell
# SYNOPSIS
jo [-p] [-a] [-B] [-v] [-V] [--] [ [-s|-n|-b] word ...]
# DESCRIPTION
*jo* creates a JSON string on _stdout_ from _word_s given it as arguments or read from _stdin_. Without
option `-a` it generates an object whereby each _word_ is a `key=value` (or `key@value`)
pair with _key_ being the JSON object element and _value_ its value. *jo* attempts to
guess the type of _value_ in order to create number (using _strtod(3)_), string, or null values in JSON.
*jo* treats `key@value` specifically as boolean JSON elements: if the value begins with `T`, `t`,
or the numeric value is greater than zero, the result is `true`, else `false`. A missing or
empty value behind the colon results in a `null` JSON element.
*jo* creates an array instead of an object when `-a` is specified.
When the `:=` operator is used in a _word_, the name to the right of `:=` is a file containing JSON which is parsed and assigned to the key left of the operator.
# TYPE COERCION
*jo*'s type guesses can be overridden on a per-word basis by prefixing _word_ with `-s` for _string_,
`-n` for _number_, or `-b` for _boolean_. The list of _word_s *must* be prefixed with `--`, to indicate
to *jo* that there are no more global options.
Type coercion works as follows:
word -s -n -b default
------------ ---------------- ------------ --------- ----------------
a= "a":"" "a":0 "a":false "a":null
a=string "a":"string" "a":6 "a":true "a":"string"
a=\"quoted\" "a":"\"quoted\"" "a":8 "a":true "a":"\"quoted\""
a=12345 "a":"12345" "a":12345 "a":true "a":12345
a=true "a":"true" "a":1 "a":true "a":true
a=false "a":"false" "a":0 "a":false "a":false
a=null "a":"" "a":0 "a":false "a":null
Coercing a non-number string to number outputs the _length_ of the string.
Coercing a non-boolean string to boolean outputs `false` if the string is empty, `true` otherwise.
Type coercion only applies to `key=value` words, and individual words in a `-a` array.
Coercing other words has no effect.
# EXAMPLES
Create an object. Note how the incorrectly-formatted float value becomes a string:
$ jo tst=1457081292 lat=12.3456 cc=FR badfloat=3.14159.26 name="JP Mens" nada= coffee@T
{"tst":1457081292,"lat":12.3456,"cc":"FR","badfloat":"3.14159.26","name":"JP Mens","nada":null,"coffee":true}
Pretty-print an array with a list of files in the current directory:
$ jo -p -a *
[
"Makefile",
"README.md",
"jo.1",
"jo.c",
"jo.pandoc",
"json.c",
"json.h"
]
Create objects within objects; this works because if the first character of value is an open brace or a bracket we attempt to decode the remainder as JSON. Beware spaces in strings ...
$ jo -p name=JP object=$(jo fruit=Orange hungry@0 point=$(jo x=10 y=20 list=$(jo -a 1 2 3 4 5)) number=17) sunday@0
{
"name": "JP",
"object": {
"fruit": "Orange",
"hungry": false,
"point": {
"x": 10,
"y": 20,
"list": [
1,
2,
3,
4,
5
]
},
"number": 17
},
"sunday": false
}
Booleans as strings or as boolean (pay particular attention to _switch_; the `-B` option disables the default detection of the "`true`", "`false`", and "`null`" strings):
$ jo switch=true morning@0
{"switch":true,"morning":false}
$ jo -B switch=true morning@0
{"switch":"true","morning":false}
Elements (objects and arrays) can be nested. The following example nests an array called _point_ and an object named _geo_:
$ jo -p name=Jane point[]=1 point[]=2 geo[lat]=10 geo[lon]=20
{
"name": "Jane",
"point": [
1,
2
],
"geo": {
"lat": 10,
"lon": 20
}
}
Type coercion:
$ jo -p -- -s a=true b=true -s c=123 d=123 -b e="1" -b f="true" -n g="This is a test" -b h="This is a test"
{
"a": "true",
"b": true,
"c": "123",
"d": 123,
"e": true,
"f": true,
"g": 14,
"h": true
}
$ jo -a -- -s 123 -n "This is a test" -b C_Rocks 456
["123",14,true,456]
Read element values from files: a value which starts with `@` is read in plain whereas if it begins with a `%` it will be base64-encoded:
$ jo program=jo authors=@AUTHORS
{"program":"jo","authors":"Jan-Piet Mens <jpmens@gmail.com>"}
$ jo filename=AUTHORS content=%AUTHORS
{"filename":"AUTHORS","content":"SmFuLVBpZXQgTWVucyA8anBtZW5zQGdtYWlsLmNvbT4K"}
Read element values from a file in order to overcome ARG_MAX limits during object assignment:
$ ls | jo -a > child.json
$ jo files:=child.json
{"files":["AUTHORS","COPYING","ChangeLog" ....
# OPTIONS
*jo* understands the following global options.
-a
: Interpret the list of _words_ as array values and produce an array instead of
an object.
-B
: By default *jo* interprets the strings "`true`" and "`false`" as boolean elements
`true` and `false` respectively, and "`null`" as `null`. Disable with this option.
-p
: Pretty-print the JSON string on output instead of the terse one-line output it
prints by default.
-v
: Show version and exit.
-V
: Show version as a JSON object and exit.
# BUGS
Probably.
If a value given to *jo* expands to empty in the shell, then *jo* produces a `null` in object mode, and might appear to hang in array mode; it is not hanging, rather it's reading _stdin_. This is not a bug.
Numeric values are converted to numbers which can produce undesired results. If you quote a numeric value, *jo* will make it a string. Compare the following:
$ jo a=1.0
{"a":1}
$ jo a=\"1.0\"
{"a":"1.0"}
Omitting a closing bracket on a nested element causes a diagnostic message to print, but the output contains garbage anyway. This was designed thusly.
# RETURN CODES
*jo* exits with a code 0 on success and non-zero on failure after indicating what
caused the failure.
# AVAILABILITY
<http://github.com/jpmens/jo>
# CREDITS
* This program uses `json.[ch]`, by Joseph A. Adams.
# SEE ALSO
* <https://stedolan.github.io/jq/>
* <https://github.com/micha/jsawk>
* <https://github.com/jtopjian/jsed>
* strtod(3)
# AUTHOR
Jan-Piet Mens <http://jpmens.net>
|