User Tools

Site Tools


manual:JSON

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
manual:JSON [2019/06/24 00:49]
peternlewis
manual:JSON [2023/10/02 02:33] (current)
peternlewis
Line 1: Line 1:
 ====== JSON ====== ====== JSON ======
  
-Keyboard Maestro ​(v9.0+) ​includes comprehensive support for [[https://​json.org|JSON]] (JavaScript Object Notation), which is a formalized lightweight data-interchange format.+Keyboard Maestro includes comprehensive support for [[https://​json.org|JSON]] (JavaScript Object Notation), which is a formalized lightweight data-interchange format.
  
 JSON objects consist of one of: JSON objects consist of one of:
Line 8: Line 8:
 * A dictionary (aka, object), surrounded by curly brackets with comma-separated key-value pairs, eg `{ "​one"​ : 1, "​two"​ : "​2"​ }`.  The Key must be a properly formatted, double quoted, string. * A dictionary (aka, object), surrounded by curly brackets with comma-separated key-value pairs, eg `{ "​one"​ : 1, "​two"​ : "​2"​ }`.  The Key must be a properly formatted, double quoted, string.
 * A double quoted string, eg `"​hello"​`. ​ Strings can contain various backslash-escaped characters, including `"`, `/`, `\`, `b` (backspace),​ `f` (form feed), `n` (linefeed), `r` (carriage return), `t` (tab), and `u` followed by four hex digits to make a unicode character. * A double quoted string, eg `"​hello"​`. ​ Strings can contain various backslash-escaped characters, including `"`, `/`, `\`, `b` (backspace),​ `f` (form feed), `n` (linefeed), `r` (carriage return), `t` (tab), and `u` followed by four hex digits to make a unicode character.
 +* A number.
 * `true` - boolean true * `true` - boolean true
 * `false` - boolean false * `false` - boolean false
Line 30: Line 31:
 * “.” followed by the field name.  Field names are trimmed of leading or trailing whitespace - if your object field names can start or end with white space, you need to use the `{ field name }` notation. * “.” followed by the field name.  Field names are trimmed of leading or trailing whitespace - if your object field names can start or end with white space, you need to use the `{ field name }` notation.
  
-Array indices are 1-based. ​ The 0 index of an array access will return the count of the number of entries in the array.+Array indices are 1-based.  Negative indices count from the end of the array.  The 0 index of an array access will return the count of the number of entries ​in the array. ​ When evaluating the index, the context sensitive [[function:​COUNT|COUNT()]] function will return the number of elements ​in the array.
  
 Keyboard Maestro will use arrays and dictionaries more or less interchangeably,​ so: Keyboard Maestro will use arrays and dictionaries more or less interchangeably,​ so:
Line 38: Line 39:
 * J{3} * J{3}
  
-will all return the third element of an array, or the dictionary value for key “3”.  ​And important distinction is that the first one is a numeric calculation,​ the second one is plain text, and the third one is token text. +will all return the third element of an array, or the dictionary value for key “3”.  ​An important distinction is that the first one is a numeric calculation,​ the second one is plain text, and the third one is token text.
  
 ===== Pretty, Compact and Strict Flags ===== ===== Pretty, Compact and Strict Flags =====
Line 45: Line 45:
 Many of Keyboard Maestro’s operations that produce a result from JSON have two flags associated with them: Compact or Pretty; Strict or Not-Strict. Many of Keyboard Maestro’s operations that produce a result from JSON have two flags associated with them: Compact or Pretty; Strict or Not-Strict.
  
-* Compact means all extraneous white space is omitted from JSON results+* Compact means all extraneous white space is omitted from JSON results.
 * Pretty means JSON results will include white space to format the JSON in a relatively readable manner. * Pretty means JSON results will include white space to format the JSON in a relatively readable manner.
  
Line 52: Line 52:
     {"​a":​3,"​b":​null}     {"​a":​3,"​b":​null}
  
-whereas the result of %JSONValuePretty%J%` will be:+whereas the result of `%JSONValuePretty%J%` will be:
  
     {     {
Line 59: Line 59:
     }     }
  
-The exact indentation should not be assumed, it might be any number ​fo spaces or tabs.+The exact indentation should not be assumed, it might be any number ​of spaces or tabs.
  
 The Strict flag relates only to JSON results that are trivial JSON strings, eg JSON `"​result"​`. The Strict flag relates only to JSON results that are trivial JSON strings, eg JSON `"​result"​`.
  
-* Strict means even for trivial JSON strings, the result will be a properly double quoted string (eg `"​result"​`.+* Strict means even for trivial JSON strings, the result will be a properly double quoted string (eg `"​result"​`).
 * Non-Strict means that for trivial JSON string results, the result will return just the resulting string without any double quotes and with any escaping removed/​evaluated. ​ This will be more useful in some situations, but will lose the ability to distinguish between strings, numbers and `null`. * Non-Strict means that for trivial JSON string results, the result will return just the resulting string without any double quotes and with any escaping removed/​evaluated. ​ This will be more useful in some situations, but will lose the ability to distinguish between strings, numbers and `null`.
  
Line 79: Line 79:
 The default result format is Compact, Non-Strict. The default result format is Compact, Non-Strict.
  
-===== Actions ​===== +===== Use =====
  
 +There are [[:​Actions|actions]] to set dictionaries or variables from JSON containers, as well as an [[:action: Set_JSON_Value|action]] to set a field within a JSON object to a specified value.
  
 ===== Notes ===== ===== Notes =====
Line 87: Line 87:
 JSON objects must be properly legal to be processed. ​ In particular keys to objects must be strings, which means strings must be quoted with double quotes. `{ a : 3 }` is not valid, it must be `{ "​a"​ : 3 }`. JSON objects must be properly legal to be processed. ​ In particular keys to objects must be strings, which means strings must be quoted with double quotes. `{ a : 3 }` is not valid, it must be `{ "​a"​ : 3 }`.
  
-Although ​`3and `"​a"​` ​are technically legal JSON, in cases of ambiguity, Keyboard Maestro will not consider a variable to contain JSON unless it is a container, ie an array or dictionary, which starts (without any leading white space) with a `{` or `[`, and ends with a matching bracket followed by optional white space.+Decimal numbers may be processed by the system JSON APIs, which will store them as floating point, and floating point cannot store all decimal numbers with full fidelity. For example, if variable ​`Jcontains ​`[{ "​a" ​: 3.45 }]`, then `%JSONValue%J[1]%` may result ​in `{"​a":​3.4500000000000002}`. If you need precision when dealing ​with JSON values, avoid decimal numbers.
  
 +Although `3` and `"​a"​` are technically legal JSON, in Non-Strict mode with cases of ambiguity, Keyboard Maestro will not consider a value or variable to contain JSON unless it is a container, ie an array or dictionary, which starts (without any leading white space) with a `{` or `[`, and ends with a matching bracket followed by optional white space.
  
manual/JSON.1561351740.txt.gz · Last modified: 2019/06/24 00:49 by peternlewis