---

33.31 Разбор и генерация значений 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, alist или plist. Когда alist или plist содержит несколько элементов с одинаковым ключом, Emacs использует только первый элемент для сериализации, в соответствии с поведением assq.

Обратите внимание, что nil, будучи как допустимым alist, так и допустимым plist, представляет {}, пустой объект 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 ¶

Эта функция возвращает новую unibyte-строку Lisp, содержащую JSON-представление object. Аргумент args — это список пар ключ/аргумент. Принимаются следующие ключевые слова:

:null-object

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

:false-object

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

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

Эта функция вставляет JSON-представление object в текущий буфер перед точкой. Аргументы 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 для использования alist с символами в качестве ключей; либо plist для использования 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.