Script unit that provides methods to manage json data.
This unit provides methods to create and parse any kind of JSON including string, decimal, boolean, null, objects and arrays. Items of an array do not need to all be of the same type.
A variable of type json_value can represent a json value of any kind. The following readonly boolean properties are never null and can be used to check the type of the json value:
- isNull: boolean - true if value is null
- isString: boolean - the value as a string
- isDecimal: boolean - the value as a decimal
- isBoolean: boolean - the value as a boolean
- isObject: boolean - the value as a object
- isArray: boolean - the value as a array
The following readonly properties can be used to get the json value. They return null if the value not of the given type or is null:
- asDecimal: string - the value as a string
- asBoolean: boolean - the value as a boolean
- asObject: json_object - the value as an object
- asArray: list<json_value> - the value as an array.
Datetime, date and time types are not natively supported in JSON. They can be converted from or to a string using functions toIsoString() and fromIsoString() provided by units core.datetime, core.date and core.time.
Samples The following is a JSON sample:
{
"id": "jsmith",
"firstName": "Jane",
"lastName": "Smith",
"age": 30,
"income": null,
"address": {
"street": "123 Main St",
"city": "San Francisco"
},
"variousItems": [
{
"id": "jdoe",
"firstName": "John",
"lastName": "Doe"
},
"Hello!",
-743.6534,
true,
null,
[54, 67, 89, -21]
]
}
The following script shows how to parse this JSON string:
uses core.json as json;
procedure processJson(json: string)
begin
// Parse the JSON string into a JSON object
// Note: Following code will NOT raise an error if json.parse(json) returns null, but variable user will simply be
// set to null. For details see EBX Script reference.
var user := json.parse(json).asObject;
if isNull(user) then
// Following will be called if:
// - The json.parse() returned null because JSON is not valid,
// - The JSON is not an object (e.g. an array).
raise 1, 'Json parsing failed';
// Note: Following code will NOT raise an error if the key does not exist in the JSON string, but variable id
// will be set to null. For details see EBX Script reference.
var id := json.get(user, 'id').asString;
var firstName := json.get(user, 'firstName').asString;
var lastName := json.get(user, 'lastName').asString;
var age := json.get(user, 'age').asDecimal;
var income := json.get(user, 'income').asDecimal;
var address := json.get(user, 'address').asObject;
var street := json.get(address, 'street').asString;
var city := json.get(address, 'city').asString;
// Field "unknown" does not exist in the JSON string, but will not raise an error, and value
// will be set to null.
var unknown := json.get(address, 'unknown').asString;
// Variable income and unknown are null. The following checks if the JSON values were explicitly
// set to null or if they do not exist in the JSON string.
if json.get(user, 'income').isNull then
reportMessage('Property income is explicitly set to null in the JSON string');
if isNull(json.get(user, 'unknown')) then
reportMessage('Property unknown is missing in the JSON string');
// Iterate through the JSON array of various items.
// A JSON array is of type list<json_value>.
for item in json.get(user, 'variousItems').asArray do
begin
if item.isString then
reportMessage('Found string item ' | item.asString);
else if item.isBoolean then
reportMessage('Found boolean item ' | item.asBoolean);
else if item.isDecimal then
reportMessage('Found decimal item ' | item.asDecimal);
else if item.isNull then
reportMessage('Found null item');
else if item.isObject then
reportMessage('Found object item with the number of keys equal to ' | json.keys(item.asObject).size);
else if item.isArray then
reportMessage('Found array item of size ' | item.asArray.size);
end
// Do something with the parsed data.
end
The following script shows how to create a JSON string identical to the above sample:
uses core.json as json;
uses core.list as list;
function createJson(): string
begin
var user := instanceOf<json_object>();
// Create simple properties.
json.put(user, 'id', json.ofString('jsmith'));
json.put(user, 'firstName', json.ofString('Jane'));
json.put(user, 'lastName', json.ofString('Smith'));
json.put(user, 'age', json.ofDecimal(30));
json.put(user, 'income', json.ofNull());
// Create an objecty property.
begin
var address := instanceOf<json_object>();
json.put(user, 'address', json.ofObject(address));
json.put(address, 'street', json.ofString('123 Main St'));
json.put(address, 'city', json.ofString('San Francisco'));
end
// Create a property that is an array of items of various types.
begin
// The JSON array variousItems is a list if items of type json_value.
var variousItems := list.of<json_value>();
json.put(user, 'variousItems', json.ofArray(variousItems));
// Add an object to the JSON array.
begin
var object := instanceOf<json_object>();
list.add(variousItems, json.ofObject(object));
json.put(object, 'id', json.ofString('jdoe'));
json.put(object, 'firstName', json.ofString('John'));
json.put(object, 'lastName', json.ofString('Doe'));
end
// Add simple values to the JSON array.
list.add(variousItems, json.ofString('Hello!'));
list.add(variousItems, json.ofDecimal( - 743.6534));
list.add(variousItems, json.ofBoolean(true));
list.add(variousItems, json.ofNull());
// Add an array of integers.
begin
var intArray := list.of<json_value>();
list.add(variousItems, json.ofArray(intArray));
for value in list.of(54, 67, 89, - 21) do
begin
list.add(intArray, json.ofDecimal(value));
end
end
end
// Generate the JSON string.
return json.toJson(json.ofObject(user));
end
function arrayToJoson(list: list): string
This serializes a list of JSON values to a string.
Return :
the JSON string. Is null if the input list is null.
Can be used in:
function copyOfBooleans(value: list): json_value
Converts a boolean list to a JSON value of type array. Modifying the input list will not modify the returned JSON value.
Parameters :
list: the input list.
Return :
the JSON value. If input list is null, is the same as ofNull(). Never null.
Can be used in:
function copyOfDecimals(value: list): json_value
Converts a list of decimals to a JSON value of type array. Modifying the input list will not modify the returned JSON value.
Parameters :
list: the input list.
Return :
the JSON value. If input list is null, is the same as ofNull(). Never null.
Can be used in:
function copyOfObjects(value: list): json_value
Converts a list of JSON objects to a JSON value of type array. Modifying the input list will not modify the returned JSON value. The copy is not deep, so modifying the properties of an object in the list will modify the corresponding JSON value in the returned JSON value array.
Parameters :
list: the input list.
Return :
the JSON value. If input list is null, is the same as ofNull(). Never null.
Can be used in:
function copyOfStrings(value: list): json_value
Converts a list of strings to a JSON value of type array. Modifying the input list will not modify the returned JSON value.
Parameters :
list: the input list.
Return :
the JSON value. If input list is null, is the same as ofNull(). Never null.
Can be used in:
function exists(json: json_object, key: string): boolean
Checks if a key exists in the JSON object.
Can be used in:
function get(json: json_object, key: string): json_value
Returns the JSON value associated with the key in the JSON object.
Can be used in:
function getArray(json: json_object, key: string): list
This method is a shortcut for core.json.get(json, key).asArray.
Can be used in:
function getBoolean(json: json_object, key: string): decimal
This method is a shortcut for core.json.get(json, key).asBoolean.
Can be used in:
function getDecimal(json: json_object, key: string): decimal
This method is a shortcut for core.json.get(json, key).asDecimal.
Can be used in:
function getObject(json: json_object, key: string): object
This method is a shortcut for core.json.get(json, key).asObject.
Can be used in:
function getString(json: json_object, key: string): string
This method is a shortcut for core.json.get(json, key).asString.
Can be used in:
function isNotNull(json: json_object, key: string): boolean
This method is a shortcut for not core.json.isNull(json, key).
Can be used in:
function isNull(json: json_object, key: string): boolean
Returns true if the JSON value associated with the key exists and a JSON null value.
Can be used in:
function keys(object: json_object): list
Returns the keys of the JSON object as a list of strings. The order of the keys is not guaranteed.
Parameters :
object: the JSON object.
Return :
the keys list or null of the object is null.
Can be used in:
function objectToJson(object: json_object): string
This serializes a JSON object to a string.
Return :
the JSON string. Is null if the input JSON object is null.
Can be used in:
function ofArray(list: list): json_value
Returns an array JSON value. Modifying the input list will modify the returned JSON array.
Parameters :
value: the input value.
Return :
the JSON value. If input list is null, is the same as ofNull(). Never null.
Can be used in:
function ofBoolean(value: boolean): json_value
Returns a boolean JSON value.
Parameters :
value: the input value.
Return :
the JSON value. If input value is null, is the same as ofNull(). Never null.
Can be used in:
function ofDecimal(value: decimal): json_value
Returns a decimal JSON value.
Parameters :
value: the input value.
Return :
the JSON value. If input value is null, is the same as ofNull(). Never null.
Can be used in:
function ofNull(): json_value
Returns a null JSON value.
Return :
the value that represents the null JSON value. Never null.
Can be used in:
function ofObject(value: json_object): json_value
Returns an object JSON value. Modifying the input object's properties will modify the returned object JSON value's properties.
Parameters :
value: the input value.
Return :
the JSON value. If input value is null, is the same as ofNull(). Never null.
Can be used in:
function ofString(value: string): json_value
Returns a string JSON value.
Parameters :
value: the input value.
Return :
the JSON value. If input value is null, is the same as ofNull(). Never null.
Can be used in:
function parse(json: string): json_value
Parses a JSON string. The JSON can be of any type.
If parsing failed, returns null without any details. If a detailed error message is needed, for example to diagnose an issue, use parseWithReport() instead.
Parameters :
json: the JSON string.
Return :
the JSON value. If the input string is not valid JSON or is null, returns null.
Can be used in:
function parseWithReport(json: string): json_report
Parses a JSON string. The JSON can be of any type. If parsing failed, returns an error message that may be helpful to diagnose the issue.
The returned report has following readonly properties: value: json_value - The result of the parsing. Is never null if isSuccess is true or isError is false. isSuccess: boolean - true if and only the parsing succeeded. Never null. isError: boolean - false if and only the parsing failed. Never null. message: string - the error message. May be null if isSuccess is true or isError is false.
Parameters :
json: the JSON string.
Return :
the JSON report. Never null.
Can be used in:
procedure put(json: json_object, key: string, value: json_value)
Sets the JSON value associated with the key in the JSON object. Any previous value associated with the key is overwritten. Raises an error of the JSON object or the key are null.
Can be used in:
procedure putBoolean(json: json_object, key: string, value: list)
This method is a shortcut for core.json.put(json, key, core.json.ofArray(value)).
Can be used in:
procedure putBoolean(json: json_object, key: string, value: boolean)
This method is a shortcut for core.json.put(json, key, core.json.ofBoolean(value)).
Can be used in:
procedure putDecimal(json: json_object, key: string, value: decimal)
This method is a shortcut for core.json.put(json, key, core.json.ofDecimal(value)).
Can be used in:
procedure putBoolean(json: json_object, key: string)
This method is a shortcut for core.json.put(json, key, core.json.ofNull()).
Can be used in:
procedure putBoolean(json: json_object, key: string, value: json_object)
This method is a shortcut for core.json.put(json, key, core.json.ofObject(value)).
Can be used in:
procedure putBoolean(json: json_object, key: string, value: string)
This method is a shortcut for core.json.put(json, key, core.json.ofString(value)).
Can be used in:
procedure remove(builder: json_object, key: string)
Removes the item identified by the key. Removing a non-existing item has no effect.
Can be used in:
function toJson(jsonValue: json_value): string
Serializes a JSON value to a string.
Parameters :
jsonValue: the JSON value.
Return :
the JSON string. Is null if the input JSON value is null. The JSON null value is correctly serialized to valid JSON string 'null'.
Can be used in: