Jsonprint

json_die¶

Print an error message to stderr and exit 1. Variant of die() for jsonprint. Note that in the parent script, extra logic may be necessary to die in subshells. See: https://gist.github.com/rawiriblundell/2dab6903848f73641652a8e95e872dcb

Arguments¶

• $1 (string): Error message

Exit codes¶

• 1: Always

Output on stderr¶

• Error message prefixed with '====> jsonprint exception:'

json_exception¶

Alias for json_die().

json_open¶

Emit an opening curly brace to denote the start of a JSON block.

Exit codes¶

• 0: Always

Output on stdout¶

• '{'

json_close¶

Emit a closing curly brace followed by a newline (for ndjson).

Exit codes¶

• 0: Always

Output on stdout¶

• '}\n'

json_comma¶

Emit a single comma.

Exit codes¶

• 0: Always

Output on stdout¶

• ','

json_decomma¶

Remove a trailing comma from stdin. Pipe input into this function. Use when you cannot avoid emitting a trailing comma on the last element.

Example¶

some_code | json_decomma

Exit codes¶

• 0: Always

Output on stdout¶

• Input with trailing comma removed

json_sanitise¶

Sanitise a string for use as a JSON key or value. Strips surrounding quotes, trailing ':' or '=', and leading/trailing whitespace. Accepts input as an argument or via stdin.

Arguments¶

• $1 (string): Optional: string to sanitise (reads from stdin if omitted)

Exit codes¶

• 0: Always

Output on stdout¶

• Sanitised string

json_sanitize¶

US-English spelling alias for json_sanitise().

json_require¶

Verify that required commands or files exist. On failure, emits a JSON object containing Warning keypairs for each missing item and exits 1.

Example¶

json_require lsblk /proc/meminfo

Arguments¶

• ... (string): One or more command names or file paths to check

Exit codes¶

• 0: All required items found
• 1: One or more items missing

Output on stdout¶

• JSON Warning object if any required items are missing

json_gettype¶

Determine the JSON type of a value: 'float', 'int', 'bool', or 'string'. Used internally to select the appropriate output function (json_str, json_num, etc.).

Arguments¶

• $1 (string): Value to inspect

Exit codes¶

• 0: Always

Output on stdout¶

• One of: float, int, bool, string

json_open_arr¶

Emit an opening array bracket. With a name argument, emits '"name": ['. Without an argument, emits '['.

Arguments¶

• $1 (string): Optional: array name

Exit codes¶

• 0: Always

Output on stdout¶

• '"name": [' or '['

json_close_arr¶

Emit a closing array bracket. With '-c' or '--comma', appends a trailing comma.

Arguments¶

• $1 (string): Optional: '-c' or '--comma' to append a trailing comma

Exit codes¶

• 0: Always

Output on stdout¶

• ']' or '],'

json_append_arr¶

Emit a closing-then-opening array bracket sequence to chain arrays. With '-n' or '--no-bracket', the leading ']' is omitted. With a name argument, emits '], "name": ['.

Arguments¶

• $1 (string): Optional: '-n'/'--no-bracket' to omit the leading bracket
• $2 (string): Optional: array name

Exit codes¶

• 0: Always

Output on stdout¶

• Array transition bracket(s)

json_open_obj¶

Emit an opening object brace. With a name argument, emits '"name": {'. Without an argument, emits '{'.

Arguments¶

• $1 (string): Optional: object name

Exit codes¶

• 0: Always

Output on stdout¶

• '"name": {' or '{'

json_close_obj¶

Emit a closing object brace. With '-c' or '--comma', appends a trailing comma.

Arguments¶

• $1 (string): Optional: '-c' or '--comma' to append a trailing comma

Exit codes¶

• 0: Always

Output on stdout¶

• '}' or '},'

json_append_obj¶

Emit a closing-then-opening object brace sequence to chain objects. With '-n' or '--no-bracket', the leading '}' is omitted. With a name argument, emits '}, "name": {'.

