SimpLight поддерживает работу с JSON-документами в скриптах. Основные типы для работы с JSON-форматом это:
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
, указав имя поля:
|
Узнать тип поля объекта можно с помощью свойства Types
. Например:
|
Название метода | Описание метода |
---|---|
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
способен обрабатывать значения различных типов. Наполнить массив можно так:
|
Добавить элементы массива можно с помощью метода Add
принимающий тип Variant
или метод с конкретным типом Add
добавив букву типа из Таблицы 1.
После того как массив был наполнен можно его обойти. Обход выполняется с помощью цикла while
и индекса.
|
Заметим, что при доступе к элементу с помощью индекса явно указывается тип значения, к которому будет приведено значения элемента массива, в виде свойства. Похожий механизм используется в TJsonObject
для доступа к полям объекта.
Название метода | Описание метода |
Assign(ASource: TJsonArray) | Присвоение полей переданного массива с удалением элементов целевого объекта. |
AddT(AValue: K) | Позволяет добавить значение в массив, где T – первая буква тип данных, K – тип данных. см. Таблица 1. |
AddUtcDateTime(AValue: TDateTime) | Добавляет дату и время по часовому поясу UTC в массив. |
AddArray: TJsonArray | Добавляет новый массив в текущий массив и возвращает его. |
AddObject: TJsonObject | Добавляет новый объект в текущий массив и возвращает его. |
InsertT(Index: Integer; Value: K) | Вставка нового элемента в массив, где T – первая буква тип данных, K – тип данных. см. Таблица 1. |
Ins ert(Index: Integer; Val ue: 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
является базовым типом для ранее рассмотренных 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-структурой из файла следует придерживаться следующей схемы
|
Ниже представлен полный пример работы с JSON-документом. Подготовим документ следующего вида.
Затем создаем скрипт по работе с подготовленным JSON-документом. В скрипте пройдемся по JSON-структуре и найденные адреса электронной почты запишем в другой отдельный JSON-файл.
В результате работы скрипта на жестком диске образуется новый JSON-файл (или перезаписывается существующий файл), содержащий адреса электронной почты, найденные в первичном документе "users.json".