Common Lisp PicoLisp Makefile Shell
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

JSON Encoder/Decoder for PicoLisp

GitHub release Build Status Dependency

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


NEW: Please read to learn more about PicoLisp and this (v3) JSON library.

Please read to learn more about PicoLisp and the older (v2) JSON library.

  1. Requirements
  2. Getting Started
  3. Usage
  4. Examples
  5. Testing
  6. Alternatives
  7. Contributing
  8. License


  • PicoLisp 32-bit or 64-bit v3.1.11+
  • Tested up to PicoLisp v17.12

Getting Started

This library has been rewritten in pure PicoLisp and contains no external dependencies.

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

  1. Include json.l in your project
  2. Try the examples below


Note: Namespaces do not work with versions of PicoLisp >= 17.3.4, please set the environment variable PIL_NAMESPACES=false (this may change in the future).

Only the following functions are exported publicly:

  • (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"))


  • To disallow duplicate Object keys: (on *Json_prevent_duplicate_keys). Default allows duplicate Object keys.
  • A successful result will return a list.
  • Failures return NIL, store the error message in *Msg, and print the error message to STDERR (standard error).
  • 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.
  • Supports Unicode characters as "\uNNNN" where N is a hexadecimal digit.

JSON Specification

This library conforms to the ECMA-404 The JSON Data Interchange Standard, except for the following semantic exceptions:

  • [Numbers] Scientific (floating point, fractional, exponential) numbers (ex: 3.7e-5) are not accepted. They must be provided as strings (ex: "3.7e-5").


(decode String)

(load "json.l")

(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.

(load "json.l")

(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)

(load "json.l")

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

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

(decode InvalidString)

(decode "{\"Hello\":invalid}")
"Invalid Object 'invalid', must be '[' OR '{' OR string OR number OR true OR false OR null"

-> NIL


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

make check


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


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

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


MIT License

Copyright (c) 2015-2018 Alexander Williams, Unscramble