#+TITLE: JSON meta library

* What is a meta library?
The purpose of this library is to be a portable shim for many JSON libraries.

* Why?
If one wants to write portable Scheme which does some JSON processing, one must either:

- Abandon hope of being portable, and depend on an implementation specific library.
- Use a portable JSON library which is redundant, and may conflict with other libraries that expect parsed JSON to be represented in a certain way.
- Write a bunch of cond-expands to act as a portability layer, and use different JSON libraries in different contexts.

This library aims to be an implementation of the latter which you can just plug in as a dependency, instead of writing your own.

* 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~.

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.

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~.
** 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.

~(json-list-ref lst i)~:
Returns the ~json-value?~ at index ~i~

** 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)~:
Convert ~lst~ to a ~list?~ of ~json-value?~.