When Emacs is compiled with JSON (JavaScript Object Notation) support, it provides several functions to convert between Lisp objects and JSON values. Any JSON value can be converted to a Lisp object, but not vice versa. Specifically:
true
, null
, false
.
true
is represented by the symbol t
. By default, the
remaining two are represented, respectively, by the symbols
:null
and :false
.
assq
.
Note that nil
, being both a valid alist and a valid plist,
represents {}
, the empty JSON object; not null
,
false
, or an empty array, all of which are different JSON
values.
This predicate returns non-nil
if Emacs has been built with
JSON support, and the library is available on the current
system.
If some Lisp object can’t be represented in JSON, the serialization
functions will signal an error of type wrong-type-argument
.
The parsing functions can also signal the following errors:
json-unavailable
Signaled when the parsing library isn’t available.
json-end-of-file
Signaled when encountering a premature end of the input text.
json-trailing-content
Signaled when encountering unexpected input after the first JSON object parsed.
json-parse-error
Signaled when encountering invalid JSON syntax.
Top-level values and the subobjects within these top-level values can be serialized to JSON. Likewise, the parsing functions will return any of the possible types described above.
This function returns a new Lisp string which contains the JSON representation of object. The argument args is a list of keyword/argument pairs. The following keywords are accepted:
:null-object
The value decides which Lisp object to use to represent the JSON
keyword null
. It defaults to the symbol :null
.
:false-object
The value decides which Lisp object to use to represent the JSON
keyword false
. It defaults to the symbol :false
.
This function inserts the JSON representation of object into the
current buffer before point. The argument args are interpreted
as in json-parse-string
.
This function parses the JSON value in string, which must be a
Lisp string. If string doesn’t contain a valid JSON object,
this function signals the json-parse-error
error.
The argument args is a list of keyword/argument pairs. The following keywords are accepted:
:object-type
The value decides which Lisp object to use for representing the
key-value mappings of a JSON object. It can be either
hash-table
, the default, to make hashtables with strings as
keys; alist
to use alists with symbols as keys; or plist
to use plists with keyword symbols as keys.
:array-type
The value decides which Lisp object to use for representing a JSON
array. It can be either array
, the default, to use Lisp
arrays; or list
to use lists.
:null-object
The value decides which Lisp object to use to represent the JSON
keyword null
. It defaults to the symbol :null
.
:false-object
The value decides which Lisp object to use to represent the JSON
keyword false
. It defaults to the symbol :false
.
This function reads the next JSON value from the current buffer,
starting at point. It moves point to the position immediately after
the value if contains a valid JSON object; otherwise it signals the
json-parse-error
error and doesn’t move point. The arguments
args are interpreted as in json-parse-string
.