JSON: add jsons extract variant, to strip quotes from string results

[exim.git] / doc / doc-docbook / spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 46cab7c58fa68736261537b69a384c90bf836b00..d3de8763f663f00d03c7a7b872f07d4324628c8c 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -6755,9 +6755,10 @@ of the JSON structure.
 If a selector is numeric, it must apply to a JSON array; the (zero-based)
 nunbered array element is selected.
 Otherwise it must apply to a JSON object; the named element is selected.
-The final resulting object can be a simple JSOM type or a JSON object
+The final resulting element can be a simple JSON type or a JSON object
 or array; for the latter two a string-representation os the JSON
 is returned.
+For elements of type string, the returned value is de-quoted.
 .wen
 .next
 .cindex "linear search"
@@ -9536,6 +9537,8 @@ This forces an expansion failure (see section &<<SECTforexpfai>>&);
 {<&'string2'&>} must be present for &"fail"& to be recognized.
 
 .vitem "&*${extract json{*&<&'key'&>&*}{*&<&'string1'&>&*}{*&<&'string2'&>&*}&&&
+       {*&<&'string3'&>&*}}*&" &&&
+       "&*${extract jsons{*&<&'key'&>&*}{*&<&'string1'&>&*}{*&<&'string2'&>&*}&&&
        {*&<&'string3'&>&*}}*&"
 .cindex "expansion" "extracting from JSON object"
 .cindex JSON expansions
@@ -9550,6 +9553,13 @@ The expanded <&'string1'&> must be of the form:
 The braces, commas and colons, and the quoting of the member name are required;
 the spaces are optional.
 Matching of the key against the member names is done case-sensitively.
+For the &"json"& variant,
+if a returned value is a JSON string, it retains its leading and
+trailing quotes.
+.new
+For the &"jsons"& variant, which is intended for use with JSON strings, the
+leading and trailing quotes are removed.
+.wen
 . XXX should be a UTF-8 compare
 
 The results of matching are handled as above.
@@ -9587,6 +9597,8 @@ empty (for example, the fifth field above).
 
 
 .vitem "&*${extract json{*&<&'number'&>&*}}&&&
+        {*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&" &&&
+       "&*${extract jsons{*&<&'number'&>&*}}&&&
         {*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&"
 .cindex "expansion" "extracting from JSON array"
 .cindex JSON expansions
@@ -9595,6 +9607,13 @@ apart from leading and trailing white space, which is ignored.
 
 Field selection and result handling is as above;
 there is no choice of field separator.
+For the &"json"& variant,
+if a returned value is a JSON string, it retains its leading and
+trailing quotes.
+.new
+For the &"jsons"& variant, which is intended for use with JSON strings, the
+leading and trailing quotes are removed.
+.wen
 
 
 .vitem &*${filter{*&<&'string'&>&*}{*&<&'condition'&>&*}}*&