core.json ユニット
JSON データを管理するメソッドを提供するスクリプトユニットです。
このユニットは、文字列、10 進数、ブール値、null、オブジェクト、配列など、あらゆる種類の JSON を作成および解析するメソッドを提供します。配列の項目はすべて同じ型である必要はありません。
json\_value 型の変数は、あらゆる種類の JSON 値を表すことができます。以下の読み取り専用ブールプロパティは決して null にならず、JSON 値の型をチェックするために使用できます。
-
isNull: boolean - 値が null の場合に true
-
isString: boolean - 値が文字列の場合
-
isDecimal: boolean - 値が 10 進数の場合
-
isBoolean: boolean - 値がブール値の場合
-
isObject: boolean - 値がオブジェクトの場合
-
isArray: boolean - 値が配列の場合
以下の読み取り専用プロパティを使用して JSON 値を取得できます。値が指定された型でない場合、または null の場合は null を返します。
-
asDecimal: string - 値が文字列の場合
-
asBoolean: boolean - 値がブール値の場合
-
asObject: json\_object - 値がオブジェクトの場合
-
asArray: list<json\_value> - 値が配列の場合
日時、日付、時刻の型は JSON でネイティブにサポートされていません。これらは、ユニット core.datetime、core.date、および core.time によって提供される関数 toIsoString() および fromIsoString() を使用して、文字列との間で変換できます。
サンプル 以下は JSON のサンプルです。
{
"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]
]
}
以下のスクリプトは、この JSON 文字列を解析する方法を示しています。
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
以下のスクリプトは、上記のサンプルと同一の JSON 文字列を作成する方法を示しています。
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
arrayToJson
function arrayToJoson(list: list): string
JSON 値のリストを文字列にシリアル化します。
戻り値:
JSON 文字列。入力リストが null の場合は null
使用可能箇所:
copyOfBooleans
function copyOfBooleans(value: list): json\_value
ブール値のリストを配列型の JSON 値に変換します。入力リストを変更しても、返される JSON 値は変更されません。
パラメーター:
list: 入力リスト
戻り値:
JSON 値。入力リストが null の場合は ofNull() と同じ。決して null ではない
使用可能箇所:
copyOfDecimals
function copyOfDecimals(value: list): json\_value
10 進数のリストを配列型の JSON 値に変換します。入力リストを変更しても、返される JSON 値は変更されません。
パラメーター:
list: 入力リスト
戻り値:
JSON 値。入力リストが null の場合は ofNull() と同じ。決して null ではない
使用可能箇所:
copyOfObjects
function copyOfObjects(value: list): json\_value
JSON オブジェクトのリストを配列型の JSON 値に変換します。入力リストを変更しても、返される JSON 値は変更されません。コピーはディープではないため、リスト内のオブジェクトのプロパティを変更すると、返される JSON 値配列内の対応する JSON 値が変更されます。
パラメーター:
list: 入力リスト
戻り値:
JSON 値。入力リストが null の場合は ofNull() と同じ。決して null ではない
使用可能箇所:
copyOfStrings
function copyOfStrings(value: list): json\_value
文字列のリストを配列型の JSON 値に変換します。入力リストを変更しても、返される JSON 値は変更されません。
パラメーター:
list: 入力リスト
戻り値:
JSON 値。入力リストが null の場合は ofNull() と同じ。決して null ではない
使用可能箇所:
exists
function exists(json: json\_object, key: string): boolean
JSON オブジェクトにキーが存在するかどうかをチェックします。
使用可能箇所:
get
function get(json: json\_object, key: string): json\_value
JSON オブジェクト内のキーに関連付けられた JSON 値を返します。
使用可能箇所:
getArray
function getArray(json: json\_object, key: string): list
このメソッドは core.json.get(json, key).asArray のショートカットです。
使用可能箇所:
getBoolean
function getBoolean(json: json\_object, key: string): decimal
このメソッドは core.json.get(json, key).asBoolean のショートカットです。
使用可能箇所:
getDecimal
function getDecimal(json: json\_object, key: string): decimal
このメソッドは core.json.get(json, key).asDecimal のショートカットです。
使用可能箇所:
getObject
function getObject(json: json\_object, key: string): object
このメソッドは core.json.get(json, key).asObject のショートカットです。
使用可能箇所:
getString
function getString(json: json\_object, key: string): string
このメソッドは core.json.get(json, key).asString のショートカットです。
使用可能箇所:
isNotNull
function isNotNull(json: json\_object, key: string): boolean
このメソッドは not core.json.isNull(json, key) のショートカットです。
使用可能箇所:
isNull
function isNull(json: json\_object, key: string): boolean
キーに関連付けられた JSON 値が存在し、JSON null 値である場合に true を返します。
使用可能箇所:
keys
function keys(object: json\_object): list
JSON オブジェクトのキーを文字列のリストとして返します。キーの順序は保証されません。
パラメーター:
object: JSON オブジェクト
戻り値:
キーのリスト。オブジェクトが null の場合は null
使用可能箇所:
objectToJson
function objectToJson(object: json\_object): string
JSON オブジェクトを文字列にシリアル化します。
戻り値:
JSON 文字列。入力 JSON オブジェクトが null の場合は null
使用可能箇所:
ofArray
function ofArray(list: list): json\_value
配列 JSON 値を返します。入力リストを変更すると、返される JSON 配列が変更されます。
パラメーター:
value: 入力値
戻り値:
JSON 値。入力リストが null の場合は ofNull() と同じ。決して null ではない
使用可能箇所:
ofBoolean
function ofBoolean(value: boolean): json\_value
ブール値 JSON 値を返します。
パラメーター:
value: 入力値
戻り値:
JSON 値。入力値が null の場合は ofNull() と同じ。決して null ではない
使用可能箇所:
ofDecimal
function ofDecimal(value: decimal): json\_value
10 進数 JSON 値を返します。
パラメーター:
value: 入力値
戻り値:
JSON 値。入力値が null の場合は ofNull() と同じ。決して null ではない
使用可能箇所:
ofNull
function ofNull(): json\_value
null JSON 値を返します。
戻り値:
null JSON 値を表す値。決して null ではない
使用可能箇所:
ofObject
function ofObject(value: json\_object): json\_value
オブジェクト JSON 値を返します。入力オブジェクトのプロパティを変更すると、返されるオブジェクト JSON 値のプロパティが変更されます。
パラメーター:
value: 入力値
戻り値:
JSON 値。入力値が null の場合は ofNull() と同じ。決して null ではない
使用可能箇所:
ofString
function ofString(value: string): json\_value
文字列 JSON 値を返します。
パラメーター:
value: 入力値
戻り値:
JSON 値。入力値が null の場合は ofNull() と同じ。決して null ではない
使用可能箇所:
parse
function parse(json: string): json\_value
JSON 文字列を解析します。JSON は任意の型にできます。
解析に失敗した場合、詳細はなく null を返します。問題の診断など、詳細なエラーメッセージが必要な場合は、代わりに parseWithReport() を使用してください。
パラメーター:
json: JSON 文字列
戻り値:
JSON 値。入力文字列が有効な JSON でない場合、または null の場合は null を返します。
使用可能箇所:
parseWithReport
function parseWithReport(json: string): json\_report
JSON 文字列を解析します。JSON は任意の型にできます。解析に失敗した場合、問題の診断に役立つ可能性のあるエラーメッセージを返します。
返されるレポートには、以下の読み取り専用プロパティがあります。value: json\_value - 解析結果。isSuccess が true または isError が false の場合は決して null ではない。isSuccess: boolean - 解析が成功した場合にのみ true。決して null ではない。isError: boolean - 解析が失敗した場合にのみ false。決して null ではない。message: string - エラーメッセージ。isSuccess が true または isError が false の場合は null の場合がある。
パラメーター:
json: JSON 文字列
戻り値:
JSON レポート。決して null ではない
使用可能箇所:
put
procedure put(json: json\_object, key: string, value: json\_value)
JSON オブジェクト内のキーに関連付けられた JSON 値を設定します。キーに関連付けられた以前の値は上書きされます。JSON オブジェクトまたはキーが null の場合はエラーが発生します。
使用可能箇所:
putArray
procedure putBoolean(json: json\_object, key: string, value: list)
このメソッドは core.json.put(json, key, core.json.ofArray(value)) のショートカットです。
使用可能箇所:
putBoolean
procedure putBoolean(json: json\_object, key: string, value: boolean)
このメソッドは core.json.put(json, key, core.json.ofBoolean(value)) のショートカットです。
使用可能箇所:
putDecimal
procedure putDecimal(json: json\_object, key: string, value: decimal)
このメソッドは core.json.put(json, key, core.json.ofDecimal(value)) のショートカットです。
使用可能箇所:
putNull
procedure putBoolean(json: json\_object, key: string)
このメソッドは core.json.put(json, key, core.json.ofNull()) のショートカットです。
使用可能箇所:
putObject
procedure putBoolean(json: json\_object, key: string, value: json\_object)
このメソッドは core.json.put(json, key, core.json.ofObject(value)) のショートカットです。
使用可能箇所:
putString
procedure putBoolean(json: json\_object, key: string, value: string)
このメソッドは core.json.put(json, key, core.json.ofString(value)) のショートカットです。
使用可能箇所:
remove
procedure remove(builder: json\_object, key: string)
キーによって識別される項目を削除します。存在しない項目を削除しても効果はありません。
使用可能箇所:
toJson
function toJson(jsonValue: json\_value): string
JSON 値を文字列にシリアル化します。
パラメーター:
jsonValue: JSON 値
戻り値:
JSON 文字列。入力 JSON 値が null の場合は null。JSON null 値は、有効な JSON 文字列 'null' に正しくシリアル化されます。
使用可能箇所: