JSON

SimpLight поддерживает работу с JSON-документами в своих скриптах. Основные типы для работы с JSON-форматом это TjsonObject и TJsonArray:

TjsonObject, TJsonArray

Работа с объектами

TjsonObject представляет JSON-объект. Объект хранит множество полей, значения которых можно получить по имени поля. Создать объект можно так:

json := TJsonObject.Create;

После получения объекта можно создать новое поле для него. Присвоим значение «SimpLight» типа string полю наименованием «brand».

json.S['brand'] := 'SimpLight';

Можно также получить значение поля и присвоить его какой-либо переменной.

objectBrand := json.S['brand'];

Следует заметить, что поле создается неявно при обращении к нему, а именно: при получении значения поля, или при установке значения поля. Обращение к полям происходит через использование свойств объекта, которое начинается с первой буквы типа, и квадратных скобок с именем поля. В таблице 1 приведен список типов и их сокращений, используемых в именах свойств.

Тип данных	Имя свойства
String	S
Integer	I
Int64	L
UInt64	U
Double	F
TDateTime	D
TDateTime	DUtc
Boolean	B
Array	A
Object	O
Variant	V

Таблица 1. Типы данных JSON и имя свойств объектов, массивов.

В таблице стоит обратить внимание на свойство DUtc, с его помощью можно получать дату и время в стандарте UTC.

Проверить наличие поля у объекта можно, используя метод Contains, указав имя поля:

if json.Contains('color') then DoOnTrue;

Узнать тип поля объекта можно с помощью свойства Types. Например:

lType := json.Types['brand'];
// lType будет содержать перечисление jdtString

Название метода	Описание метода
Assign(ASource: TJsonObject)	Присвоение полей переданного объекта с удалением полей целевому объекту
Clear	Очистка полей целевого объекта
Remove(Name: string)	Удаление поля по имени целевого объекта
Delete(Index: Integer)	Удаление поля по индексу целевого объекта
IndexOf(Name: string): Boolean	Метод возвращает индекс поля по его имени. Если поле отсутствует, то возвращает -1
Contains(Name: string): Boolean	Метод проверки наличия поля по имени
Extract(Name: string): TJsonBaseObject	Позволяет извлечь поле типа объект или массив по имени. Извлечение приводит к удалению поля из объекта и позволяет обрабатывать значение поля вне зависимости от остального документа. Возникает необходимость освободить память вручную для возвращенного значения.
ExtractArray(Name: string): TJsonArray	Позволяет извлечь поле типа массив. Работает аналогично методу Extract.
ExtractObject(Name: string): TJsonObject	Позволяет извлечь поле типа объект. Работает аналогично методу Extract.
IsNull(Name: string): Boolean	Метод позволяет узнать является ли поле равно null (nil в Паскале). Если поле отсутствует, то возвращает True. Если тип поля объект и оно равно nil, то возвращает True. Если у поля тип не объект, то возвращает False.

Таблица 2. Методы типа TJsonObject.

Название свойства	Описание
Types[Name: string]: TJsonDataType	Тип поля по указанному имени поля.
Count: Integer	Количество полей, принадлежащих объекту. Только для чтения.
Capacity: Integer	Показывает сколько мест выделено для полей. Свойство увеличивается самостоятельно по мере наполнения объекта полями.

Таблица 3. Свойства типа TJsonObject.

Работа с массивами

TjsonArray представляет JSON массив. Массив – это тип данных, который последовательно хранит значения и позволяет обратиться к конкретному элементу по индексу.

Массив можно создать следующим образом:

json := TJsonArray.Create;

TjsonArray способен обрабатывать значения различных типов. Наполнить массив можно так:

json.Add(67);
json.AddS('Мама');
json.AddS('мыла');
json.AddS('раму');

Добавить элементы массива можно с помощью метода Add принимающий тип Variant или метод с конкретным типом Add добавив букву типа из Таблицы 1.

После того как массив был наполнен можно его обойти. Обход выполняется с помощью цикла while и индекса.

i := 0;
while i < json.Count do
begin
strValue := json.S[i]; Inc(i);
end;

Заметим, что при доступе к элементу с помощью индекса явно указывается тип значения, к которому будет приведено значения элемента массива, в виде свойства. Похожий механизм используется в TJsonObject для доступа к полям объекта.

Название метода	Описание метода
Assign(ASource: TJsonArray)	Присвоение полей переданного массива с удалением элементов целевого объекта.
AddT(AValue: K)	Позволяет добавить значение в массив, где T – первая буква тип данных, K – тип данных. см. Таблица 1.
AddUtcDateTime(AValue: TDateTime)	Добавляет дату и время по часовому поясу UTC в массив.
AddArray: TJsonArray	Добавляет новый массив в текущий массив и возвращает его.
AddObject: TJsonObject	Добавляет новый объект в текущий массив и возвращает его.
InsertT(Index: T; Value: K)	Вставка нового элемента в массив, где T – первая буква тип данных, K – тип данных. см. Таблица 1.
Insert(Index: Integer; Value: Variant)	Вставка нового элемента в массив.
InsertArray(Index: Integer): TJsonArray	Вставляет новый массив по указанному индексу и возвращает его.
InsertObject(Index: Integer): TJsonObject	Вставляет новый объект по указанному индексу и возвращает его.
IsNull(Index: Integer): Boolean	Метод позволяет узнать является ли элемент null (nil в Паскале). Если тип элемента объект и элемент равен nil, то возвращает True. Если у элемента тип не объект, то возвращает False. Если индекс больше или равен количеству элементов массива выбрасывается исключение.

