JSON Built-ins ¶

JSON Built-ins convert JSON-encoded structures (numbers, strings, booleans, arrays, objects and null) into vocable data transfer objects (DTOs) that are natively usable. JSON arrays are converted into lists, while JSON objects are converted into maps consisting of an unordered collection of key-value pairs.

JSON With Options Functions ¶

The withOptions method takes a list of strings describing JSON-encoding options and returns a GsonWrapper. The GsonWrapper provides the encode and decode methods.

Syntax

1	<json GsonWrapper> := Json.withOptions([<option String>, ...])

Returns
The GsonWrapper that provides the encode and decode methods.

Parameter

option - The JSON-encoding option, which refer to the GsonBuilder documentation
- May be one or more of:
  - disableHtmlEscaping
  - enableComplexMapKeySerialization
  - serializeNulls
  - serializeSpecialFloatingPointValues
  - setLenient
  - setPrettyPrinting

Example

stepdef "do some json"
    m := { "a" : null, "b" : 1 }

    d := Json.withOptions(["serializeNulls", "setPrettyPrinting"])
    enc2 := d.encode(m)
    println(enc2)

    dec2 := d.decode(enc2)
    println("" + dec2)
end

If written using the legacy encode and decode Built-in functions, as described below, the Stepdef may instead look like the following:

  enc := Json.encode(m)
  println(enc)

  dec := Json.decode(enc)
  println("" + dec)

Encode ¶

This function converts a data object into a JSON-encoded string.

Syntax

1	<resultEncode String> := Json.encode(<data Any>)

Returns
The encoded JSON object.

Parameter

data - The data object to be encoded

Example

stepdef "print temperature"
  map  := {"temperature" : 21, "time" : 18, "day" : "saturday"}
  map["temperature"] := 16
  println(Json.encode(map))
end

The example above accesses and encodes a map where a value has been changed. It should return the following:

1	{"temperature":16,"time":18,"day":"saturday"}

Decode ¶

This function decodes JSON-encoded strings.

Syntax

1	<resultDecode Any> := Json.decode(<encoded String>)

Returns
The decoded JSON object.

Parameter

encoded - The JSON-encoded string to decode

Example

stepdef "print my name"
  myJson  := "[1, 3, {name: 'Robin'}]"
  decoded := Json.decode(myJson)
  map := decoded[2]
  println(map["name"])
end

The JSON-encoded string in the example above contains a JSON array with three values, which is converted to a list. The first two elements are numbers and the third element is a JSON object that is converted to a map. The third element is then stored in a variable and the value of the key "name" is printed.

PrettyPrint ¶

The following function applies prettyPrint formatting conventions to JSON to improve its readability.

Syntax

1	<pretty String> := Json.prettyPrint(<json String>)

Returns
A more readable version of the given JSON-encoded string.

Parameter

json - The JSON content

Example

1	println(Json.prettyPrint('{"a":3, "b":4}') )

will result in the following output:

{
  "a" : 3,
  "b" : 4
}