This is the njson Reference Manual, version 1.2.2, generated automatically by Declt version 4.0 beta 2 "William Riker" on Tue Jul 15 06:05:35 2025 GMT+0.
The main system appears first, followed by any subsystem dependency.
njsonNJSON is a JSON handling framework with the focus on convenience and brevity.
Atlas Engineer LLC
(GIT https://github.com/atlas-engineer/njson.git)
BSD-3 Clause
1.2.2
package.lisp (file).
conditions.lisp (file).
njson.lisp (file).
functions.lisp (file).
macros.lisp (file).
aliases.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
njson/njson.asdnjson/package.lispnjson/conditions.lispnjson/njson.lispnjson/functions.lispnjson/macros.lispnjson/aliases.lispnjson/conditions.lisppackage.lisp (file).
njson (system).
decode-from-stream-not-implemented (condition).
encode-to-stream-not-implemented (condition).
invalid-key (condition).
invalid-pointer (condition).
jerror (condition).
no-key (condition).
non-indexable (condition).
value-mismatch (condition).
actual (reader method).
(setf actual) (writer method).
deprecated (reader method).
(setf deprecated) (writer method).
deprecated (condition).
expected (reader method).
(setf expected) (writer method).
json-short-print (function).
key (reader method).
key (reader method).
(setf key) (writer method).
(setf key) (writer method).
object (reader method).
object (reader method).
object (reader method).
(setf object) (writer method).
(setf object) (writer method).
(setf object) (writer method).
pointer (reader method).
(setf pointer) (writer method).
read-new-key (function).
read-new-pointer (function).
read-new-value (function).
replacement (reader method).
(setf replacement) (writer method).
type-num (function).
value (reader method).
(setf value) (writer method).
njson/njson.lispconditions.lisp (file).
njson (system).
decode (generic function).
decode-from-file (generic function).
decode-from-stream (generic function).
decode-from-string (generic function).
encode (generic function).
encode-to-file (generic function).
encode-to-stream (generic function).
encode-to-string (generic function).
njson/functions.lispnjson.lisp (file).
njson (system).
ensure-array (generic function).
ensure-object (generic function).
jcopy (generic function).
jget (generic function).
(setf jget) (generic function).
jget* (generic function).
jkeys (generic function).
jnot (function).
jtruep (generic function).
make-singular-array (function).
parse-pointer-pathname (function).
njson/macros.lispfunctions.lisp (file).
njson (system).
check-value (function).
njson/aliases.lispmacros.lisp (file).
njson (system).
Packages are listed by definition order.
njson/aliasesShort aliases for the regular njson functions.
Perfect with j: package-local-nickname, disastrous when :use-d.
common-lisp.
@ (function).
(setf @) (function).
and (macro).
bind (macro).
copy (generic function).
decode (generic function).
encode (generic function).
ensure-array (generic function).
ensure-object (generic function).
get (generic function).
(setf get) (generic function).
get* (generic function).
if (macro).
keys (generic function).
match (macro).
not (function).
or (macro).
true (generic function).
true? (generic function).
truep (generic function).
when (macro).
njsonNJSON is a convenience library for JSON handling. Important functions/APIs:
- ‘njson:encode’ and ‘njson:decode’ as universal (en|de)coding functions working
on strings, streams, and pathnames.
- ‘njson:jget’ (and ‘njson:get_’ alias) to get the value from decoded
and arbitrarily nested JSON array/object.
- ‘njson:jtruep’ (and aliases) to check the non-falsity of a decoded
value.
- ‘njson:jif’, ‘njson:jwhen’, ‘njson:jor’, ‘njson:jand’, and
‘njson:jnot’ (and aliases) as convenience macros for JSON
non-falsity-based control flow.
Generics to implement:
- ‘njson:encode-to-stream’ and ‘njson:decode-from-stream’ as the basic
methods to specialize for every backend.
- ‘njson:encode-to-string’ and ‘njson:encode-to-file’, as more specific
methods to speed things up.
- ‘njson:decode-from-string’ and ‘njson:decode-from-file’, as more
specific decoding methods.
common-lisp.
decode (generic function).
decode-from-file (generic function).
decode-from-stream (generic function).
decode-from-stream-not-implemented (condition).
decode-from-string (generic function).
encode (generic function).
encode-to-file (generic function).
encode-to-stream (generic function).
encode-to-stream-not-implemented (condition).
encode-to-string (generic function).
ensure-array (generic function).
ensure-object (generic function).
invalid-key (condition).
invalid-pointer (condition).
jand (macro).
jbind (macro).
jcopy (generic function).
jerror (condition).
jget (generic function).
(setf jget) (generic function).
jget* (generic function).
jif (macro).
jkeys (generic function).
jmatch (macro).
jnot (function).
jor (macro).
jtrue-p (generic function).
jtrue? (generic function).
jtruep (generic function).
jwhen (macro).
no-key (condition).
non-indexable (condition).
value-mismatch (condition).
actual (generic reader).
(setf actual) (generic writer).
check-value (function).
deprecated (generic reader).
(setf deprecated) (generic writer).
deprecated (condition).
expected (generic reader).
(setf expected) (generic writer).
json-short-print (function).
key (generic reader).
(setf key) (generic writer).
make-singular-array (function).
object (generic reader).
(setf object) (generic writer).
parse-pointer-pathname (function).
pointer (generic reader).
(setf pointer) (generic writer).
read-new-key (function).
read-new-pointer (function).
read-new-value (function).
replacement (generic reader).
(setf replacement) (generic writer).
type-num (function).
value (generic reader).
(setf value) (generic writer).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Match the FORM against DESTRUCTURING-PATTERN.
The pattern might be:
- A symbol, in which case the current chosen form is bound to it. If
the symbol is _, simply skip the form.
- A literal form:
- String or number: compare with ‘equal’.
- Keywords :TRUE, :FALSE, and :NULL, matching T, NIL, and :NULL
respectively.
- If the pattern is a property list of string+pattern pairs, match the
string+pattern pairs inside it to the provided JSON object and
resolve them recursively.
- If the pattern is a list of symbols (VAR &optional VAR-P), these are
bound to the respective values of ‘jget’. It is a good way to make
‘jbind’ to be more lenient to missing keys, because the default
behavior is to error on missing data.
- If the pattern is an inline vector, match it against a JSON array
with at least as many elements as provided in the vector. Match
every form in the vector against the element with the same index.
If the DESTRUCTURING-PATTERN doesn’t match the object, throw
‘value-mismatch’.
Underlying ‘jget’ can throw errors for the exceptionally malformed inputs. See ‘jget’ documentation for the types of errors it throws.
Example:
("hello" hello "a" _ "b" b
"array" #(first second third _))
matches a JSON object
{"hello": 3, "a": 8, "b": 3, "c": null, "array": [1, 2, 3, 4]}
and binds
- HELLO to 3
- B to 3
- FIRST to 1
- SECOND to 2
- THIRD to 3
It also checks that "a" key is present in the object and there’s a
fourth element in the nested array.
See more examples in njson tests.
JSON-aware version of ‘cl:if’.
If TEST is ‘jtruep’ evaluate THEN, otherwise evaluate ELSE.
jif.
JSON-aware version of ‘cl:and’.
Match the FORM against DESTRUCTURING-PATTERN.
The pattern might be:
- A symbol, in which case the current chosen form is bound to it. If
the symbol is _, simply skip the form.
- A literal form:
- String or number: compare with ‘equal’.
- Keywords :TRUE, :FALSE, and :NULL, matching T, NIL, and :NULL
respectively.
- If the pattern is a property list of string+pattern pairs, match the
string+pattern pairs inside it to the provided JSON object and
resolve them recursively.
- If the pattern is a list of symbols (VAR &optional VAR-P), these are
bound to the respective values of ‘jget’. It is a good way to make
‘jbind’ to be more lenient to missing keys, because the default
behavior is to error on missing data.
- If the pattern is an inline vector, match it against a JSON array
with at least as many elements as provided in the vector. Match
every form in the vector against the element with the same index.
If the DESTRUCTURING-PATTERN doesn’t match the object, throw
‘value-mismatch’.
Underlying ‘jget’ can throw errors for the exceptionally malformed inputs. See ‘jget’ documentation for the types of errors it throws.
Example:
("hello" hello "a" _ "b" b
"array" #(first second third _))
matches a JSON object
{"hello": 3, "a": 8, "b": 3, "c": null, "array": [1, 2, 3, 4]}
and binds
- HELLO to 3
- B to 3
- FIRST to 1
- SECOND to 2
- THIRD to 3
It also checks that "a" key is present in the object and there’s a
fourth element in the nested array.
See more examples in njson tests.
JSON-aware version of ‘cl:if’.
If TEST is ‘jtruep’ evaluate THEN, otherwise evaluate ELSE.
Similar to Trivia match macro, match the FORM (JSON value) against CLAUSES.
CLAUSES are (PATTERN . BODY) forms, where
- PATTERN is a ‘jbind’ destructuring pattern.
- And BODY is an implicit progn.
If PATTERN matches successfully in ‘jbind’, then BODY is executed with
the variables from the PATTERN bound to the respective values, as per
‘jbind’.
The last clause could start with T, OTHERWISE, ELSE, or _, and it will be invoked if other patterns don’t match. If there’s no such clause, ‘jmatch’ will simply return NIL on no matching patterns.
JSON-aware version of ‘cl:or’.
JSON-aware version of ‘cl:when’. If TEST is ‘jtruep’ evaluate BODY.
Similar to Trivia match macro, match the FORM (JSON value) against CLAUSES.
CLAUSES are (PATTERN . BODY) forms, where
- PATTERN is a ‘jbind’ destructuring pattern.
- And BODY is an implicit progn.
If PATTERN matches successfully in ‘jbind’, then BODY is executed with
the variables from the PATTERN bound to the respective values, as per
‘jbind’.
The last clause could start with T, OTHERWISE, ELSE, or _, and it will be invoked if other patterns don’t match. If there’s no such clause, ‘jmatch’ will simply return NIL on no matching patterns.
JSON-aware version of ‘cl:when’. If TEST is ‘jtruep’ evaluate BODY.
Alias for ‘jget’ that indexes OBJECT with KEYS. Setf-able.
JSON-aware version of ‘cl:not’.
Copy the OBJECT, potentially creating an identical one. Coerce all JSON arrays to adjustable vectors.
Decode OBJECT from JSON source FROM.
FROM can be a string, stream, pathname, or byte array.
Distinguishes between null/false and arrays/objects.
Decodes:
- null as :NULL,
- false as nil,
- true as t,
- arrays as vectors,
- objects as hash-tables.
Decode OBJECT from JSON source FROM.
FROM can be a string, stream, pathname, or byte array.
Distinguishes between null/false and arrays/objects.
Decodes:
- null as :NULL,
- false as nil,
- true as t,
- arrays as vectors,
- objects as hash-tables.
Decode JSON from FILE.
Specialize on ‘pathname’ to make NJSON better decode JSON files.
Uses ‘decode-from-stream’ by default.
Decode JSON from STREAM.
Specialize on ‘stream’ to make NJSON decode JSON.
Decode JSON from STRING.
Specialize on ‘string’ to make NJSON better decode JSON strings.
Uses ‘decode-from-stream’ by default.
Encode OBJECT to JSON output spec TO.
TO can be:
- T, in which case ‘*standard-output*’ is used as encoding stream.
- NIL, in which case OBJECT is encoded to a string.
- STREAM, in which case OBJECT is encoded to it.
- PATHNAME, in which case OBJECT is encoded to the file designated by the pathname.
Distinguishes between null and false.
Encodes:
- :NULL as null,
- nil as false.
Encode OBJECT to JSON output spec TO.
TO can be:
- T, in which case ‘*standard-output*’ is used as encoding stream.
- NIL, in which case OBJECT is encoded to a string.
- STREAM, in which case OBJECT is encoded to it.
- PATHNAME, in which case OBJECT is encoded to the file designated by the pathname.
Distinguishes between null and false.
Encodes:
- :NULL as null,
- nil as false.
Encode OBJECT to FILE.
Specialize on ‘pathname’ (and, optionally, OBJECT types) to make NJSON better encode JSON to files.
Uses ‘encode-to-stream’ by default.
Encode OBJECT to STREAM as JSON.
Specialize on ‘stream’ (and, optionally, OBJECT types) to make NJSON encode JSON.
Encode OBJECT to JSON string.
Specialize on ‘string’ (and, optionally, OBJECT types) to make NJSON better encode JSON to strings.
Uses ‘encode-to-stream’ by default.
Ensure that the return value is an array.
If OBJECT is an array already, return it.
If it’s a literal value, wrap it into a one-element array.
If it’s an object:
- When CONVERT-OBJECTS is T, put all the values into an array (order
not guaranteed).
- Otherwise wrap the object into an array.
Ensure that the return value is an array.
If OBJECT is an array already, return it.
If it’s a literal value, wrap it into a one-element array.
If it’s an object:
- When CONVERT-OBJECTS is T, put all the values into an array (order
not guaranteed).
- Otherwise wrap the object into an array.
hash-table) &key convert-objects &allow-other-keys) ¶sequence) &key &allow-other-keys) ¶string) &key &allow-other-keys) ¶null) &key &allow-other-keys) ¶Ensure that the return value is a JSON object.
If OBJECT is an object already, return it, checking KEY presence.
If it’s anything else, wrap it into an object with OBJECT under KEY.
Throws errors from underlying ‘jget’.
Ensure that the return value is a JSON object.
If OBJECT is an object already, return it, checking KEY presence.
If it’s anything else, wrap it into an object with OBJECT under KEY.
Throws errors from underlying ‘jget’.
Get the value at KEY-OR-INDEX in OBJECT.
KEY-OR-INDEX can be
- an integer (for array indexing),
- a string (for object keying),
- a pathname (with JSON Pointer syntax),
- a sequence of integers and strings (to index the nested structures).
- an empty sequence/pathname (to match the whole object).
Return two values: the value under KEY-OR-INDEX and whether this value
was found.
- (Starting from version 2) Throw ‘no-key’ when the key is not present in the object.
- Throw ‘invalid-key’ if using the wrong index type.
- Throw ‘non-indexable’ when trying to index something other than
JSON arrays or objects.
- Throw ‘invalid-pointer’ when using JSON Pointer with invalid syntax
as key.
For example, to get the data from a structure like
{"data": [1, 2, {"three": 3}]}
you can use
(jget #("data" 2 "three") data)
;; => 3, T
OBJECT can be JSON array or object, which in Lisp translates to
‘array’ or ‘hash-table’.
‘jget*’ is a more structured and strict version of ‘jget’, enforcing
the ‘no-key’ condition and removing the two-valued approach because of
that. ‘jget*’ will be merged into ‘jget’ in version 2.
jget.
Set the value at KEY-OR-INDEX in OBJECT.
The arguments are the same as in ‘jget’, except KEY-OR-INDEX cannot be
an empty pathname/sequence (because setting the object itself to a new
value is not possible in CL, unless it’s a place, which is not
guaranteed for ‘jget’ arguments).
- Throw ‘invalid-key’ if using the wrong index type.
- Throw ‘non-indexable’ when trying to index something other than
JSON arrays or objects.
- Throw ‘invalid-pointer’ when using JSON Pointer with invalid syntax
as key.
OBJECT can be JSON array or object, which in Lisp translates to ‘array’ or ‘hash-table’.
A version of ‘jget’ that’s more strict regarding missing keys.
Copy the OBJECT, potentially creating an identical one. Coerce all JSON arrays to adjustable vectors.
Get the value at KEY-OR-INDEX in OBJECT.
KEY-OR-INDEX can be
- an integer (for array indexing),
- a string (for object keying),
- a pathname (with JSON Pointer syntax),
- a sequence of integers and strings (to index the nested structures).
- an empty sequence/pathname (to match the whole object).
Return two values: the value under KEY-OR-INDEX and whether this value
was found.
- (Starting from version 2) Throw ‘no-key’ when the key is not present in the object.
- Throw ‘invalid-key’ if using the wrong index type.
- Throw ‘non-indexable’ when trying to index something other than
JSON arrays or objects.
- Throw ‘invalid-pointer’ when using JSON Pointer with invalid syntax
as key.
For example, to get the data from a structure like
{"data": [1, 2, {"three": 3}]}
you can use
(jget #("data" 2 "three") data)
;; => 3, T
OBJECT can be JSON array or object, which in Lisp translates to
‘array’ or ‘hash-table’.
‘jget*’ is a more structured and strict version of ‘jget’, enforcing
the ‘no-key’ condition and removing the two-valued approach because of
that. ‘jget*’ will be merged into ‘jget’ in version 2.
Set the value at KEY-OR-INDEX in OBJECT.
The arguments are the same as in ‘jget’, except KEY-OR-INDEX cannot be
an empty pathname/sequence (because setting the object itself to a new
value is not possible in CL, unless it’s a place, which is not
guaranteed for ‘jget’ arguments).
- Throw ‘invalid-key’ if using the wrong index type.
- Throw ‘non-indexable’ when trying to index something other than
JSON arrays or objects.
- Throw ‘invalid-pointer’ when using JSON Pointer with invalid syntax
as key.
OBJECT can be JSON array or object, which in Lisp translates to ‘array’ or ‘hash-table’.
sequence) object) ¶integer) (object array)) ¶string) (object hash-table)) ¶pathname) object) ¶string) (object array)) ¶integer) (object hash-table)) ¶string)) ¶A version of ‘jget’ that’s more strict regarding missing keys.
sequence) object) ¶integer) (object array)) ¶string) (object hash-table)) ¶pathname) object) ¶string) (object array)) ¶integer) (object hash-table)) ¶string) (object string)) ¶integer) (object string)) ¶Get keys to index OBJECT with, as a list of integers/strings. If the OBJECT is not a JSON array/object, throws ‘non-indexable’.
Test OBJECT for truthiness in JSON terms.
Recognize all the values true, except for null and false. This is to
make the transition from JSON to Lisp (2 false values -> 1 false
value) smoother.
Unlike JavaScript, empty strings and zero are not false (because this behavior is confusing).
Test OBJECT for truthiness in JSON terms.
Recognize all the values true, except for null and false. This is to
make the transition from JSON to Lisp (2 false values -> 1 false
value) smoother.
Unlike JavaScript, empty strings and zero are not false (because this behavior is confusing).
Test OBJECT for truthiness in JSON terms.
Recognize all the values true, except for null and false. This is to
make the transition from JSON to Lisp (2 false values -> 1 false
value) smoother.
Unlike JavaScript, empty strings and zero are not false (because this behavior is confusing).
Get keys to index OBJECT with, as a list of integers/strings. If the OBJECT is not a JSON array/object, throws ‘non-indexable’.
Test OBJECT for truthiness in JSON terms.
Recognize all the values true, except for null and false. This is to
make the transition from JSON to Lisp (2 false values -> 1 false
value) smoother.
Unlike JavaScript, empty strings and zero are not false (because this behavior is confusing).
Test OBJECT for truthiness in JSON terms.
Recognize all the values true, except for null and false. This is to
make the transition from JSON to Lisp (2 false values -> 1 false
value) smoother.
Unlike JavaScript, empty strings and zero are not false (because this behavior is confusing).
Test OBJECT for truthiness in JSON terms.
Recognize all the values true, except for null and false. This is to
make the transition from JSON to Lisp (2 false values -> 1 false
value) smoother.
Unlike JavaScript, empty strings and zero are not false (because this behavior is confusing).
Incomplete decoding implementation error.
Incomplete encoding implementation error.
The condition thrown on using wrong key with object/array.
Condition thrown when trying to index an object with invalid pointer.
:pointer
Fundamental error class all the NJSON errors inherit from.
error.
Condition thrown when trying to index an object/array with a key not present in it.
The condition thrown on trying to index non-object/array.
:value
Condition thrown when getting a value not matching ‘jbind’/‘jmatch’ specification.
Check that JSON value in OBJECT at INDICES is ‘equal’ to EXPECTED specification.
Produce a string with a short object representation for debugging.
May actually produce long results for objects/arrays with many members. But it’s implied that these are rare cases and don’t need special treatment.
Parse POINTER-PATHNAME per JSON Pointer rules (https://www.rfc-editor.org/rfc/rfc6901). Only supports JSON string representation, not the URL one.
value-mismatch)) ¶value-mismatch)) ¶deprecated)) ¶deprecated)) ¶value-mismatch)) ¶value-mismatch)) ¶no-key)) ¶no-key)) ¶key.
invalid-key)) ¶invalid-key)) ¶key.
value-mismatch)) ¶value-mismatch)) ¶no-key)) ¶no-key)) ¶invalid-key)) ¶invalid-key)) ¶invalid-pointer)) ¶invalid-pointer)) ¶deprecated)) ¶deprecated)) ¶non-indexable)) ¶non-indexable)) ¶| Jump to: | (
@
A B C D E F G I J K M N O P R T V W |
|---|
| Jump to: | (
@
A B C D E F G I J K M N O P R T V W |
|---|
| Jump to: | A D E K O P R S V |
|---|
| Jump to: | A D E K O P R S V |
|---|
| Jump to: | A C D E F I J M N P S V |
|---|
| Jump to: | A C D E F I J M N P S V |
|---|