Arguments¶

• $1 (string): Optional: '-n'/'--no-bracket' to omit the leading brace
• $2 (string): Optional: object name

Exit codes¶

• 0: Always

Output on stdout¶

• Object transition brace(s)

json_escape_str¶

Escape characters that must be escaped in JSON strings. Reads from stdin. Converts input to octals and substitutes control characters and special characters with their JSON escape sequences. Modified from https://stackoverflow.com/a/23166624

Example¶

printf '%s' 'hello "world"' | json_escape_str

Exit codes¶

• 0: Always

Output on stdout¶

• JSON-escaped string

json_str¶

Emit a JSON string keypair. With '-c' or '--comma', appends a trailing comma. If the value is blank or literally 'null', emits null (unquoted).

Example¶

json_str name Alice          # => "name": "Alice"
json_str -c name Alice       # => "name": "Alice",

Arguments¶

• $1 (string): Optional: '-c'/'--comma' for trailing comma, otherwise the key
• $2 (string): Value (or key if $1 is a flag)

Exit codes¶

• 0: Always

Output on stdout¶

• '"key": "value"' or '"key": null'

json_append_str¶

Emit a comma-prefixed JSON string keypair for stacking inside an object. If the value is blank or literally 'null', emits null (unquoted).

Arguments¶

• $1 (string): Key
• $2 (string): Value

Exit codes¶

• 0: Always

Output on stdout¶

• ', "key": "value"' or ', "key": null'

json_num¶

Emit a JSON number keypair. Numbers are unquoted. With '-c' or '--comma', appends a trailing comma. Integers strip leading zeros; floats use 2 decimal places. If the value is not a number, calls json_die().

Example¶

json_num count 42            # => "count": 42
json_num ratio 3.14          # => "ratio": 3.14

Arguments¶

• $1 (string): Optional: '-c'/'--comma' for trailing comma, otherwise the key
• $2 (string): Numeric value

Exit codes¶

• 0: Always
• 1: If value is not a number

Output on stdout¶

• '"key": value' or '"key": null'

json_append_num¶

Emit a comma-prefixed JSON number keypair for stacking inside an object. Numbers are unquoted. If the value is blank or null, emits null (unquoted).

Arguments¶

• $1 (string): Key
• $2 (string): Numeric value

Exit codes¶

• 0: Always
• 1: If value is not a number

Output on stdout¶

• ', "key": value' or ', "key": null'

json_bool¶

Emit a JSON boolean keypair. Booleans are unquoted. With '-c' or '--comma', appends a trailing comma. Accepts true/false/yes/no/on/off (case-insensitive). Calls json_die() if the value is not a recognised boolean.

Arguments¶

• $1 (string): Optional: '-c'/'--comma' for trailing comma, otherwise the key
• $2 (string): Boolean value (true/false/yes/no/on/off)

Exit codes¶

• 0: Always
• 1: If value is not a recognised boolean

Output on stdout¶

• '"key": true' or '"key": false'

json_append_bool¶

Emit a comma-prefixed JSON boolean keypair for stacking inside an object. Accepts true/false/yes/no/on/off (case-insensitive). Calls json_die() for unrecognised values.

Arguments¶

• $1 (string): Key
• $2 (string): Boolean value (true/false/yes/no/on/off)

Exit codes¶

• 0: Always
• 1: If value is not a recognised boolean

Output on stdout¶

• ', "key": true' or ', "key": false'

json_auto¶

Emit a JSON keypair, automatically selecting the correct type function (json_num, json_bool, or json_str) based on the value. Experimental.

Arguments¶

• $1 (string): Key
• $2 (string): Value

Exit codes¶

• 0: Always

Output on stdout¶

• JSON keypair in the appropriate format

json_append_auto¶

Emit a comma-prefixed JSON keypair, automatically selecting the correct type function. Experimental.

Arguments¶

• $1 (string): Key
• $2 (string): Value

