Разбор и создание значений JSON

Поддержка Emacs JSON (JavaScript Object Notation) предоставляет несколько функций для преобразования объектов Lisp в значения JSON и обратно. Любое значение JSON можно преобразовать в объект Lisp, но не наоборот. В частности:

• В JSON используются три ключевых слова: true, null, false. true представляется символом t. По умолчанию два оставшихся представляются соответственно символами :null и :false.
• В JSON есть только числа с плавающей точкой. Они могут представлять как целые числа Lisp, так и числа Lisp с плавающей точкой.
• Строки JSON всегда являются строками Unicode в кодировке UTF-8. Строки Lisp могут содержать символы, не относящиеся к Unicode.
• В JSON есть только один тип последовательности — массив. Массивы JSON представляются с помощью векторов Lisp.
• В JSON есть только один тип отображения — объект. Объекты JSON представляются с помощью хеш-таблиц, ассоциативных списков или списков свойств Lisp. Если ассоциативный список или список свойств содержит несколько элементов с одинаковым ключом, при сериализации Emacs использует только первый элемент, в соответствии с поведением assq.

Обратите внимание, что nil, будучи одновременно допустимым ассоциативным списком и допустимым списком свойств, представляет {} — пустой объект JSON, а не null, false или пустой массив: все они являются различными значениями JSON.

Если какой-либо объект Lisp нельзя представить в JSON, функции сериализации сообщат об ошибке типа wrong-type-argument. Функции разбора также могут сообщить о следующих ошибках:

json-unavailable

Сообщается, если библиотека разбора недоступна.

json-end-of-file

Сообщается при преждевременном завершении входного текста.

json-trailing-content

Сообщается при обнаружении неожиданного ввода после разбора первого объекта JSON.

json-parse-error

Сообщается при обнаружении недопустимого синтаксиса JSON.

Значения верхнего уровня и вложенные объекты внутри этих значений верхнего уровня можно сериализовать в JSON. Аналогичным образом, функции разбора возвращают любое из описанных выше возможных типов.

Функция: json-serialize object &rest args

Эта функция возвращает новую однобайтовую строку Lisp, содержащую представление object в формате JSON. Аргумент args представляет собой список пар «ключевое слово/аргумент». Допускаются следующие ключевые слова:

:null-object

Значение определяет, какой объект Lisp использовать для представления ключевого слова JSON null. По умолчанию используется символ :null.

:false-object

Значение определяет, какой объект Lisp использовать для представления ключевого слова JSON false. По умолчанию используется символ :false.

Функция: json-insert object &rest args

Эта функция вставляет представление object в формате JSON в текущий буфер перед точкой. Аргументы args интерпретируются так же, как в json-serialize.

Функция: json-parse-string string &rest args

Эта функция разбирает значение JSON в string, которая должна быть строкой Lisp. Если string не содержит допустимый объект JSON, эта функция сообщает об ошибке json-parse-error.

Аргумент args представляет собой список пар «ключевое слово/аргумент». Допускаются следующие ключевые слова:

:object-type

Значение определяет, какой объект Lisp использовать для представления отображений ключ-значение объекта JSON. Можно указать hash-table (значение по умолчанию), чтобы создавать хеш-таблицы со строками в качестве ключей; alist, чтобы использовать ассоциативные списки с символами в качестве ключей; или plist, чтобы использовать списки свойств с ключевыми символами в качестве ключей.

:array-type

Значение определяет, какой объект Lisp использовать для представления массива JSON. Можно указать array (значение по умолчанию), чтобы использовать массивы Lisp; или list, чтобы использовать списки.

:null-object

Значение определяет, какой объект Lisp использовать для представления ключевого слова JSON null. По умолчанию используется символ :null.

:false-object

Значение определяет, какой объект Lisp использовать для представления ключевого слова JSON false. По умолчанию используется символ :false.

Функция: json-parse-buffer &rest args

Эта функция считывает следующее значение JSON из текущего буфера, начиная с точки. Если буфер содержит допустимый объект JSON, она перемещает точку в позицию сразу после этого значения; в противном случае сообщает об ошибке json-parse-error и не перемещает точку. Аргументы args интерпретируются так же, как в json-parse-string.