JSON Generation and Parsing

The following builtin functions allow programmers to quickly and easily convert data structures between MOO and JSON.

Function: str generate_json (value [, str mode])

Returns the JSON representation of the MOO value.

MOO supports a richer set of values than JSON allows. The optional mode specifies how this function handles the conversion of MOO values into their JSON representation.

The common subset mode, specified by the literal mode string "common-subset", is the default conversion mode. In this mode, only the common subset of types (strings and numbers) are translated with fidelity between MOO types and JSON types. All other types are treated as alternative representations of the string type. This mode is useful for integration with non-MOO applications.

The embedded types mode, specified by the literal mode string "embedded-types", adds type information. Specifically, values other than strings and numbers, which carry implicit type information, are converted into strings with type information appended. The converted string consists of the string representation of the value (as if tostr() were applied) followed by the pipe (|) character and the type. This mode is useful for serializing/deserializing objects and collections of MOO values.

generate_json([])                                           ⇒   "{}"
generate_json(["foo" -> "bar"])                             ⇒   "{\"foo\":\"bar\"}"
generate_json(["foo" -> "bar"], "common-subset")            ⇒   "{\"foo\":\"bar\"}"
generate_json(["foo" -> "bar"], "embedded-types")           ⇒   "{\"foo\":\"bar\"}"
generate_json(["foo" -> 1.1])                               ⇒   "{\"foo\":1.1}"
generate_json(["foo" -> 1.1], "common-subset")              ⇒   "{\"foo\":1.1}"
generate_json(["foo" -> 1.1], "embedded-types")             ⇒   "{\"foo\":1.1}"
generate_json(["foo" -> #1])                                ⇒   "{\"foo\":\"#1\"}"
generate_json(["foo" -> #1], "common-subset")               ⇒   "{\"foo\":\"#1\"}"
generate_json(["foo" -> #1], "embedded-types")              ⇒   "{\"foo\":\"#1|obj\"}"
generate_json(["foo" -> E_PERM])                            ⇒   "{\"foo\":\"E_PERM\"}"
generate_json(["foo" -> E_PERM], "common-subset")           ⇒   "{\"foo\":\"E_PERM\"}"
generate_json(["foo" -> E_PERM], "embedded-types")          ⇒   "{\"foo\":\"E_PERM|err\"}"

JSON keys must be strings, so regardless of the mode, the key will be converted to a string value.

generate_json([1 -> 2])                                     ⇒   "{\"1\":2}"
generate_json([1 -> 2], "common-subset")                    ⇒   "{\"1\":2}"
generate_json([1 -> 2], "embedded-types")                   ⇒   "{\"1|int\":2}"
generate_json([#1 -> 2], "embedded-types")                  ⇒   "{\"#1|obj\":2}"

Function: value parse_json (str json [, str mode])

Returns the MOO value representation of the JSON string. If the specified string is not valid JSON, E_INVARG is raised.

The optional mode specifies how this function handles conversion of MOO values into their JSON representation. The options are the same as for generate_json().

parse_json("{}")                                            ⇒   []
parse_json("{\"foo\":\"bar\"}")                             ⇒   ["foo" -> "bar"]
parse_json("{\"foo\":\"bar\"}", "common-subset")            ⇒   ["foo" -> "bar"]
parse_json("{\"foo\":\"bar\"}", "embedded-types")           ⇒   ["foo" -> "bar"]
parse_json("{\"foo\":1.1}")                                 ⇒   ["foo" -> 1.1]
parse_json("{\"foo\":1.1}", "common-subset")                ⇒   ["foo" -> 1.1]
parse_json("{\"foo\":1.1}", "embedded-types")               ⇒   ["foo" -> 1.1]
parse_json("{\"foo\":\"#1\"}")                              ⇒   ["foo" -> "#1"]
parse_json("{\"foo\":\"#1\"}", "common-subset")             ⇒   ["foo" -> "#1"]
parse_json("{\"foo\":\"#1|obj\"}", "embedded-types")        ⇒   ["foo" -> #1]
parse_json("{\"foo\":\"E_PERM\"}")                          ⇒   ["foo" -> "E_PERM"]
parse_json("{\"foo\":\"E_PERM\"}", "common-subset")         ⇒   ["foo" -> "E_PERM"]
parse_json("{\"foo\":\"E_PERM|err\"}", "embedded-types")    ⇒   ["foo" -> E_PERM]

In embedded types mode, key values can be converted to MOO types by appending type information. The full set of supported types are obj, str, err, float and int.

parse_json("{\"1\":2}")                                     ⇒   ["1" -> 2]
parse_json("{\"1\":2}", "common-subset")                    ⇒   ["1" -> 2]
parse_json("{\"1|int\":2}", "embedded-types")               ⇒   [1 -> 2]
parse_json("{\"#1|obj\":2}", "embedded-types")              ⇒   [#1 -> 2]

JSON defines types that MOO (currently) does not support, such as boolean true and false, and null. These values are always converted to the strings "true", "false" and "null".