diff options
Diffstat (limited to 'README.org')
| -rw-r--r-- | README.org | 96 |
1 files changed, 91 insertions, 5 deletions
@@ -15,51 +15,137 @@ This library aims to be an implementation of the latter which you can just plug * API ** Constructors ~(json-object pairs ...)~: + Constructs a new JSON object. -pairs are ~pair?~ objects with a ~string?~ as the ~car~, and a ~json-value?~ as the ~cdr~. +~pairs~ are ~pair?~ objects with a ~string?~ as the ~car~, and a ~json-value?~ as the ~cdr~. An alist can be converted to a JSON object like so: ~(apply json-object alist)~ ~(json-list objs ...)~: + Constructs a new JSON list. -objs are ~json-value?~ objects. +~objs~ are ~json-value?~ objects. A list can be converted to a JSON list like so: ~(apply json-list some-list)~ ~json-null~: + This is not a constructor, but instead it is a value which represents null in JSON. ** Predicates ~(json-value? obj)~: + Returns true if ~obj~ is a value that can be serialized as JSON. This is true for values related to the constructors, and for numbers, strings, and booleans. ~(json-object? obj)~: + Returns true if ~obj~ is a value that can be serialized as a JSON object. Either the result of deserializing a string formatted as a JSON object, or from the ~json-object~ constructor. ~(json-list? obj)~: + Returns true if ~obj~ is a value that can be serialized as a JSON list. Either the result of deserializing a string formatted as a JSON list, or from the ~json-list~ constructor. ~(json-null? obj)~: + Returns true if ~obj~ is ~eq?~ to ~json-null~. + +~(json-object-contains-key? obj key)~: + +Returns true if ~obj~ contains the ~key~. ** Serialization ~(json->string obj)~: + Convert a ~json-value?~ to a JSON formatted ~string?~. ~(string->json str)~ + Converts a ~string?~ into a ~json-value?~ ** Selectors ~(json-object-ref obj key)~: + Returns the ~json-value?~ associated with ~key~ in ~obj~. -~key~ should be a ~string?~, and the behavior when ~obj~ does not contain ~key~ is currently undefined. +~key~ should be a ~string?~. + +The behavior when ~key~ is not found in ~obj~ can be controlled with the ~json-key-not-found~ parameter. +The value of ~json-key-not-found~ should be a procedure of no arguments, and the return value of the procedure is returned, if any exists. +The default behavior of ~json-key-not-found~ will return nothing, using ~(values)~. ~(json-list-ref lst i)~: -Returns the ~json-value?~ at index ~i~ + +Returns the ~json-value?~ at index ~i~. + +~(json-list-length lst)~: + +Returns the length of ~lst~. + +~(json-ref json ref refs ...)~: + +General JSON reference accessor. + +If ~json~ is a ~json-list?~ and ~ref~ is a ~number?~, get the element at that index of the list. + +If ~json~ is a ~json-object?~ and ~ref~ is a ~string?~, get the value associated with that key in the object. + +If there are more ~refs ...~, they are recursively applied. + ** Conversion ~(json-object->alist obj)~: + Convert ~obj~ to a ~list?~ of ~pair?~ where the ~car~ of each pair is a ~string?~ and the ~cdr~ is the associated ~json-value?~. -~(json-object->list lst)~: +~(json-list->list lst)~: + Convert ~lst~ to a ~list?~ of ~json-value?~. + +** Examples +#+begin_src scheme + (json-list->list (apply json-list lst)) ; => lst +#+end_src + +#+begin_src scheme + (json-object->alist (apply json-object alist)) ; => alist +#+end_src + +#+begin_src scheme + (json-null? (string->json "null")) ; => #t +#+end_src + +#+begin_src scheme + (json-object-contains-key? + (json-object '("a" . 5) + `("b" . ,(json-list 1 2 3))) + "a") ; => #t + + (json-object-contains-key? + (json-object '("a" . 5) + `("b" . ,(json-list 1 2 3))) + "c") ; => #f +#+end_src + +#+begin_src scheme + (json-ref + (json-object `("x" . ,(json-list "hello" "world"))) + "x" + 0) ; => "hello" +#+end_src + +#+begin_src scheme + (define-syntax case-values + (syntax-rules () + ((_ vals (pattern body1 body2 ...) ...) + (call-with-values (lambda () vals) (case-lambda (pattern body1 body2 ...) ...))))) + + (case-values (json-ref (json-object `("x" . ,(json-list "hello" "world"))) "x") + (() 'not-found) + ((x) (json-list? x))) ; => #t + + (case-values (json-ref (json-object `("x" . ,(json-list "hello" "world"))) "y") + (() 'not-found) + ((x) (json-list? x))) ; => not-found +#+end_src + +* Feedback +Please email me at: contact (at) robbyzambito (dot) me if you have any suggestions or would like for me to add support for another JSON library. |