1\function{json_decode}
2\synopsis{Parse JSON text into an S-Lang data structure}
3\usage{json = json_decode (String_Type text)}
4\description
5  The \ifun{json_decode} function parses JSON data from the input
6  string, and returns a corresponding S-Lang data structure.
7  JSON values are represented as follows:
8#v+
9    JSON   -> S-Lang
10
11    object    Struct_Type
12    array     List_Type
13    string    String_Type or BString_Type
14    number    (L)Long_Type or Double_Type
15    `true'    UChar_Type ('\1')
16    `false'   UChar_Type ('\0')
17    `null'    Null_Type
18#v-
19  The S-Lang structure corresponding to a JSON object
20  with duplicate keys has no duplicate field names,
21  but the field value is given by the last JSON value.
22
23  If the input string does not contain valid JSON data,
24  or if numeric values cannot be represented within \slang,
25  or if JSON objects and/or arrays are too deeply nested,
26  a \exmp{Json_Parse_Error} is thrown.
27\seealso{json_encode}
28\done
29
30\function{json_encode}
31\synopsis{Generate JSON text from an S-Lang data structure}
32\usage{String_Type text = json_encode (json)}
33\description
34  The \ifun{json_encode} function generates the JSON text
35  that corresponds to the S_Lang data structure \exmp{json}.
36  Valid input types -- i.e., those that generate text
37  that can be parsed by \ifun{json_decode} -- are \dtype{Struct_Type}
38  (for JSON objects) and \dtype{List_Type} or \dtype{Array_Type} (for
39  JSON arrays), provided that these containers contain
40  only the following types:
41#v+
42    S-Lang                         -> JSON
43
44    Struct_Type                       object
45    List_Type or Array_Type           array
46    String_Type or BString_Type       string
47    UChar_Type ('\1')                 `true'
48    UChar_Type ('\0')                 `false'
49    other non-complex numeric types   number
50    Null_Type                         `null'
51#v-
52  Invalid input causes a \exmp{Json_Invalid_Json_Error}.
53
54  Optional whitespace in the output text can be configured
55  by the \exmp{pre_nsep}, \exmp{post_nsep}, \exmp{pre_vsep}, and \exmp{post_vsep}
56  qualifiers. (Only strings built from ' ', '\\t', '\\n',
57  or '\\r' are allowed. Other characters are ignored.)
58  If present, all whitespace after the final "\\n"
59  in \exmp{post_vsep} is considered as extra indentation,
60  which accumulates for nested objects and arrays.
61
62\qualifiers
63\qualifier{pre_nsep=str}{whitespace before name separator ':'
64                    in objects}{""}
65\qualifier{post_nsep=str}{whitespace after name separator ':'
66                     in objects}{""}
67\qualifier{pre_vsep=str}{whitespace before value separator ','
68                    in objects or arrays}{""}
69\qualifier{post_vsep=str}{whitespace after value separator ',',
70                     after the opening, and before
71                     the closing brackets in objects
72                     or arrays}{""}
73
74\example
75#v+
76  % some whitespace and indentation after separators:
77  json_encode (json; pre_nsep="", post_nsep=" ",
78                     pre_vsep="", post_vsep="\n  ")
79
80  % yet more whitespace around separators:
81  json_encode (json; pre_nsep=" ", post_nsep="  ",
82                     pre_vsep=" ", post_vsep="\n\t")
83#v-
84\seealso{json_decode}
85\done
86