Docs: JSON operators and tweaks to genesis widget

editions/tw5.com/tiddlers/filters/jsonextract.tid

@@ -0,0 +1,58 @@
+created: 20220611104737314
+modified: 20220611104737314
+tags: [[Filter Operators]] [[JSON Operators]]
+title: jsonextract Operator
+caption: jsonextract
+op-purpose: retrieve the JSON value of a property from JSON strings
+op-input: a selection of JSON strings
+op-parameter: one or more indexes of the property to retrieve
+op-output: the JSON values of each of the retrieved properties
+
+<<.from-version "5.3.0">> See [[JSON in TiddlyWiki]] for background.
+
+The <<.op jsonextract>> operator is used to extract a smaller JSON object from within a larger one. It returns the properties from JSON data as a JSON string. See also the following related operators:
+
+* <<.olink jsonget>> to retrieve the values of a property in JSON data
+* <<.olink jsontype>> to retrieve the type of a JSON value
+* <<.olink jsonindexes>> to retrieve the names of the fields of a JSON object, or the indexes of a JSON array
+
+Properties within a JSON object are identified by a sequence of indexes. In the following example, the value at `[a]` is `one`, and the value at `[d][f][0]` is `five`.
+
+```
+{
+    "a": "one",
+    "b": "",
+    "c": "three",
+    "d": {
+        "e": "four",
+        "f": [
+            "five",
+            "six",
+            true,
+            false,
+            null
+        ],
+        "g": {
+            "x": "max",
+            "y": "may",
+            "z": "maize"
+        }
+    }
+}
+```
+
+The following examples assume that this JSON data is contained in a variable called `jsondata`.
+
+The <<.op jsonextract>> operator uses multiple operands to specify the indexes of the property to retrieve:
+
+```
+[<jsondata>jsonextract[a]] --> "one"
+[<jsondata>jsonextract[d],[f]] --> ["five","six",true,false,null]
+[<jsondata>jsonextract[d],[g]] --> {"x": "max","y": "may","z": "maize"}
+```
+
+Indexes can be dynamically composed from variables and transclusions:
+
+```
+[<jsondata>jsonextract<variable>,{!!field},[0]]
+```

editions/tw5.com/tiddlers/filters/jsonget.tid

@@ -0,0 +1,93 @@
+created: 20220611104737314
+modified: 20220611104737314
+tags: [[Filter Operators]] [[JSON Operators]]
+title: jsonget Operator
+caption: jsonget
+op-purpose: retrieve the value of a property from JSON strings
+op-input: a selection of JSON strings
+op-parameter: one or more indexes of the property to retrieve
+op-output: the values of each of the retrieved properties
+
+<<.from-version "5.3.0">> See [[JSON in TiddlyWiki]] for background.
+
+The <<.op jsonget>> operator is used to retrieve values from JSON data. See also the following related operators:
+
+* <<.olink jsonextract>> to extract a subtree of JSON data
+* <<.olink jsontype>> to retrieve the type of a JSON value
+* <<.olink jsonindexes>> to retrieve the names of the fields of a JSON object, or the indexes of a JSON array
+
+Properties within a JSON object are identified by a sequence of indexes. In the following example, the value at `[a]` is `one`, and the value at `[d][f][0]` is `five`.
+
+```
+{
+    "a": "one",
+    "b": "",
+    "c": "three",
+    "d": {
+        "e": "four",
+        "f": [
+            "five",
+            "six",
+            true,
+            false,
+            null
+        ],
+        "g": {
+            "x": "max",
+            "y": "may",
+            "z": "maize"
+        }
+    }
+}
+```
+
+The following examples assume that this JSON data is contained in a variable called `jsondata`.
+
+The <<.op jsonget>> operator uses multiple operands to specify the indexes of the property to retrieve:
+
+```
+[<jsondata>jsonget[a]] --> "one"
+[<jsondata>jsonget[d],[e]] --> "four"
+[<jsondata>jsonget[d],[f],[0]] --> "five"
+```
+
+Indexes can be dynamically composed from variables and transclusions:
+
+```
+[<jsondata>jsonget<variable>,{!!field},[0]]
+```
+
+Boolean values and null are returned as normal strings. The <<.olink jsontype>> operator can be used to retrieve a string identifying the original type. Thus:
+
+```
+[<jsondata>jsontype[a]] --> "string"
+[<jsondata>jsontype[d]] --> "object"
+[<jsondata>jsontype[d],[f]] --> "array"
+[<jsondata>jsontype[d],[f],[2]] --> "boolean"
+```
+
+Using the <<.op jsonget>> operator to retrieve an object or an array returns a list of all the values. For example:
+
+```
+[<jsondata>jsonget[d],[f]] --> "five","six","true","false","null"
+[<jsondata>jsonget[d],[g]] --> "max", "may", "maize"
+```
+
+The <<.olink jsonindexes>> operator retrieves the corresponding indexes:
+
+```
+[<jsondata>jsonindexes[d],[f]] --> "0", "1", "2", "3", "4"
+[<jsondata>jsonindexes[d],[g]] --> "x", "y", "z"
+```
+
+The behaviour when retrieving an object or array that contains values that are themselves objects or arrays is to recursively retrieve all the values:
+
+```
+[<jsondata>jsonget[d]] --> "four", "five", "six", "true", "false", "null", "max", "may", "maize"
+```
+
+A subtlety is that the special case of a single blank operand is used to identify the root object. Thus:
+
+```
+[<jsondata>jsonindexes[]] --> "a", "b", "c", "d"
+```

