jsonutils

This module implements a hookable (de)serialization for arbitrary types. Design goal: avoid importing modules where a custom serialization is needed; see strtabs.fromJsonHook,toJsonHook for an example.

Example:

import std/[strtabs,json]
type Foo = ref object
  t: bool
  z1: int8
let a = (1.5'f32, (b: "b2", a: "a2"), 'x', @[Foo(t: true, z1: -3), nil], [{"name": "John"}.newStringTable])
let j = a.toJson
doAssert j.jsonTo(type(a)).toJson == j

Types

Joptions = object
  allowExtraKeys*: bool ## If `true` Nim's object to which the JSON is parsed is not required to
                        ## have a field for every JSON key.
  allowMissingKeys*: bool ## If `true` Nim's object to which JSON is parsed is allowed to have
                          ## fields without corresponding JSON keys.
  
Options controlling the behavior of fromJson.   Source Edit

Procs

proc fromJson[T](a: var T; b: JsonNode; opt = Joptions())
inplace version of jsonTo   Source Edit
proc jsonTo(b: JsonNode; T: typedesc): T:type
reverse of toJson   Source Edit
proc toJson[T](a: T): JsonNode
serializes a to json; uses toJsonHook(a: T) if it's in scope to customize serialization, see strtabs.toJsonHook for an example.   Source Edit
proc fromJsonHook[K, V](t: var (Table[K, V] | OrderedTable[K, V]);
                        jsonNode: JsonNode)

Enables fromJson for Table and OrderedTable types.

See also:

Example:

import tables, json
var foo: tuple[t: Table[string, int], ot: OrderedTable[string, int]]
fromJson(foo, parseJson("""
      {"t":{"two":2,"one":1},"ot":{"one":1,"three":3}}"""))
assert foo.t == [("one", 1), ("two", 2)].toTable
assert foo.ot == [("one", 1), ("three", 3)].toOrderedTable
  Source Edit
proc toJsonHook[K, V](t: (Table[K, V] | OrderedTable[K, V])): JsonNode

Enables toJson for Table and OrderedTable types.

See also:

Example:

import tables, json
let foo = (
  t: [("two", 2)].toTable,
  ot: [("one", 1), ("three", 3)].toOrderedTable)
assert $toJson(foo) == """{"t":{"two":2},"ot":{"one":1,"three":3}}"""
  Source Edit
proc fromJsonHook[A](s: var SomeSet[A]; jsonNode: JsonNode)

Enables fromJson for HashSet and OrderedSet types.

See also:

Example:

import sets, json
var foo: tuple[hs: HashSet[string], os: OrderedSet[string]]
fromJson(foo, parseJson("""
      {"hs": ["hash", "set"], "os": ["ordered", "set"]}"""))
assert foo.hs == ["hash", "set"].toHashSet
assert foo.os == ["ordered", "set"].toOrderedSet
  Source Edit
proc toJsonHook[A](s: SomeSet[A]): JsonNode

Enables toJson for HashSet and OrderedSet types.

See also:

Example:

import sets, json
let foo = (hs: ["hash"].toHashSet, os: ["ordered", "set"].toOrderedSet)
assert $toJson(foo) == """{"hs":["hash"],"os":["ordered","set"]}"""
  Source Edit
proc fromJsonHook[T](self: var Option[T]; jsonNode: JsonNode)

Enables fromJson for Option types.

See also:

Example:

import options, json
var opt: Option[string]
fromJsonHook(opt, parseJson("\"test\""))
assert get(opt) == "test"
fromJson(opt, parseJson("null"))
assert isNone(opt)
  Source Edit
proc toJsonHook[T](self: Option[T]): JsonNode

Enables toJson for Option types.

See also:

Example:

import options, json
let optSome = some("test")
assert $toJson(optSome) == "\"test\""
let optNone = none[string]()
assert $toJson(optNone) == "null"
  Source Edit
proc fromJsonHook(a: var StringTableRef; b: JsonNode) {...}{.
    raises: [ValueError, KeyError, JsonKindError], tags: [].}

Enables fromJson for StringTableRef type.

See also:

  • toJsonHook proc<#toJsonHook,StringTableRef>`_

Example:

import strtabs, json
var t = newStringTable(modeCaseSensitive)
let jsonStr = """{"mode": 0, "table": {"name": "John", "surname": "Doe"}}"""
fromJsonHook(t, parseJson(jsonStr))
assert t[] == newStringTable("name", "John", "surname", "Doe",
                             modeCaseSensitive)[]
  Source Edit
proc toJsonHook(a: StringTableRef): JsonNode {...}{.raises: [], tags: [].}

Enables toJson for StringTableRef type.

See also:

  • fromJsonHook proc<#fromJsonHook,StringTableRef,JsonNode>`_

Example:

import strtabs, json
let t = newStringTable("name", "John", "surname", "Doe", modeCaseSensitive)
let jsonStr = """{"mode": "modeCaseSensitive",
                      "table": {"name": "John", "surname": "Doe"}}"""
assert toJson(t) == parseJson(jsonStr)
  Source Edit