Add json-object-contains-key?, json-list-length, and json-key-not-found.

Update README accordingly and with add examples.

1 files changed, 91 insertions, 5 deletions

diff --git a/README.org b/README.org
index 169e103..1c18542 100644
--- a/README.org
+++ b/README.org
@@ -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.