editions/tw5.com/tiddlers/filters/jsonindexes.tid

@@ -0,0 +1,65 @@
+created: 20220611104737314
+modified: 20220611104737314
+tags: [[Filter Operators]] [[JSON Operators]]
+title: jsonindexes Operator
+caption: jsonindexes
+op-purpose: retrieve the value of a property from JSON strings
+op-input: a selection of JSON strings
+op-parameter: one or more indexes of the property to retrieve
+op-output: the values of each of the retrieved properties
+
+<<.from-version "5.3.0">> See [[JSON in TiddlyWiki]] for background.
+
+The <<.op jsonindexes>> operator is used to retrieve the property names of JSON objects or the index names of JSON arrays. See also the following related operators:
+
+* <<.olink jsonget>> to retrieve the values of a property in JSON data
+* <<.olink jsonextract>> to extract a subtree of JSON data
+* <<.olink jsontype>> to retrieve the type of a JSON value
+
+Properties within a JSON object are identified by a sequence of indexes. In the following example, the value at `[a]` is `one`, and the value at `[d][f][0]` is `five`.
+
+```
+{
+    "a": "one",
+    "b": "",
+    "c": "three",
+    "d": {
+        "e": "four",
+        "f": [
+            "five",
+            "six",
+            true,
+            false,
+            null
+        ],
+        "g": {
+            "x": "max",
+            "y": "may",
+            "z": "maize"
+        }
+    }
+}
+```
+
+The following examples assume that this JSON data is contained in a variable called `jsondata`.
+
+The <<.op jsonindexes>> operator uses multiple operands to specify the indexes of the property to retrieve:
+
+```
+[<jsondata>jsonindexes[d],[f]] --> "0", "1", "2", "3", "4"
+[<jsondata>jsonindexes[d],[g]] --> "x", "y", "z"
+```
+
+Indexes can be dynamically composed from variables and transclusions:
+
+```
+[<jsondata>jsonindexes<variable>,{!!field}]
+```
+
+Retrieving the indexes of JSON properties that are not objects or arrays will return nothing.
+
+A subtlety is that the special case of a single blank operand is used to identify the root object. Thus:
+
+```
+[<jsondata>jsonindexes[]] --> "a", "b", "c", "d"
+```

