This function is used to extract the value of the item specified in the direct path field. The result is written to a specified named variable. The directed path field can refer to a container or any item in a container. If the targeted item does not exist, it is considered an error.
All text fields can contain any of the escape sequences defined in Escape Sequences.
The action test state will be set to true if there are no errors. The action test state will be false if any errors occurred. Named variable Container Error will contain the errror text. If the Stop action on error option is enabled, the action will be terminated with an error message in the case of an error. Remember that the non existence of the targeted item is considered an error. For that reason you will typically not set the Stop action on error option.
Note that optionally every item which is returned can be prefixed by a single character tag identifying the type. This is useful when you want to determine the data type of an available item. If the Include the data tag option is set, the prefix character is included.
This statement can effectively be performed in an escape sequence where the include data tag option is disabled and errors are not reported. The sequence which can be found on the Insert Yate Escape Sequence > Numeric Exprs/Container Refs menu is as follows:
\?[ directed path \?]
The following list describes how each queried JSON data item is returned. In the examples it is assumed that the include data tag option is set. The data tag character is indicated in blue. All examples refer to the following JSON text in a container named sample.
[
{
"id" : 23,
"location" : {
"address" : "123 Front Street",
"phone #" : "555-5555",
"city" : "Toronto",
},
"moods" : [
"rock",
"blues"
],
"name" : "Jack",
"special" : true,
"id" : "item 0"
},
{
"description" : "great person",
"id" : 24,
"location" : {
"address" : "21 Main Street",
"phone #" : "555-2222",
"city" : "Toronto"
},
"moods" : [
"classical",
"opera",
"jazz"
],
"name" : "Jill",
"special" : null,
"id" : "item 1"
}
]You can optionally specify that the returned test state should be false unless a particular data type is referenced by the specified directed path field. The Data type control is used to choose a must match data type. When not set to Any, a test will be made against the specified data type. If the data type of the returned data does not satisfy the referenced item, the action test state will be set to false.
The data types of Array, Object, String, Boolean and Null match specific data types. A data type of Node implies that any of String, Number, Boolean, Null or the plist data types of Date or Data will be accepted. A data type of Number will match Number and Boolean.
When a Boolean is matched by a data type of Number the returned value will be 1 or 0 as opposed to true or false.
When the specified data type is Any, Node or String you have additional options which modify the returned value. This only occurs at runtime if the extracted value was from actually from a String. The following options are available:
Note that when extracting values from an object modified by a Prompt from Container statement, it is better to test for Any or Node rather than a specific simple data type. The statement takes a relaxed attitude with simple data types.
There are a few special forms of a directed path which can be used to extract all values of array items, the directed paths of array items, and to set named variables to the directed paths of array items.
Enumerate Unique Array Elements
The form [*] implies that a referenced array is to be enumerated. At most one [*] form may be specified. The List Secondary Delimiter (\:) separates the returned array elements. Note that if the array does not contain any elements, the destination named variable will be empty. Empty elements are not returned and duplicates may be. You can specify an alternate delimiter for \: by placing a non empty value in named variable Container Secondary Delimiter.
The [*] form is also unique that in certain circumstances it will not fail on an Object name which does not exist. A non existent .name sequence will not be considered an error if the required data type is anything other than Array or Object. The value returned is an empty string and if data types are being included a special data type of ? will be used. Note that empty elements are not returned unless the data type tag is requested.
Directed Path to an array element
While you can use hard coded array indexes to refer to an array element, this can be detrimental if the array structure can change.
You can use the [*] form to return the directed paths of the array elements where the returned value (included the optional data tag) would match a supplied pattern. The equality test is always case insensitive. The key-value delimiter (\k) is used to separate the directed path from the pattern. Note that spaces are significant after the \k delimiter. Only items which match the pattern will have their path's returned. The List Secondary Delimiter (\:) separates the returned array elements. You can specify an alternate delimiter for \: by placing a non empty value in named variable Container Secondary Delimiter.
Directed Paths to Named Variables
You can also extract the directed paths of array elements to named variables. The value of the referenced item (typically an object name) is interpreted as being the named variable. The returned value is a list of the named variables which were modified, delimited by the default list delimiter (\~). A double key-value delimiter is used to represent the mode. Any text after the \k\k sequence is ignored.
Example: Save all id element values to named variables.
Extract data from the container item at 'obj[*].id\k\k' to named variable 'res' will set the following named variables: item 0: obj[0] item 1: obj[1] res: item·1⏎item·0