From c4db9ca63f449901632b4dc40f12bd10a00ec1fc Mon Sep 17 00:00:00 2001 From: =?utf8?q?Mattias=20Engdeg=C3=A5rd?= Date: Mon, 1 Apr 2024 17:02:58 +0200 Subject: [PATCH] Update JSON codec doc strings * src/json.c (Fjson_serialize, Fjson_insert, Fjson_parse_string) (Fjson_parse_buffer): Make the text more readable, fix minor errors and avoid terminology confusion. (cherry picked from commit a5fbb652ed3614d6735015551564f32b80e42c53) --- src/json.c | 98 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 50 insertions(+), 48 deletions(-) diff --git a/src/json.c b/src/json.c index 486253581ff..c3244ad04d2 100644 --- a/src/json.c +++ b/src/json.c @@ -598,23 +598,27 @@ DEFUN ("json-serialize", Fjson_serialize, Sjson_serialize, 1, MANY, NULL, doc: /* Return the JSON representation of OBJECT as a string. -OBJECT must be t, a number, string, vector, hashtable, alist, plist, -or the Lisp equivalents to the JSON null and false values, and its -elements must recursively consist of the same kinds of values. t will -be converted to the JSON true value. Vectors will be converted to -JSON arrays, whereas hashtables, alists and plists are converted to -JSON objects. Hashtable keys must be strings, unique within each object. -Alist and plist keys must be symbols; if a key is duplicate, the first -instance is used. A leading colon in plist keys is elided. +OBJECT is translated as follows: + +`t' -- the JSON `true' value. +number -- a JSON number. +string -- a JSON string. +vector -- a JSON array. +hash-table -- a JSON object. Keys must be strings. +alist -- a JSON object. Keys must be symbols. +plist -- a JSON object. Keys must be symbols. + A leading colon in plist key names is elided. + +For duplicate object keys, the first value is used. The Lisp equivalents to the JSON null and false values are configurable in the arguments ARGS, a list of keyword/argument pairs: -The keyword argument `:null-object' specifies which object to use -to represent a JSON null value. It defaults to `:null'. +:null-object OBJ -- use OBJ to represent a JSON null value. + It defaults to `:null'. -The keyword argument `:false-object' specifies which object to use to -represent a JSON false value. It defaults to `:false'. +:false-object OBJ -- use OBJ to represent a JSON false value. + It defaults to `:false'. In you specify the same value for `:null-object' and `:false-object', a potentially ambiguous situation, the JSON output will not contain @@ -631,9 +635,9 @@ usage: (json-serialize OBJECT &rest ARGS) */) DEFUN ("json-insert", Fjson_insert, Sjson_insert, 1, MANY, NULL, doc: /* Insert the JSON representation of OBJECT before point. -This is the same as (insert (json-serialize OBJECT)), but potentially +This is the same as (insert (json-serialize OBJECT ...)), but potentially faster. See the function `json-serialize' for allowed values of -OBJECT. +OBJECT and ARGS. usage: (json-insert OBJECT &rest ARGS) */) (ptrdiff_t nargs, Lisp_Object *args) { @@ -1734,31 +1738,30 @@ json_parse (struct json_parser *parser, DEFUN ("json-parse-string", Fjson_parse_string, Sjson_parse_string, 1, MANY, NULL, - doc: /* Parse the JSON STRING into a Lisp object. + doc: /* Parse the JSON STRING into a Lisp value. This is essentially the reverse operation of `json-serialize', which -see. The returned object will be the JSON null value, the JSON false -value, t, a number, a string, a vector, a list, a hashtable, an alist, -or a plist. Its elements will be further objects of these types. If -there are duplicate keys in an object, all but the last one are -ignored. If STRING doesn't contain a valid JSON object, this function +see. The returned value will be the JSON null value, the JSON false +value, t, a number, a string, a vector, a list, a hash-table, an alist, +or a plist. Its elements will be further values of these types. +If STRING doesn't contain a valid JSON value, this function signals an error of type `json-parse-error'. The arguments ARGS are a list of keyword/argument pairs: -The keyword argument `:object-type' specifies which Lisp type is used -to represent objects; it can be `hash-table', `alist' or `plist'. It -defaults to `hash-table'. If an object has members with the same -key, `hash-table' keeps only the last value of such keys, while -`alist' and `plist' keep all the members. +:object-type TYPE -- use TYPE to represent JSON objects. + TYPE can be `hash-table' (the default), `alist' or `plist'. + If an object has members with the same key, `hash-table' keeps only + the last value of such keys, while `alist' and `plist' keep all the + members. -The keyword argument `:array-type' specifies which Lisp type is used -to represent arrays; it can be `array' (the default) or `list'. +:array-type TYPE -- use TYPE to represent JSON arrays. + TYPE can be `array' (the default) or `list'. -The keyword argument `:null-object' specifies which object to use -to represent a JSON null value. It defaults to `:null'. +:null-object OBJ -- use OBJ to represent a JSON null value. + It defaults to `:null'. -The keyword argument `:false-object' specifies which object to use to -represent a JSON false value. It defaults to `:false'. +:false-object OBJ -- use OBJ to represent a JSON false value. + It defaults to `:false'. usage: (json-parse-string STRING &rest ARGS) */) (ptrdiff_t nargs, Lisp_Object *args) { @@ -1782,35 +1785,34 @@ usage: (json-parse-string STRING &rest ARGS) */) DEFUN ("json-parse-buffer", Fjson_parse_buffer, Sjson_parse_buffer, 0, MANY, NULL, - doc: /* Read JSON object from current buffer starting at point. -Move point after the end of the object if parsing was successful. + doc: /* Read a JSON value from current buffer starting at point. +Move point after the end of the value if parsing was successful. On error, don't move point. -The returned object will be a vector, list, hashtable, alist, or +The returned value will be a vector, list, hashtable, alist, or plist. Its elements will be the JSON null value, the JSON false value, t, numbers, strings, or further vectors, lists, hashtables, -alists, or plists. If there are duplicate keys in an object, all -but the last one are ignored. +alists, or plists. -If the current buffer doesn't contain a valid JSON object, the +If the current buffer doesn't contain a valid JSON value, the function signals an error of type `json-parse-error'. The arguments ARGS are a list of keyword/argument pairs: -The keyword argument `:object-type' specifies which Lisp type is used -to represent objects; it can be `hash-table', `alist' or `plist'. It -defaults to `hash-table'. If an object has members with the same -key, `hash-table' keeps only the last value of such keys, while -`alist' and `plist' keep all the members. +:object-type TYPE -- use TYPE to represent JSON objects. + TYPE can be `hash-table' (the default), `alist' or `plist'. + If an object has members with the same key, `hash-table' keeps only + the last value of such keys, while `alist' and `plist' keep all the + members. -The keyword argument `:array-type' specifies which Lisp type is used -to represent arrays; it can be `array' (the default) or `list'. +:array-type TYPE -- use TYPE to represent JSON arrays. + TYPE can be `array' (the default) or `list'. -The keyword argument `:null-object' specifies which object to use -to represent a JSON null value. It defaults to `:null'. +:null-object OBJ -- use OBJ to represent a JSON null value. + It defaults to `:null'. -The keyword argument `:false-object' specifies which object to use to -represent a JSON false value. It defaults to `:false'. +:false-object OBJ -- use OBJ to represent a JSON false value. + It defaults to `:false'. usage: (json-parse-buffer &rest args) */) (ptrdiff_t nargs, Lisp_Object *args) { -- 2.39.5