Парсинг и генерация значений 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.

Функция: json-available-p

Этот предикат возвращает не-nil значение, если Emacs был скомпилирован с поддержкой 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, которая содержит представление JSON объекта object. Аргумент args — это список пар ключ/значение. Принимаются следующие ключи:

:null-object

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

:false-object

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

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

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

Функция: 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.