jason
(mostly) compile-time JSON encoding
"I don't care." -- Araq, 2020
cpp +/ nim-1.0arc +/ cpp +/ nim-1.3
Goals
Making some assumptions (ie. that our types aren't changing) allows...
- predictably fast performance
- predictably mild memory behavior
- predictably idiomatic API
- hard to misuse
It's fairly hard to misuse, but it's not fully optimized yet. In some cases, it's much faster than the standard json module. In a few, it's a little slower.
The main advantage is that you get JSON encoding of tuples, objects, and iterators "for free" -- no serialization to implement and no duplication of data.
Everything is type-checked, too, so there will be no runtime serialization exceptions.
And, if you want to implement custom serialization, it's now trivial to do so for individual types.
Usage
# an integer
echo 45.jason # 45
# a float
echo jason(5.0) # 5.0
# a bool
echo jason true # true
# an enum (see below for custom serialization overriding)
echo Two.jason # 2
# a string
echo jason"foo" # "foo"
# ref types are fine
echo jason((ref string) nil) # null
Tuples without named fields become JSON arrays. Tuples with named fields become JSON objects.
echo (1, 2, 3).jason # [1,2,3]
echo (cats: "meow", dogs: "woof").jason # {"cats":"meow","dogs":"woof"}
Objects are supported, with or without ref fields.
type
O = object
cats: string
dogs: int
q: ref O
let o = O(cats: "yuk", dogs: 2)
echo o.jason # {"cats":"yuk","dogs":2,"q":null}
Custom serialization is trivial; just implement jason for your type. No need to guess as to whether you've implemented all necessary serializers; if it compiles, you're golden.
type
B = object
x: int
y: string
C = seq[B]
let b = B(x: 3, y: "sup")
let c: C = @[ B(x: 1), B(x: 2), B(x: 3) ]
func jason(n: B): Json =
if n.x mod 2 == 0: jason"even"
else: jason"odd"
echo b.jason # "odd"
echo c.jason # ["odd","even","odd"]
Json is a proper type.
var n: string = jason"foo" # type error
var x: string = $"foo".jason # ok
var y = jason"foo" # ok
y.add "bif" # type error
More to come...
Installation
$ nimph clone disruptek/jason
or if you're still using Nimble like it's 2012,
$ nimble install https://github.com/disruptek/jason
Documentation
WIP
I'm going to try a little harder with these docs by using runnableExamples so the documentation demonstrates current usage examples and working tests despite the rapidly-evolving API.
See the documentation for the jason module as generated directly from the source.
Testing
There's a test and a benchmark under tests/; the benchmark requires criterion.
License
MIT
