GAMBAS-BOOK 3.19.5

On the website http://de.wikipedia.org/wiki/JavaScript_Object_Notation, the data format JSON is described thus: The JavaScript Object Notation, or JSON [ˈdʒeɪsən], is a compact data format in an easy-to-read text form for the purpose of exchanging data between applications. Any valid JSON document shall be a valid JavaScript and be able to be interpreted via eval(). […] Apart from that, however, JSON is independent of the programming language.

• You can read the RFC for JSON at https://tools.ietf.org/html/rfc7159.
• The German JSON original can be found at http://json.org/json-de.html, to which the Gambas documentation refers.

The class JSON (gb.web → gb.util.web) allows you to encode and decode in JSON format.

The following table describes the mapping between JSON elements and Gambas data types:

Table 24.6.9.0.1 : Mapping table

Note that JSON syntax requires you to lowercase the values true, false and null in the JSON text.

The JSON class has only one property and two methods:

• The static property Null of type Variant represents a JSON null value. It is used, among other things, if the optional argument 'UseNull' in the JSON.Decode(…) method has the value 'True'.

• The method Encode ( Value As Variant ) As String encodes a Gambas value into a JSON text and returns it. A date is converted to a corresponding string, as JSON does not support a 'Date' type. Note: The parameter 'Value' is a typed value in Gambas terminology. Even if you pass Value as a Variant, the interpreter will find out the correct data type of Value. The data exchange format JSON allows Gambas to serialise existing data with the function Encode(…). The serialised data is then available as a JSON object (JSON text), whose structure is defined with {“KEY_1”: VALUE_1, “KEY_2”: VALUE_2, …, “KEY_k”: VALUE_k} is similar to a Gambas collection.

• The method Decode ( JSONString As String [ , UseNull As Boolean ] ) As Variant decodes a JSON text and returns it as a Gambas value of data type Variant - either of type Collection or JSONCollection. If the optional argument 'UseNull' in the JSON.Decode method has the value 'True', then null is represented by the JSON.Null property. This allows the distinction between an unset property and a property with the value NULL. The Decode(…) method implements both a validator and a parser for a JSON text. Data in JSON format becomes data of the Gambas type Variant if the JSON text has been recognised as syntactically correct by the validator.

The class JSONCollection (gb.web → gb.util.web) represents a JSON object.

• JSONCollection is a special collection that allows a null value to be associated with a key, which would not be possible with a collection in Gambas. In a collection (gb), if the value to a defined key is null, then the key-value pair is removed from the collection!
• The class JSONCollection is used by the method JSON.Decode(JSONString As String [ , UseNull As Boolean ] ) if the value for the optional argument 'UseNull' is set to True.

The JSONCollection class has two properties:

Table 24.6.9.0.2 : Properties of the class JSONCollection

The JSONCollection class has the following five methods:

Table 24.6.9.0.3 : Methods of the class JSONCollection

In this example, data is converted to JSON format using the JSON.Decode(….) method:

[1]   Dim fRatio As Float, sJSONText As String, vArray As Variant[]
[2]   Dim cCollection As Collection, cJSONCollection As JSONCollection
[3]
[4]   cJSONCollection = New JSONCollection
[5]   cCollection = New Collection
[6]
[7]   fRatio = 0.1
[8]   cJSONCollection["Seite \"a\" "] = 688.7 * fRatio
[9]   cCollection[String.Chr(946)] = 43
[10]   cCollection[String.Chr(947)] = 2.039E1
[11]   cJSONCollection["Winkel"] = cCollection ' Alternative: cData.Add(cCollection, "Winkel")
[12]   cJSONCollection["Umfang Dreieck " & String.Chr(916) & " ABC"] = "?"
[13]   cJSONCollection["Widerstand in " & String.Chr(937)] = 2550
[14]   vArray = New Variant[]
[15]   vArray = ["gambas-buch.de", "gambas.sourceforge" & ".net"]
[16]   cJSONCollection["URLs"] = vArray
[17]   cJSONCollection["EMail"] = "wer@ist.da"
[18]   cJSONCollection["Datum"] = Format(Now(), "dd. mmmm yyyy")
[19]   cJSONCollection["Diplom"] = False
[20]   cJSONCollection["Master"] = JSON.Null
[21]
[22]   sJSONText = JSON.Encode(cJSONCollection)
[23]
[24]   Print sJSONText

Comment:

• In line 8, the first element is inserted into the JSON collection. The key contains “a” and therefore the two “ around a must be masked. The value is first calculated and then assigned.
• The key-value pair “angle” | value in line 11 contains as value a collection whose two value-key pairs are specified in lines 9 and 10. The characters for beta and gamma are generally not accessible on the keyboard. Therefore, they are utf8-encoded.
• The key “URLs” is assigned a variant array as value in line 16, which is declared in line 14 and assigned an inline array in line 15.
• Since JSON does not know its own date format, a suitably formatted date string is assigned in line 18.
• Assigning a truth value to the key “diploma” is done in line 19.
• Unlike the “Diploma” key, the value for the “Master” key is not known. Therefore, JSON.Null is the correct value. But this assumes that you have declared the variable cJSONCollection with the data type JSONCollection!
• The method Encode(Value As Variant) is passed the JSONCollection as parameter in line 22 and the function value is assigned to the variable sJSONText.
• In line 24, the JSON text is output.

This is how the JSON text presents itself in the console of the Gambas IDE:

{"Seite \"a\" ": 68.87, "Winkel": {"β": 43, "γ": 20.39}, "Umfang Dreieck Δ ABC": "?",
"Widerstand in Ω": 2550, "URLs": ["gambas-buch.de", "gambas.sourceforge.net"],
"EMail": "wer@ist.da", "Datum": "17. April 2016", "Diplom": false, "Master": null}

If the JSON text is output formatted → Chapter 24.6.9.1 Project formatter for JSON text, it is easier to read:

{
  "Seite "a" ": 68,87,
  "Winkel": {
    "β": 43,
    "γ": 20,39
  },
  "Umfang Dreieck Δ ABC": "?",
  "Widerstand in Ω": 2550,
  "URLs": [
    "gambas-buch.de",
    "gambas.sourceforge.net"
  ],
  "EMail": "wer@ist.da",
  "Datum": "17. April 2016",
  "Diplom": false,
  "Master": null
}

If one analyses the value data type of the elements in the JSON collection, then the following overview shows up:

Anzahl der Elemente in der JSON-Collection: 9
----------------------------------------------------------------------------------------------------
Schlüssel 1 : "Seite "a" " ---> Wert-Typ: Float
Schlüssel 2 : "Winkel" ---> Wert-Typ: JSONCollection
Schlüssel 3 : "Umfang Dreieck Δ ABC" ---> Wert-Typ: String
Schlüssel 4 : "Widerstand in Ω" ---> Wert-Typ: Integer
Schlüssel 5 : "URL" ---> Wert-Typ: Variant[]
Schlüssel 6 : "EMail" ---> Wert-Typ: String
Schlüssel 7 : "Datum" ---> Wert-Typ: String
Schlüssel 8 : "Diplom" ---> Wert-Typ: Boolean
Schlüssel 9 : "Master" ---> Wert-Typ: NULL oder JSON-Null

Note: In revision 7744 of Gambas3, a bug has been fixed in the JSONCollection class that did not correctly take the JSON.Null property.