JSON Encoder/Decoder for PicoLisp

![Dependency](https://img.shields.io/badge/[deps] Parson-18761d99ff-ff69b4.svg) ![Dependency](https://img.shields.io/badge/[deps] picolisp--unit-v1.0.0-ff69b4.svg)

This library can be used to parse and serialize (encode/decode) JSON strings in PicoLisp.

Please read EXPLAIN.md to learn more about PicoLisp and this JSON library.

Requirements
Getting Started
Usage
Examples
Testing
Alternatives
Contributing
License

Requirements

PicoLisp 64-bit v3.1.9+
Git
UNIX/Linux development/build tools (gcc, make/gmake, etc..)

Getting Started

These FFI bindings require the Parson C library, compiled as a shared library.

Type make to pull and compile the Parson C Library.
Include json.l in your project
Try the examples below

Linking and Paths

Once compiled, the shared library is symlinked as:

.lib/libparson.so -> .modules/parson/HEAD/libparson.so

The json.l file searches for .lib/libparson.so, relative to its current directory.

Updating

To keep everything updated, type:

git pull && make clean && make

Usage

Only the following functions are exported publicly, and namespaced with (symbols 'json) (or the prefix: json~):

(decode arg1 arg2) parses a JSON string or file
- arg1 String: the JSON string or filename you want to decode
- arg2 Flag (optional): a flag (T or NIL) indicating to parse a file if set
(encode arg1) serializes a list into a JSON string
- arg1 List: a PicoLisp list which will be converted to a JSON string

Note: These functions are not namespace local symbols, which means they would redefine symbols with the same name in the 'pico namespace.

JSON-PicoLisp data type table

JSON	PicoLisp	Example
Number	Number	`25 <-> 25`
String	String	`"hello" <-> "hello"`
Null	Transient null Symbol	`null <-> 'null`
Boolean	Transient true or false Symbol	`true <-> 'true`
Array	List with T in cdar	`{"array":[1,2,3]} <-> '(("array" T 1 2 3))`
Object	Cons pair	`{"hello":"world"} <-> '(("hello" . "world"))`

Notes

A successful result will return a list. Failures return NIL.
Keys are in car, values are in cdr.
When the 2nd item in the list is T, the rest of the list represents a JSON array.
When the 2nd item in the list is a cons pair, it represents a JSON object.

Examples

(decode String)

pil +

(load "json.l")

(symbols 'json)

(decode "{\"Hello\":\"World\"}")

-> (("Hello" . "World"))

(decode Filename T)

The same function is used for parsing JSON strings and files. Simply append T as the last argument if you want to parse a file.

pil +

(load "json.l")

(symbols 'json)

(decode "test.json" T)

-> (("first" . "John")
    ("last" . "Doe")
    ("age" . 25)
    ("registered" . true)
    ("interests" T "Reading" "Mountain Biking")
    ("favorites" ("color" . "blue") ("sport" . "running"))
    ("utf string" . "lorem ipsum")
    ("utf-8 string" . "あいうえお")
    ("surrogate string" . "lorem�ipsum�lorem") )

(encode List)

pil +

(load "json.l")

(symbols 'json)

(encode '(("Hello" . "World")))

-> "{\"Hello\":\"World\"}"

Testing

This library now comes with full unit tests. To run the tests, type:

make check

Alternatives

The following are alternatives written in pure PicoLisp. They are limited by pipe/read syscalls.

JSON reader/writer by Alexander Burger.
JSON reader/writer by Henrik Sarvell.

Contributing

If you find any bugs or issues, please create an issue.

If you want to improve this library, please make a pull-request.

License

MIT License

tj64/picolisp-json