cObject
---cJsonObject
The cJsonObject represents a single JSON node within a structure of JSON nodes.
A JSON node can represent an object, array, simple type (string, number and Boolean) or null value.
The class contains the entire API for generating, parsing and enumerating JSON. The JsonToDataType and DataTypeToJson methods can be used to parse a JSON document into struct and / or arrays.
This class can be used to parse and generate JSON. It is also capable of converting structs and arrays into JSON and JSON into structs and arrays. A cJsonObject instance represents a single node in a structure of JSON nodes. It can represent an object, array, simple type (string, number, Boolean) or a null value. Once initialized (by either parsing, using DataTypeToJson or calling InitJsonType) its API's can be used to enumerate or generate the JSON.
To parse JSON the ParseString or ParseUtf8 functions can be used. Both functions return a Boolean indicating if the parse was successful. If not ReportParseError or psParseError can be used to get information about the parse error.
The example below shows how to parse a string with JSON. If successful it reads the age member from the details object. If not successful it uses ReportParseError that will generate an error.
Handle hoJson hoDetails
Boolean bSuccess
Integer iAge
Get Create (RefClass(cJsonObject)) to hoJson
Get ParseString of hoJson '{"name" : "John", "details" : {"age" : 31, "male" : true}}' to bSuccess
If (bSuccess) Begin
Get Member of hoJson "details" to hoDetails
Get MemberValue of hoDetails "age" to iAge
Showln ("Age of John: " + String(iAge))
Send Destroy of hoDetails
End
Else Begin
Send ReportParseError of hoJson
End
Send Destroy of hoJson
Generating JSON can be done by calling Stringify on an initialized JSON object. The peWhitespace property on this object determines how the JSON will be spaced. To inialize JSON manually, the InitializeJsonType procedure can be used.
The example below initializes a JSON object, sets the name member, creates and initializes the member object, sets two members and then sets the member object as a member of the wrapping JSON object. Running this code results in the following JSON.
{ "name": "John", "details": { "age": 31, "male": true } }
Handle hoJson hoDetail String sJson Get Create (RefClass(cJsonObject)) to hoJson Send InitializeJsonType of hoJson jsonTypeObject Send SetMemberValue of hoJson "name" jsonTypeString "John" // Initialize detail object Get Create (RefClass(cJsonObject)) to hoDetail Send InitializeJsonType of hoDetail jsonTypeObject Send SetMemberValue of hoDetail "age" jsonTypeInteger 31 Send SetMemberValue of hoDetail "male" jsonTypeBoolean True Send SetMember of hoJson "details" hoDetail Send Destroy of hoDetail // Generate JSON string Set peWhiteSpace of hoJson to jpWhitespace_Spaced Get Stringify of hoJson to sJson Showln sJson Send Destroy of hoJson
A JSON document should be seen as a tree of objects, arrays and simple type nodes as leaves. A cJsonObject instance represents a single node in that tree and there are several API's available to traverse the tree. The JsonType and MemberJsonType functions can be used to determine the type of a specific node.
The MemberCount function returns the number of members on an object or an array and using Member or MemberByIndex members can be enumerated. When Member or MemberByIndex is used to obtain a handle to a member node, this handle needs to be destroyed manually. Note that destroying a member handle does not actually change the JSON document.
The example below enumerates a JSON object showing information about its members. It outputs the following:
Member 'name' of type 6
Member 'details' of type 4
Handle hoJson hoMember
Integer iMem iType
String sName
Boolean bSuccess
Get Create (RefClass(cJsonObject)) to hoJson
Get ParseString of hoJson '{"name" : "John", "details" : {"age" : 31, "male" : true}}' to bSuccess
If (bSuccess) Begin
For iMem from 0 to (MemberCount(hoJson) - 1)
Get MemberNameByIndex of hoJson iMem to sName
Get MemberByIndex of hoJson iMem to hoMember
Get JsonType of hoMember to iType
Showln (SFormat("Member '%1' of type %2", sName, iType))
Send Destroy of hoMember
Loop
End
Begin
Send ReportParseError of hoJson
End
Send Destroy of hoJson
The following example shows how enumerate array members. Note that in this example we do not get a handle to the member node first but access it directly using MemberValue which can be used for both arrays and objects.
The output of this example will be:
Member 0 has value 8
Member 1 has value 7,5
Member 2 has value 8
Member 3 has value 5,5
Handle hoJson
Boolean bSuccess
Integer iMem
Number nVal
Get Create (RefClass(cJsonObject)) to hoJson
Get ParseString of hoJson '[ 8, 7.5, 8, 5.5 ]' to bSuccess
If (bSuccess) Begin
For iMem from 0 to (MemberCount(hoJson) - 1)
Get MemberValue of hoJson iMem to nVal
Showln (SFormat("Member %1 has value %2", iMem, nVal))
Loop
End
Else Begin
Send ReportParseError
End
Send Destroy of hoJson
A good method to easily serialize and deserialize data is available with the JsonToDataType and DataTypeToJson methods. They can be used to convert data stored in structs to JSON and the other way around.
The example below defines a set of structs and arrays. It then parses some JSON uses JsonToDataType to convert the JSON into usable struct data. The output of the this example will be 'Student "John" has 4 ratings'.
Struct tStudentDetail
Integer age
Boolean male
End_Struct
Struct tStudent
String name
tStudentDetail details
Number[] ratings
End_Struct
Procedure ReadIntoStruct
Handle hoJson
tStudent student
Boolean bSuccess
Get Create (RefClass(cJsonObject)) to hoJson
Get ParseString of hoJson '{"name" : "John", "details" : {"age" : 31, "female" : false, "male" : true}, "ratings" : [ 8, 7.5, 8, 5.5 ]}' to bSuccess
If (bSuccess) Begin
// Convert JSON structure into struct
Get JsonToDataType of hoJson to student
Showln (SFormat('Student "%1" has %2 ratings', student.name, SizeOfArray(student.ratings)))
End
Else Begin
Send ReportParseError of hoJson
End
Send Destroy of hoJson
End_Procedure
This example demonstrates the other way arround where a struct with data is used to generate JSON.
{ "name": "John", "details": { "age": 31, "male": true }, "ratings": [ 8, 7.5, 8, 5.5 ] }
Procedure StructToJson
Handle hoJson
tStudent student
String sJson
Move "John" to student.name
Move 31 to student.details.age
Move True to student.details.male
Move 8 to student.ratings[0]
Move 7.5 to student.ratings[1]
Move 8 to student.ratings[2]
Move 5.5 to student.ratings[3]
Get Create (RefClass(cJsonObject)) to hoJson
// Convert struct to JSON structure
Send DataTypeToJson of hoJson student
Set peWhiteSpace of hoJson to jpWhitespace_Spaced
Get Stringify of hoJson to sJson
Showln sJson
Send Destroy of hoJson
End_Procedure