This is the jsown Reference Manual, version 1.0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Jun 15 06:02:20 2025 GMT+0.
The main system appears first, followed by any subsystem dependency.
jsownFast JSON parsing library. Mainly geared torwards fetching only a few keys of many objects, but efficient for other types of content too
Aad Versteden <madnificent@gmail.com>
Aad Versteden <madnificent@gmail.com>
MIT
1.0.1
packages.lisp (file).
accessors.lisp (file).
reader.lisp (file).
writer.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
jsown/accessors.lisppackages.lisp (file).
jsown (system).
do-json-keys (macro).
empty-object (function).
extend-js (macro).
keyp (function).
keywords (function).
new-js (macro).
remkey (function).
(setf val) (setf expander).
val (function).
val-safe (function).
append-key (function).
jsown-object-p (function).
key-val (function).
overwrite-val (function).
push-key (function).
jsown/reader.lispaccessors.lisp (file).
jsown (system).
*parsed-empty-list-value* (special variable).
*parsed-false-value* (special variable).
*parsed-null-value* (special variable).
*parsed-true-value* (special variable).
build-key-container (compiler macro).
build-key-container (function).
filter (macro).
parse (compiler macro).
parse (function).
parse-with-container (function).
with-injective-reader (macro).
+assume-fixnums+ (constant).
+compile-unescape-json-strings+ (constant).
buffer (structure).
buffer-index (reader).
(setf buffer-index) (writer).
buffer-mark (reader).
(setf buffer-mark) (writer).
buffer-p (function).
buffer-string (reader).
(setf buffer-string) (writer).
build-buffer (function).
build-character-tree (compiler macro).
build-character-tree (function).
build-tree (function).
char-in-arr (function).
copy-buffer (function).
current-char (function).
decr-char (function).
fetch-char (function).
find-first-elts (function).
high-surrogate-p (function).
iterate-tree (function).
make-buffer (function).
make-jsown-filter (function).
mark-buffer (function).
mark-length (function).
next-char (function).
next-char/ (function).
next-char/i (function).
parse-string (function).
peek-behind-char (function).
read-array (function).
read-key (function).
read-number (function).
read-number* (macro).
read-object (function).
read-partial-key (function).
read-partial-object (function).
read-value (function).
set-read-number-part (macro).
skip-array (function).
skip-key (function).
skip-number (function).
skip-object (function).
skip-string (function).
skip-to (function).
skip-to/ (function).
skip-until (function).
skip-until* (function).
skip-until/ (function).
skip-value (function).
subseq-buffer-mark (function).
subseq-tree (function).
subseq-until (function).
subseq-until/ (function).
subseq-until/unescape (function).
test-reader-speed (function).
unescape-string/count (function).
jsown/writer.lispreader.lisp (file).
jsown (system).
as-js-bool (function).
as-js-null (function).
initialize-instance (method).
json-encoded-content (class).
to-json (generic function).
to-json* (function).
content (reader method).
list-is-object-p (function).
list-to-json (function).
object-to-json (function).
supplementary-plane-p (function).
write-number* (function).
write-object-to-stream (function).
write-string* (function).
Packages are listed by definition order.
jsowncommon-lisp.
*parsed-empty-list-value* (special variable).
*parsed-false-value* (special variable).
*parsed-null-value* (special variable).
*parsed-true-value* (special variable).
as-js-bool (function).
as-js-null (function).
build-key-container (compiler macro).
build-key-container (function).
do-json-keys (macro).
empty-object (function).
extend-js (macro).
filter (macro).
json-encoded-content (class).
keyp (function).
keywords (function).
new-js (macro).
parse (compiler macro).
parse (function).
parse-with-container (function).
remkey (function).
to-json (generic function).
to-json* (function).
(setf val) (setf expander).
val (function).
val-safe (function).
with-injective-reader (macro).
+assume-fixnums+ (constant).
+compile-unescape-json-strings+ (constant).
append-key (function).
buffer (structure).
buffer-index (reader).
(setf buffer-index) (writer).
buffer-mark (reader).
(setf buffer-mark) (writer).
buffer-p (function).
buffer-string (reader).
(setf buffer-string) (writer).
build-buffer (function).
build-character-tree (compiler macro).
build-character-tree (function).
build-tree (function).
char-in-arr (function).
content (generic reader).
copy-buffer (function).
current-char (function).
decr-char (function).
fetch-char (function).
find-first-elts (function).
high-surrogate-p (function).
iterate-tree (function).
jsown-object-p (function).
key-val (function).
list-is-object-p (function).
list-to-json (function).
make-buffer (function).
make-jsown-filter (function).
mark-buffer (function).
mark-length (function).
next-char (function).
next-char/ (function).
next-char/i (function).
object-to-json (function).
overwrite-val (function).
parse-string (function).
peek-behind-char (function).
push-key (function).
read-array (function).
read-key (function).
read-number (function).
read-number* (macro).
read-object (function).
read-partial-key (function).
read-partial-object (function).
read-value (function).
set-read-number-part (macro).
skip-array (function).
skip-key (function).
skip-number (function).
skip-object (function).
skip-string (function).
skip-to (function).
skip-to/ (function).
skip-until (function).
skip-until* (function).
skip-until/ (function).
skip-value (function).
subseq-buffer-mark (function).
subseq-tree (function).
subseq-until (function).
subseq-until/ (function).
subseq-until/unescape (function).
supplementary-plane-p (function).
test-reader-speed (function).
unescape-string/count (function).
write-number* (function).
write-object-to-stream (function).
write-string* (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
value to emit when parsing a json empty list ’[]’
value to emit when parsing json’s ’false’
value to emit when parsing json’s ’null’
value to emit when parsing json’s ’true’
Iterates over the json key-value pairs
fills in a bunch of jsown values for obj. each spec should contain a list with the first element being the string which represents the key and the second being the form which evaluates to the value to which the key should be set.
it is heavily related to jsown-object, which fills in an empty object.
eg: (jsown-values (empty-object)
("kind" "onyx.Groupbox")
("components" (list (jsown-object
("content" "Hello World")
("tag" "h1"))
(jsown-object ("tag" "p") ("content" "This is jsown talkin!")))))
Fancy filtering for jsown-parsed objects.
spec can be one of the following:
[object] key to find. will transform into (jsown:val value key)
[cl:map] use this modifier with an [object] modifier after it, to filter all elements in the list.
creates a new empty object and fills it is per jsown-values
Rebinds *parsed-*-value* so that reading json documents is injective and converting them back to json yields roughly the same document as the original.
Rebinds:
- *parsed-true-value* => :true
- *parsed-false-value* => :false
- *parsed-null-value* => :null
see (setf getf) and val
val (function).
returns <value> as a boolean value (in jsown format)
returns <value> with nil being javascript’s null (in jsown format).
Builds an internal structure to speed up the keywords which you can read. This should be used when the keywords needed are not known at compiletime, but you still want to parse those keywords of a lot of documents.
If the keywords you are interested in are known at compiletime, the use of #’parse will automatically expand the kewords at compiletime.
parse-with-container takes the result of this function and will return the keywords which have been inserted here.
Returns an empty object which can be used to build new objects upon
Returns non-nil iff <object> has key <key>.
Returns a list of all the keywords contained in the object
Reads a json object from the given string, with the given keywords being the keywords which are fetched from the object. All parse functions assume <string> is not an empty json object. (string/= string "{}")
Parses the keywords which have been specified in the container from the json string json-string.
For most cases you can just use the parse function without a special key container. This is only here to support some cases where the building of the key container takes too much time.
See #’parse for the normal variant.
See #’build-key-container for a way to build new keyword containers.
Removes key from object.
Converts an object in internal jsown representation to a string containing the json representation
Returns the value of the given key in object
Returns the value of <key> in <object> if <object> existed, or nil if it did not. A second value is returned which indicates whether or not the key was found.
Writes the given object to json in a generic way.
(eql nil))) ¶(eql :empty-list))) ¶(eql :n))) ¶(eql :null))) ¶(eql :f))) ¶(eql :false))) ¶(eql :true))) ¶(eql :t))) ¶(eql t))) ¶symbol)) ¶hash-table)) ¶array)) ¶list)) ¶float)) ¶ratio)) ¶number)) ¶string)) ¶json-encoded-content)) ¶json-encoded-content) &key content unencoded-content &allow-other-keys) ¶describes a json object whos content is serialized already.
Compiles under the expectation that numbers (being integers and the float and non-float part of floats are fixnums. By default this is turned off. The performance hit seems to be around 2% to 8% in the mixed reader speed test.
Compiles support for unescaping json strings.
If you set this to nil upon compilation time strings and keywords aren’t escaped. This makes the library incompliant with json, but it does make it a few % faster.
Could be handy when used in a mapreduce situation where you don’t mind debugging and speed is of utmost importance.
This macro should be compared to inlined functions with respect to speed. The macro creates a tree of spaghetti code that can read jsown numbers to lisp numbers.
Appends the given key to the object
mark.
Makes a new buffer and ensures the string is of the correct type
Builds a character tree from a set of strings
Builds a tree from a range of lists and a function to compare its elements by
Returns t if <char> is found in <char-arr>, returns nil otherwise
Returns the current character the buffer is pointing to
Sets the pointer to the previous char in the buffer
Reads a character from the buffer and increases the index
character numbers between U+D800 and U+DFFF (inclusive) are reserved for use with the UTF-16 encoding form (as surrogate pairs) and do not directly represent characters.
Iterates a character-tree with the given character
Returns two values, being the new tree and whether or not this is an end-point.
returns non-nil iff we expect <object> to be a jsown object.
Returns the list which represents the key-val pair in the json object
Fancy filtering for jsown-parsed objects, functional implementation. look at jsown-filter for a working version.
Sets the mark of the buffer to the current character
Returns the current amount of characters in the marked piece of the buffer
Sets the pointer to the next char in the buffer
Sets the pointer to the next char in the buffer, ignores escaped characters (they start with a \) through
Does what next-char/ does, but returns nil if no char was skipped or t if a char was skipped.
Overwrites the given key’s value with value. Errors out if the key didn’t exist
Reads a JSON string from the stream
PRE: assumes the buffer’s index is at the starting "
POST: returns the matching string without converting escaped characters to their internal representation
POST: the buffer’s index is right after the ending "
Adds the given key to the object at front
Reads a JSON array from the stream
PRE: assumes the buffer’s index is at the starting [
POST: returns a list containing all read objects
POST: the buffer’s index is right after the ending ]
Reads a key from the key-value list.
PRE: Assumes the buffer’s index is at the starting " of the key
POST: The buffer’s index is right after the ending " of the key
Reads a number from the buffer.
PRE: assumes the index is pointing to the first character representing the number
POST: the value of the character is returned
POST: the buffer’s index is at the position right after the last character representing the number
reads an object, starting with { and ending with } into a in internal jsown object
reads a key from the buffer.
PRE: Assumes the buffer’s index is at the starting " of the key
POST: Returns (values key t) if the key was found as a valid key in the tree, or (values nil nil) if it was not
POST: The buffer’s index is right after the ending " of the key
Reads an object from the buffer, but only when the key matches a key in the tree
Reads a value from the stream.
This searches for the first meaningful character, and delegates to the right function for that character
Skips the contents of an array from the buffer PRE: assumes the buffer’s index is at the starting [ POST: the buffer’s index is right after the ending ]
Skips a key from the key-value list.
PRE: Assumes the buffer’s index is at the starting " of the key
POST: The buffer’s index is right after the ending " of the key
Skips a number from the buffer
PRE: assumes the index is pointing to the first character representing the number.
POST: the buffer’s index is at the position right after the last character representing the number, possibly skipping spaces after that position
Skips an object from the buffer
PRE: Assumes the buffer’s index is at the starting { of the object
POST: The buffer’s index is right after the ending } of the object
Skips the contents of an input string from the buffer. PRE: assumes the buffer’s index is at the starting " POST: the buffer’s index is right after the ending "
Skips characters until <char> has been found. <char> is the last char which is skipped see: skip-until
What skip-to does, but with the ignoring of \
Skips characters until <char> has been found. <char> is NOT skipped See: skip-to
Skips characters until one of the characters in <char-arr> has been found. The character which was found is not read from the buffer.
What skip-until does, but with \ escaping
Skips a value from the stream.
This searches for the first meaningful character, and delegates to the right function for skipping that
Returns the content between index and mark for the current buffer result: (subseq buffer-string mark index))
Returns a sequence of the buffer, reading everything that matches with the given tree before end-char is found. end-char is not read from the buffer
Returns nil if no sequence matching the tree could be found. It then stops iterating at the failed position
Skips #\
Returns a subsequence of stream, reading everything before a character belonging to char-arr is found. The character which was found is not read from the buffer
Does what subseq-until does, but does escaping too
Does what subseq-until/ does, but unescapes the returned string
character numbers between U+010000 and U+10FFFF (inclusive) are encoded as a surrogate pair.
Unescapes the given string based on JSOWN’s spec
json-encoded-content)) ¶automatically generated reader method
A string-buffer which is used to operate on the strings
The use of a string-buffer allows us to read the data in bulk, and to operate on it, by using simple index manipulations.
Reading the string up front removes the hassle of having a fixed-size maximal input
| Jump to: | (
A B C D E F G H I J K L M N O P R S T U V W |
|---|
| Jump to: | (
A B C D E F G H I J K L M N O P R S T U V W |
|---|
| Jump to: | *
+
C I M S |
|---|
| Jump to: | *
+
C I M S |
|---|
| Jump to: | A B C F J P R S W |
|---|
| Jump to: | A B C F J P R S W |
|---|