7. JSON Module

This module encodes and decodes JSON (JavaScript Object Notation) formatted data. Use require("json") to load it.

7.1 json_decode

Synopsis

Parse JSON text into an S-Lang data structure

Usage

json = json_decode (String_Type text)

Description

The json_decode function parses JSON data from the input string, and returns a corresponding S-Lang data structure. JSON values are represented as follows:

    JSON   -> S-Lang

    object    Struct_Type
    array     List_Type
    string    String_Type or BString_Type
    number    (L)Long_Type or Double_Type
    `true'    UChar_Type ('\1')
    `false'   UChar_Type ('\0')
    `null'    Null_Type

The S-Lang structure corresponding to a JSON object with duplicate keys has no duplicate field names, but the field value is given by the last JSON value.

If the input string does not contain valid JSON data, or if numeric values cannot be represented within S-Lang, or if JSON objects and/or arrays are too deeply nested, a Json_Parse_Error is thrown.

See Also

json_encode

7.2 json_encode

Synopsis

Generate JSON text from an S-Lang data structure

Usage

String_Type text = json_encode (json)

Description

The json_encode function generates the JSON text that corresponds to the S_Lang data structure json. Valid input types -- i.e., those that generate text that can be parsed by json_decode -- are Struct_Type (for JSON objects) and List_Type or Array_Type (for JSON arrays), provided that these containers contain only the following types:

    S-Lang                         -> JSON

    Struct_Type                       object
    List_Type or Array_Type           array
    String_Type or BString_Type       string
    UChar_Type ('\1')                 `true'
    UChar_Type ('\0')                 `false'
    other non-complex numeric types   number
    Null_Type                         `null'

Invalid input causes a Json_Invalid_Json_Error.

Optional whitespace in the output text can be configured by the pre_nsep, post_nsep, pre_vsep, and post_vsep qualifiers. (Only strings built from ' ', '\t', '\n', or '\r' are allowed. Other characters are ignored.) If present, all whitespace after the final "\n" in post_vsep is considered as extra indentation, which accumulates for nested objects and arrays.

Qualifiers

pre_nsep=str : whitespace before name separator ':' in objects (Default: "")

post_nsep=str : whitespace after name separator ':' in objects (Default: "")

pre_vsep=str : whitespace before value separator ',' in objects or arrays (Default: "")

post_vsep=str : whitespace after value separator ',', after the opening, and before the closing brackets in objects or arrays (Default: "")

Example

  % some whitespace and indentation after separators:
  json_encode (json; pre_nsep="", post_nsep=" ",
                     pre_vsep="", post_vsep="\n  ")

  % yet more whitespace around separators:
  json_encode (json; pre_nsep=" ", post_nsep="  ",
                     pre_vsep=" ", post_vsep="\n\t")

See Also

json_decode