JSON encoder/decoder ffi-bindings for PicoLisp
Common Lisp Makefile PicoLisp Shell
Latest commit e9f5e1d Sep 12, 2016 @aw Test with PicoLisp 16.6

README.md

JSON Encoder/Decoder for PicoLisp

GitHub release Build Status Dependency Dependency

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

picolisp-json

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

  1. Requirements
  2. Getting Started
  3. Usage
  4. Examples
  5. Testing
  6. Alternatives
  7. Contributing
  8. 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.

  1. Type make to pull and compile the Parson C Library.
  2. Include json.l in your project
  3. 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.

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

Copyright (c) 2015 Alexander Williams, Unscramble license@unscramble.jp