Exit codes¶

• 0: Always

Output on stdout¶

• Comma-prefixed JSON keypair in the appropriate format

json_from_dkvp¶

Parse a delimited key-value pair (using ':' or '=') and emit its key and value as separate quoted words suitable for passing to json_str() or json_num().

Example¶

json_num $(json_from_dkvp "Bytes: 22")   # => "Bytes": 22

Arguments¶

• $1 (string): Delimited key-value pair (e.g. 'Bytes: 22' or 'Bytes=22')

Exit codes¶

• 0: Always
• 1: Line has no recognised delimiter (': ' or '=')

Output on stdout¶

• '"key" "value"'

json_val_arr¶

Emit a JSON array keypair whose values are auto-typed. Integers, floats, and booleans are unquoted; everything else is quoted. With '-c' or '--comma', appends a trailing comma.

Example¶

json_val_arr tags foo bar         # => "tags": ["foo","bar"]
json_val_arr counts 1 2 3         # => "counts": [1,2,3]
json_val_arr flags true false     # => "flags": [true,false]

Arguments¶

• $1 (string): Optional: '-c'/'--comma' for trailing comma, otherwise the key
• $2 (string): Key (when $1 is a flag)
• ... (string): Values to include in the array

Exit codes¶

• 0: Always

Output on stdout¶

• '"key": [values...]'

json_append_val_arr¶

Comma-prefixed variant of json_val_arr for stacking inside an object.

Arguments¶

• $1 (string): Key
• ... (string): Values to include in the array

Exit codes¶

• 0: Always

Output on stdout¶

• ', "key": [values...]'

json_foreach¶

Emit a complete JSON object from a flat list of alternating key-value pairs. Automatically selects the correct type function for each value. With '-n'/'--name', wraps the object under a named key. Delegates to json_readloop for the iteration logic.

Example¶

json_foreach a b c d         # => {"a": "b", "c": "d"}
json_foreach -n root a b     # => {"root": {"a": "b"}}

Arguments¶

• $1 (string): Optional: '-n'/'--name' followed by an object name
• ... (string): Alternating key value pairs

Exit codes¶

• 0: Always

Output on stdout¶

• Complete JSON object

json_readloop¶

Read key-value pairs from a file or stdin and emit a JSON object. Automatically selects the correct type function for each value. Preliminary implementation — do not use in production.

Arguments¶

• $1 (string): Optional: '-n'/'--name' followed by an object name, or a file path

Exit codes¶

• 0: Always

Output on stdout¶

• JSON object built from input key-value pairs

json_timestamp¶

Append a timestamp object to the current JSON output. Tries epoch first; falls back to YYYYMMDDHHMMSS format if epoch is unavailable.

Exit codes¶

• 0: Always

Output on stdout¶

• JSON object: {"timestamp": {"utc_epoch": N}} or {"timestamp": {"utc_YYYYMMDDHHMMSS": N}}

json_pretty¶

Pretty-print JSON from stdin using python3 or jq, whichever is available. Falls back to cat if neither is found.

Example¶

json_open; json_str foo bar; json_close | json_pretty

Exit codes¶

• 0: Always

Output on stdout¶

• Indented, human-readable JSON

json_validate¶

Validate JSON from stdin using python3 or jq, whichever is available. Prints nothing on success; prints an error message to stderr on failure.

Example¶

json_open; json_str foo bar; json_close | json_validate

Exit codes¶

• 0: Valid JSON
• 1: Invalid JSON or no validator available

json_from_env¶

Emit a JSON object from environment variables. With no arguments, emits all environment variables. With arguments, emits only those named variables.

Example¶

json_from_env HOME SHELL       # => {"HOME": "/root", "SHELL": "/bin/bash"}
json_from_env                  # => all environment variables as a JSON object

Arguments¶

• ... (string): Optional: names of specific environment variables to include

Exit codes¶

• 0: Always

Output on stdout¶

• JSON object of environment variable keypairs