Таблица 4. Свойства типа TJsonArray.

Название свойства	Описание
Types[Index: Integer]: TJsonDataType	Тип элемента массива по указанному индексу.
Count: Integer	Количество элементов в массиве.
Capacity: Integer	Показывает сколько мест выделено для элементов. Свойство увеличивается самостоятельно по мере наполнения массива элементами.

Таблица 5. Свойства типа TJsonArray.

Базовый тип TJsonBaseObject

TjsonBaseObject является базовым типом для ранее рассмотренных TjsonObject и TJsonArray. Он содержит методы которые доступны обоим упомянутым типам.

Название метода	Описание метода
Clone: TJsonBaseObject	Позволяет создать полную копию текущего объекта. В копию включаются не только простые типы данных, но и объекты, массивы.
LoadFromFile(FileName: string; Utf8WithoutBOM: Boolean = True)	Загрузка JSON из указанного файла по имени. Тип корневого JSON элемента должен совпадать с текущим. Иначе это приведет к исключению. Utf8WithoutBOM – если True, то считается, что файл не содержит BOM в его начале, если закодирован в UTF-8.
LoadFromStream(Stream: TStream; Encoding: TEncoding = nil; Utf8WithoutBOM: Boolean = True)	Загрузка JSON из потока. Тип корневого JSON элемента должен совпадать с текущим. Иначе это приведет к исключению. Utf8WithoutBOM – если True, то считается, что поток не содержит BOM в его начале, если закодирован в UTF-8.
SaveToFile(FileName: string; Compact: Boolean = True; Encoding: TEncoding = nil; Utf8WithoutBOM: Boolean = True)	Сохранение текущего объекта в файл. если Compact – True, то конечный JSON будет в виде единственной строки. Если False – с форматированием и отступами в удобочитаемом формате.
SaveToStream(Stream: TStream; Compact: Boolean = True; Encoding: TEncoding = nil; Utf8WithoutBOM: Boolean = True)	Сохранение текущего объекта в поток.
SaveToLines(Lines: TStrings)	Сохранение текущего объекта в экземпляр TStrings с форматированием и отступами в удобочитаемом формате.
ToJSON(Compact: Boolean = True): string	Возвращает текущий объект в виде json-строки. Если Compact – True, то конечный JSON будет в виде единственной строки. Если False – с форматированием и отступами в удобочитаемом формате.

Таблица 6. Методы типа TJsonBaseObject.

Существует еще набор полезных методов для работы с JSON. Они содержатся в переменной TJson.

Название метода	Описание метода
ParseArray(S: string): TJsonArray	Возвращает JSON-массив, созданный из строки. Ожидается что корневой элемент является массивом.
ParseArrayFromFile(FileName: string; Utf8WithoutBOM: Boolean = True): TJsonArray	Возвращает JSON-массив, загруженный из файла. Ожидается что корневой элемент JSON’а является массивом.
ParseArrayFromStream(Stream: TStream; Encoding: TEncoding = nil; Utf8WithoutBOM: Boolean = True): TJsonArray	Возвращает JSON-массив, созданный из потока. Ожидается что корневой элемент JSON’а является массивом.
ParseObject(S: string): TJsonObject	Возвращает JSON-объект, созданный из строки. Ожидается что корневой элемент JSON’а является объектом.
ParseObjectFromFile(FileName: string; Utf8WithoutBOM: Boolean = True): TJsonObject	Возвращает JSON-объект, загруженный из файла. Ожидается что корневой элемент JSON’а является объект.
ParseObjectFromStream(Stream: TStream; Encoding: TEncoding = nil; Utf8WithoutBOM: Boolean = True): TJsonObject	Возвращает JSON-объект, созданный из потока. Ожидается что корневой элемент JSON’а является массивом.

Таблица 7. Методы объекта скриптов TJson.

Считывание из файла

При работе со JSON-структурой из файла следует придерживаться следующей схемы

var
  json: TJsonObject;

begin
  json := TJson.ParseObjectFromFile('c:\путь\до\файла.json');

try
  // Делаем что-нибудь
finally
  json.Free;
end;

end.

Пример работы с JSON-документом

Ниже представлен полный пример работы с JSON-документом. Подготовим документ следующего вида.

Затем создаем скрипт по работе с подготовленным JSON-документом. В скрипте пройдемся по JSON-структуре и найденные адреса электронной почты запишем в другой отдельный JSON-файл.

В результате работы скрипта на жестком диске образуется новый JSON-файл (или перезаписывается существующий файл), содержащий адреса электронной почты, найденные в первичном документе "users.json".