Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the jsown Reference Manual, version 1.0.1, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:03:14 2018 GMT+0.
• Introduction: | What jsown is all about | |
• Systems: | The systems documentation | |
• Files: | The files documentation | |
• Packages: | The packages documentation | |
• Definitions: | The symbols documentation | |
• Indexes: | Concepts, functions, variables and data types |
h1. jsown, high performance Common Lisp json parser jsown is a high performance Common Lisp json parser. Its aim is to allow for the fast parsing of json objects in CL. Recently, functions and macros have been added to ease the burden of writing and editing jsown objects. jsown allows you to parse json objects quickly to a modifiable lisp list and write them back. If you only need partial retrieval of objects, jsown allows you to select the keys which you would like to see parsed. jsown also has a json writer and some helper methods to alter the json objects themselves. h2. parsing json objects In order to parse a json object, simply use the @parse@ function.Without any extra arguments, the @parse@ function will return all keywords. In order to select only a few keywords, you can add those keywords in which you're interested:(jsown:parse "{\"foo\":\"bar\",\"baz\":100.25}") =>(:OBJ ("foo" . "bar") ("baz" . 401/4))
In order to achieve high performance when parsing specific keywords, the keywords to be found should be known at compile time. The compiler-macro-function can calculate the keyword container with the requested keywords at compile-time. When specifying the keywords in which you're interested you should ignore any escaped characters. For instance, supplying the string "foo" will automatically match "f\\\\oo" too." h2. Using jsown objects jsown ships with some convience functions to inspect and alter the returned json content. The fetching of the value given to a certain keyword may be done by using the @val@ function. This function also has a setf defined on it. The @(setf val)@ function may alter the original object, it is however not guaranteed to do so.(jsown:parse "{\"foo\":\"bar\",\"frolic\":100,\"fragrance\":10.01,\"for\":\"markup\"}" "foo" "frolic" "fragrance") => (:OBJ ("foo" . "bar") ("frolic" . 100) ("fragrance" . 1001/100))
You can build objects by using the @val@ function too, albeit it doesn't look really sexy.(jsown:val '(:obj ("foo" . "bar") ("frolic" . 100) ("fragrance" . 1001/100)) "frolic") => 100 (setf (jsown:val '(:obj ("foo" . "bar") ("frolic" . 100) ("fragrance" . 1001/100)) "frolic") "I wasn't here before") => (:obj ("foo" . "bar") ("frolic" . "I wasn't here before") ("fragrance" . 1001/100))
For building objects, the macros @new-js@ and @extend-js@ can be used. @new-js@ creates a new jsown object, @extend-js@ extends an existing jsown object.(setf (jsown:val (setf (jsown:val (setf (jsown:val (jsown:empty-object) "foo") "bar") "bang") (list 1 2 3 "foo" 4 5)) "bingo") 24.93) =>(:obj ("bingo" . 24.93) ("bang" 1 2 3 "foo" 4 5) ("foo" . "bar"))
This object can be extended by use of @extend-js@. Say we store the previously built json object in the parameter @*jsown-obj*@, then we can extend it like so:(jsown:new-js ("foo" "bar") ("baz" (+ 100 0.25))) => (:obj ("baz" . 100.25) ("foo" . "bar"))
For didactical purposes, we've defined ping in more than one form. In order to see which keywords have been defined in a parsed json object, you can use the @keywords@ function:epicdb> (jsown:extend-js *jsown-obj* ("bing" "bang") ("ping" (print "Adding ping") "pong")) => (:obj ("ping" . "pong") ("bing" . "bang") ("baz" . 100.25) ("foo" . "bar"))
You can traverse over all keywords by using the @do-json-keys@ macro.(jsown:keywords '(:obj ("foo" . "bar") ("frolic" . 100) ("fragrance" . 1001/100))) => ("foo" "frolic" "fragrance")
Lastly, the @filter@ function allows you to traverse a tree of json objects and interpret its results.CL-USER> (jsown:do-json-keys (keyword value) '(:obj ("foo" . "bar") ("frolic" . 100) ("fragrance" . 1001/100)) (format T "~A => ~A~&" keyword value)) foo => bar frolic => 100 fragrance => 1001/100 NIL
h2. Writing json objects jsown supports the writing of json objects too, use the @to-json@ CLOS method for this. You can provide an implementation for this method for your own objects so those can easily be converted to json too (and it will ensure that nested objects are correctly transformed to json).(jsown:filter (jsown:new-js ("one" 100) ("two" (jsown:new-js ("three" (list (jsown:new-js ("four" (jsown:new-js ("five" "result-one")))) (jsown:new-js ("four" (jsown:new-js ("five" "result-two")))) (jsown:new-js ("four" (jsown:new-js ("five" "result-three"))))))))) "two" "three" map "four" "five") => ("result-one" "result-two" "result-three")
When reading json objects, jsown converts their content to the most lispy translation of what was in there. As such json's @false@ will be translated to nil, which coincidentally also be the translation of json's @[]@. When writing objects lisp's @nil@ is translated to the empty json list @[]@. You can write json's @false@ by writing lisp's keywords @:false@ or @:f@.(jsown:to-json '(:obj ("bingo" . 24.93) ("bang" 1 2 3 "foo" 4 5) ("foo" . "bar"))) => "{\"bingo\":24.93,\"bang\":[1,2,3,\"foo\",4,5],\"foo\":\"bar\"}"
(jsown:to-json (jsown:new-js ("items" nil) ("falseIsEmptyList" :f) ("success" t))) "{\"success\":true,\"falseIsEmptyList\":false,\"items\":[]}"
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
• The jsown system: |
Aad Versteden <madnificent@gmail.com>
Aad Versteden <madnificent@gmail.com>
MIT
Fast JSON parsing library. Mainly geared torwards fetching only a few keys of many objects, but efficient for other types of content too
1.0.1
jsown.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
• Lisp files: |
• The jsown.asd file: | ||
• The jsown/packages.lisp file: | ||
• The jsown/accessors.lisp file: | ||
• The jsown/reader.lisp file: | ||
• The jsown/writer.lisp file: |
Next: The jsown/packages<dot>lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
jsown.asd
jsown (system)
Next: The jsown/accessors<dot>lisp file, Previous: The jsown<dot>asd file, Up: Lisp files [Contents][Index]
Next: The jsown/reader<dot>lisp file, Previous: The jsown/packages<dot>lisp file, Up: Lisp files [Contents][Index]
packages.lisp (file)
jsown (system)
accessors.lisp
Next: The jsown/writer<dot>lisp file, Previous: The jsown/accessors<dot>lisp file, Up: Lisp files [Contents][Index]
accessors.lisp (file)
jsown (system)
reader.lisp
Previous: The jsown/reader<dot>lisp file, Up: Lisp files [Contents][Index]
reader.lisp (file)
jsown (system)
writer.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
• The jsown package: |
packages.lisp (file)
common-lisp
Definitions are sorted by export status, category, package, and then by lexicographic order.
• Exported definitions: | ||
• Internal definitions: |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
• Exported special variables: | ||
• Exported macros: | ||
• Exported compiler macros: | ||
• Exported functions: | ||
• Exported generic functions: | ||
• Exported classes: |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
value to emit when parsing a json empty list ’[]’
reader.lisp (file)
value to emit when parsing json’s ’false’
reader.lisp (file)
value to emit when parsing json’s ’null’
reader.lisp (file)
value to emit when parsing json’s ’true’
reader.lisp (file)
Next: Exported compiler macros, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
Iterates over the json key-value pairs
accessors.lisp (file)
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!")))))
accessors.lisp (file)
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.
reader.lisp (file)
creates a new empty object and fills it is per jsown-values
accessors.lisp (file)
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
reader.lisp (file)
Next: Exported functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
reader.lisp (file)
reader.lisp (file)
Next: Exported generic functions, Previous: Exported compiler macros, Up: Exported definitions [Contents][Index]
returns <value> as a boolean value (in jsown format)
writer.lisp (file)
returns <value> with nil being javascript’s null (in jsown format).
writer.lisp (file)
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.
reader.lisp (file)
Returns an empty object which can be used to build new objects upon
accessors.lisp (file)
Returns non-nil iff <object> has key <key>.
accessors.lisp (file)
Returns a list of all the keywords contained in the object
accessors.lisp (file)
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 "{}")
reader.lisp (file)
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.
reader.lisp (file)
Removes key from object.
accessors.lisp (file)
Converts an object in internal jsown representation to a string containing the json representation
writer.lisp (file)
Returns the value of the given key in object
accessors.lisp (file)
(setf val) (setf expander)
see (setf getf) and val
accessors.lisp (file)
val (function)
Next: Exported classes, Previous: Exported functions, Up: Exported definitions [Contents][Index]
Writes the given object to json in a generic way.
writer.lisp (file)
Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
describes a json object whos content is serialized already.
writer.lisp (file)
standard-object (class)
:content
content (generic function)
Previous: Exported definitions, Up: Definitions [Contents][Index]
• Internal constants: | ||
• Internal macros: | ||
• Internal compiler macros: | ||
• Internal functions: | ||
• Internal generic functions: | ||
• Internal structures: |
Next: Internal macros, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
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.
reader.lisp (file)
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.
reader.lisp (file)
Next: Internal compiler macros, Previous: Internal constants, Up: Internal definitions [Contents][Index]
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.
reader.lisp (file)
reader.lisp (file)
Next: Internal functions, Previous: Internal macros, Up: Internal definitions [Contents][Index]
reader.lisp (file)
Next: Internal generic functions, Previous: Internal compiler macros, Up: Internal definitions [Contents][Index]
Appends the given key to the object
accessors.lisp (file)
reader.lisp (file)
reader.lisp (file)
reader.lisp (file)
reader.lisp (file)
Makes a new buffer and ensures the string is of the correct type
reader.lisp (file)
Builds a character tree from a set of strings
reader.lisp (file)
Builds a tree from a range of lists and a function to compare its elements by
reader.lisp (file)
Returns t if <char> is found in <char-arr>, returns nil otherwise
reader.lisp (file)
reader.lisp (file)
Returns the current character the buffer is pointing to
reader.lisp (file)
Sets the pointer to the previous char in the buffer
reader.lisp (file)
Reads a character from the buffer and increases the index
reader.lisp (file)
reader.lisp (file)
Iterates a character-tree with the given character
Returns two values, being the new tree and whether or not this is an end-point.
reader.lisp (file)
returns non-nil iff we expect <object> to be a jsown object.
accessors.lisp (file)
Returns the list which represents the key-val pair in the json object
accessors.lisp (file)
writer.lisp (file)
writer.lisp (file)
reader.lisp (file)
Fancy filtering for jsown-parsed objects, functional implementation. look at jsown-filter for a working version.
reader.lisp (file)
Sets the mark of the buffer to the current character
reader.lisp (file)
Returns the current amount of characters in the marked piece of the buffer
reader.lisp (file)
Sets the pointer to the next char in the buffer
reader.lisp (file)
Sets the pointer to the next char in the buffer, ignores escaped characters (they start with a \) through
reader.lisp (file)
Does what next-char/ does, but returns nil if no char was skipped or t if a char was skipped.
reader.lisp (file)
writer.lisp (file)
Overwrites the given key’s value with value. Errors out if the key didn’t exist
accessors.lisp (file)
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 "
reader.lisp (file)
reader.lisp (file)
Adds the given key to the object at front
accessors.lisp (file)
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 ]
reader.lisp (file)
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
reader.lisp (file)
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
reader.lisp (file)
reads an object, starting with { and ending with } into a in internal jsown object
reader.lisp (file)
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
reader.lisp (file)
Reads an object from the buffer, but only when the key matches a key in the tree
reader.lisp (file)
Reads a value from the stream.
This searches for the first meaningful character, and delegates to the right function for that character
reader.lisp (file)
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 ]
reader.lisp (file)
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
reader.lisp (file)
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
reader.lisp (file)
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
reader.lisp (file)
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 "
reader.lisp (file)
Skips characters until <char> has been found. <char> is the last char which is skipped see: skip-until
reader.lisp (file)
What skip-to does, but with the ignoring of \
reader.lisp (file)
Skips characters until <char> has been found. <char> is NOT skipped See: skip-to
reader.lisp (file)
Skips characters until one of the characters in <char-arr> has been found. The character which was found is not read from the buffer.
reader.lisp (file)
What skip-until does, but with \ escaping
reader.lisp (file)
Skips a value from the stream.
This searches for the first meaningful character, and delegates to the right function for skipping that
reader.lisp (file)
Returns the content between index and mark for the current buffer result: (subseq buffer-string mark index))
reader.lisp (file)
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 #\
reader.lisp (file)
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
reader.lisp (file)
Does what subseq-until does, but does escaping too
reader.lisp (file)
Does what subseq-until/ does, but unescapes the returned string
reader.lisp (file)
reader.lisp (file)
Unescapes the given string based on JSOWN’s spec
reader.lisp (file)
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.
accessors.lisp (file)
writer.lisp (file)
writer.lisp (file)
writer.lisp (file)
Next: Internal structures, Previous: Internal functions, Up: Internal definitions [Contents][Index]
automatically generated reader method
writer.lisp (file)
Previous: Internal generic functions, Up: Internal definitions [Contents][Index]
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
reader.lisp (file)
structure-object (structure)
simple-string
""
buffer-string (function)
(setf buffer-string) (function)
fixnum
0
buffer-index (function)
(setf buffer-index) (function)
fixnum
0
buffer-mark (function)
(setf buffer-mark) (function)
Previous: Definitions, Up: Top [Contents][Index]
• Concept index: | ||
• Function index: | ||
• Variable index: | ||
• Data type index: |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
Jump to: | F J L |
---|
Jump to: | F J L |
---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
Jump to: | (
A B C D E F G I J K L M N O P R S T U V W |
---|
Jump to: | (
A B C D E F G I J K L M N O P R S T U V W |
---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
Jump to: | *
+
C I M S |
---|
Jump to: | *
+
C I M S |
---|
Previous: Variable index, Up: Indexes [Contents][Index]
Jump to: | B C J P S |
---|
Jump to: | B C J P S |
---|