You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Alex Williams 929a7841de
Build using v2 of the picolisp-action
4 months ago
.github/workflows Build using v2 of the picolisp-action 4 months ago
test Add additional unit test with empty array 1 year ago
.gitignore Kill git submodules with 🔥. Related to #2 5 years ago Add fix for issue #19 1 year ago Add new updated 3 years ago Fix typo in EXPLAIN document 1 year ago
LICENSE Support for PicoLisp 20.6 5 months ago
Makefile Update Makefile to test with 'picolisp-unit' v3.0.0 1 year ago Run tests with pil21 4 months ago Add license to 5 years ago
json.l Support for PicoLisp 20.6 5 months ago
module.l Support for PicoLisp 20.6 5 months ago
test.json Add Unit Tests and .travis.yml for automated build testing 5 years ago
test.l Remove support for PicoLisp namespaces, adjust tests, rename internal functions 1 year ago
test2.json Fix for invalid parsing of empty arrays. Closes #6 3 years ago
test3.json Fix for invalid parsing of empty arrays. Closes #6 3 years ago
test4.json Fix invalid parsing of string with caret. #10 2 years ago
test5.json Fix invalid encoding of control characters. #11 2 years ago
test6.json Fix Invalid encoding of quote and solidus. #12 2 years ago
test7.json Fixes #13 - Invalid encoding of control characters 0x01-0x1F. 2 years ago

JSON Encoder/Decoder for PicoLisp

GitHub release Dependency Build status

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. Changelog
  9. License


  • PicoLisp 32-bit v3.1.11 to v20.6 (tested)
  • PicoLisp 64-bit v17.12 to v20.6 (tested)
  • PicoLisp 64-bit pil21 (tested)

BREAKING CHANGE since v4.0.0: Namespaces have been completely removed, and all function names are now prefixed with json- (see Changelog).

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


Public functions:

  • (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
  • (json-encode arg1) serializes a list into a JSON string
    • arg1 List: a PicoLisp list which will be converted to a JSON string

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").


(json-decode String)

(load "json.l")

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

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

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

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

(json-encode List)

(load "json.l")

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

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

(json-decode InvalidString)

(json-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-2020 Alexander Williams, Unscramble