editions/tw5.com/tiddlers/filters/jsontype.tid

@@ -0,0 +1,74 @@
+created: 20220611104737314
+modified: 20220611104737314
+tags: [[Filter Operators]] [[JSON Operators]]
+title: jsontype Operator
+caption: jsontype
+op-purpose: retrieve the type of a property from JSON strings
+op-input: a selection of JSON strings
+op-parameter: one or more indexes of the property whose type is to be retrieved
+op-output: the types of each of the retrieved properties
+
+<<.from-version "5.3.0">> See [[JSON in TiddlyWiki]] for background.
+
+The <<.op jsontype>> operator is used to retrieve the type of a property in JSON data. See also the following related operators:
+
+* <<.olink jsonget>> to retrieve the values of a property in JSON data
+* <<.olink jsonextract>> to extract a subtree of JSON data
+* <<.olink jsonindexes>> to retrieve the names of the fields of a JSON object, or the indexes of a JSON array
+
+JSON supports the following data types:
+
+* ''string'' - a Unicode string
+* ''number'' - a floating point number
+* ''boolean'' - Boolean value (true or false)
+* ''array'' - an array of values
+* ''object'' - an object of name/value pairs
+* ''null'' - a special type representing a missing value
+
+Properties within a JSON object are identified by a sequence of indexes. In the following example, the value at `[a]` is `one`, and the value at `[d][f][0]` is `five`.
+
+```
+{
+    "a": "one",
+    "b": "",
+    "c": "three",
+    "d": {
+        "e": "four",
+        "f": [
+            "five",
+            "six",
+            true,
+            false,
+            null
+        ],
+        "g": {
+            "x": "max",
+            "y": "may",
+            "z": "maize"
+        }
+    }
+}
+```
+
+The following examples assume that this JSON data is contained in a variable called `jsondata`.
+
+The <<.op jsontype>> operator uses multiple operands to specify the indexes of the property whose type is to be retrieved:
+
+```
+[<jsondata>jsontype[a]] --> "string"
+[<jsondata>jsontype[d]] --> "object"
+[<jsondata>jsontype[d],[f]] --> "array"
+[<jsondata>jsontype[d],[f],[2]] --> "boolean"
+```
+
+Indexes can be dynamically composed from variables and transclusions:
+
+```
+[<jsondata>jsontype<variable>,{!!field},[0]]
+```
+
+A subtlety is that the special case of a single blank operand is used to identify the root object. Thus:
+
+```
+[<jsondata>jsontype[]] --> "object"
+```

editions/tw5.com/tiddlers/widgets/GenesisWidget.tid

@@ -7,16 +7,16 @@ type: text/vnd.tiddlywiki
 
 ! Introduction
 
-<<.from-version "5.3.0">> The genesis widget allows the dynamic construction of widgets, where the name and attributes of the widget can be dynamically determined, and do not need to be known in advance.
+<<.from-version "5.3.0">> The genesis widget allows the dynamic construction of another widget, where the name and attributes of the new widget can be dynamically determined, without needing to be known in advance.
 
 ! Content and Attributes
 
 The content of the `<$genesis>` widget is used as the content of the dynamically created widget.
 
 |!Attribute |!Description |
-|$type |The type of widget to create |
+|$type |The type of widget to create (note that the first `$` must not be included, so the `<$text>` widget would be created by passing `text`) |
 |$tag |The HTML tag to be used for "element" widgets |
-|$names |An optional filter evaluating to the names of a list of variables to be applied to the widget |
+|$names |An optional filter evaluating to the names of a list of attributes to be applied to the widget |
 |$values |An optional filter evaluating to the values corresponding to the list of names specified in `$names` |
 |//{other attributes starting with $}// |Other attributes starting with a single dollar sign are reserved for future use |
 |//{attributes starting with $$}// |Attributes starting with two dollar signs are appplied as attributes to the output widget, but with the attribute name changed to use a single dollar sign |