json.bash's arguments define entries in a JSON object or array. Arguments use
the syntax described here to define the key and value of their entries, and
metadata on their JSON type (number, bool, etc) and how to handle missing/empty
files, etc.
Arguments have 3 main parts — the key, metadata and
value, which are all optional.
The optional ... splat prefix makes the argument describe multiple entries
that are merged into the host object or array.
Keys can be prefixed with Flags to control their behaviour when missing/empty.
Keys starting with @ are references to variables or files. (File references
start with / or ./, otherwise they're variables). Otherwise, the key's value
is a literal string. Values that use flag characters need to start with an =.
The value of a key can be any character, except : which starts a
metadata section, and @ or = which start a value.
To include these characters in keys, they must be escaped by doubling them.
Keys that are not followed by metadata can't end with the flag
characters, as they could be confused with the flags for the argument's
value.
Flags can appear before keys and values to control what happens when an entry's key or value is missing or empty.
+restores strictness, causing an error if the item is missing or empty (thejson_defaultsoption can make the default non-strict).~causes an un-set variable or missing file to be treated as if it was empty.?causes empty items to use a default value, according to the item's JSON type and the item's source (var, file, str).??causes entries containing the empty item to be omitted from the host object / array.
(The parser ignores redundant flag repetitions, and doesn't require a particular order.)
Arguments have metadata to control how their values are represented in their
entry of the produced JSON object or array. There are three parts to the
metadata, all optional. The type, collection and
attributes.
An argument's type defines the the JSON type of the entry's value. The default
type is string, so unless the default is changed using $json_default, a type
must be specified to create numbers, bools, etc.
The string type encodes the input as a JSON string, so any value is valid. The
null, true and false types don't require a redundant value. The auto
type produces numbers, bool and null values when inputs match those types, and
produces strings otherwise. The json type validates that the input is valid
JSON and emits it unchanged. raw acts like json, except that it performs no
validation!
An argument marked with a collection creates an entry with a variable-length array or object as its value, rather than a single value.
The collection section can include a split character and format. The split character controls which character is used to split the input file, variable, or string into chunks. Each chunk of the input is converted to array or object entries according to the format.
The default format is raw.
- The
rawformat encodes each chunk according to the argument'stype. - The
jsonformat validates that chunks are JSON arrays containing the argument'stype. The entries of each chunk's array are concatenated to form a single JSON array.
The default format is attrs.
- The
attrsformat reads each chunk of input using the samename=valueformat as is used forattributes(except that/is not reserved —//is not unescaped). Allname=valuepairs are merged to form entries in a single JSON object. - The
jsonformat validates that chunks are JSON objects with values that correspond to the argument'stype. The entries of each chunk's object are concatenated to form a single JSON object.
Attributes are a series of name-value pairs inside a pair of slashes, such as
/a=b,c=d/.
Like the values of keys, attributes can double up characters to escape them.
An individual attribute can just be a name without a value.
Names must escape =, , and / characters.
Values must escape , and / characters, but don't need to escape =.
Values can be prefixed with Flags to control their behaviour when missing/empty.
Values starting with @ are references to variables or files. (File references
start with / or ./, otherwise they're variables). Otherwise, a value starts
with = and the remaining content is the argument's value, without any
unescaping or further parsing.
To be parsed unambiguously, a value needs to be preceded by either a key or metadata section, for example
foo=baror:=bar. An argument with=at the start such as=bardefines akey, which is subject to double-char escaping and further parsing to identifymetadataandvaluesections.