openparser/json

openparser/json

Search:
Group by:

This module implements a JSON parser and serializer for Nim language.

It can convert Nim objects, tables and arrays to JSON strings and vice versa. It also provides compile-time options for customizing the serialization process.

This JSON implementation has a similar API to pkg/jsony but is designed to work with memory-mapped files and provide a more flexible and extensible serialization/deserialization mechanism.

Types

JsonOptions = ref object
  skipFields*: seq[string]   ## Fields to skip during serialization
Options for JSON serialization 
JsonParser = object
  prev*, curr*, next*: JsonToken
  currentField*: Option[string] ## The name of the current field being parsed, if applicable. This is set
                                ## before calling parseHook for a field value, allowing parseHooks to have
                                ## context about which field they are parsing
JsonToken = ref object
  kind*: JsonTokenKind
  value*: string
  line*, col*, pos*: int
JsonTokenKind = enum
  jtkEof = "<EOF>", jtkLBrace = "{", jtkRBrace = "}", jtkLBracket = "[",
  jtkRBracket = "]", jtkComma = ",", jtkColon = ":", jtkString = "<string>",
  jtkNumber = "<number>", jtkTrue = "<true>", jtkFalse = "<false>",
  jtkNull = "<null>"
JsonToken kinds for JSON parsing 
OpenParserJsonError = object of CatchableError

Consts

errorEndOfFile = "Unexpected EOF while parsing `$1`"
invalidToken = "Invalid token `$1`"
unexpectedChar = "Unexpected character `$1`"
unexpectedToken = "Unexpected token `$1`"
unexpectedTokenExpected = "Got `$1`, expected $2"

Procs

proc advance(parser: var JsonParser): JsonToken {.discardable,
    ...raises: [OpenParserJsonError, ValueError], tags: [], forbids: [].}
proc arrayToJson(v, valImpl: NimNode; opts: JsonOptions = nil): NimNode {.
    ...raises: [], tags: [], forbids: [].}
proc dumpHook(s: var string; v: char) {....raises: [], tags: [], forbids: [].}
proc dumpHook(s: var string; v: enum)
proc dumpHook(s: var string; v: JsonNode) {....raises: [], tags: [RootEffect],
    forbids: [].}
proc dumpHook(s: var string; val: bool) {....raises: [], tags: [], forbids: [].}
proc dumpHook(s: var string; val: float32 | float64)
proc dumpHook(s: var string; val: Integers)
proc dumpHook(s: var string; val: object)
proc dumpHook(s: var string; val: pointer) {....raises: [], tags: [], forbids: [].}
proc dumpHook(s: var string; val: string) {....raises: [], tags: [], forbids: [].}
proc dumpHook(s: var string; val: tuple)
proc dumpHook[K: string; V](s: var string; val: AnyTable[K, V])
proc dumpHook[N, T](s: var string; v: array[N, t[T]])
proc dumpHook[N, T](s: var string; v: array[N, T])
proc dumpHook[T: distinct](s: var string; v: T)
proc dumpHook[T](s: var string; arr: seq[T])
Converts a sequence of items to a JSON array string. 
proc dumpHook[T](s: var string; v: CritBitTree[T])
proc dumpHook[T](s: var string; v: Option[T])
proc dumpHook[T](s: var string; val: ref T)
proc dumpHook[T](s: var string; val: set[T])
proc error(l: var JsonLexer; msg: string) {.
    ...raises: [OpenParserJsonError, ValueError], tags: [], forbids: [].}
proc error(p: var JsonParser; msg: string) {.
    ...raises: [OpenParserJsonError, ValueError], tags: [], forbids: [].}
proc expectSkip(parser: var JsonParser; tkind: JsonTokenKind) {.
    ...raises: [OpenParserJsonError, ValueError], tags: [], forbids: [].}
proc fromJson(mapped: MemFile): JsonNode {.
    ...raises: [OpenParserJsonError, ValueError, Exception], tags: [RootEffect],
    forbids: [].}
Parse JSON directly from mapped memory. 
proc fromJson(str: string): JsonNode {....raises: [OpenParserJsonError, ValueError,
    Exception], tags: [RootEffect], forbids: [].}
Parse a JSON from str and returns the standard JsonNode 
proc fromJson[T](s: string; x: typedesc[T]): T
Provide a direct to object conversion from JSON string to Nim objects 
proc fromJsonFile(filename: string): JsonNode {.
    ...raises: [IOError, OSError, OpenParserJsonError, ValueError, Exception],
    tags: [RootEffect], forbids: [].}
Parse JSON from a memory-mapped file. 
proc fromJsonL(mapped: MemFile): JsonNode {.
    ...raises: [OpenParserJsonError, ValueError, Exception], tags: [RootEffect],
    forbids: [].}
Parse line-delimited JSON directly from mapped memory. 
proc fromJsonL(str: string): JsonNode {....raises: [OpenParserJsonError,
    ValueError, Exception], tags: [RootEffect], forbids: [].}
Parse line-delimited JSON from str and returns a JsonNode array 
proc fromJsonLFile(filename: string): JsonNode {.
    ...raises: [IOError, OSError, OpenParserJsonError, ValueError, Exception],
    tags: [RootEffect], forbids: [].}
Parse JSON-L from a memory-mapped file. 
proc isMapped(m: MemFile): bool {.inline, ...raises: [], tags: [], forbids: [].}
True when this MemFile currently has a valid mapped region. 
proc objectToJson(v, valImpl: NimNode; opts: JsonOptions = nil): NimNode {.
    ...raises: [], tags: [], forbids: [].}
proc openReadOnly(filename: string; allowRemap = false; mapFlags = cint(-1)): MemFile {.
    inline, ...raises: [IOError, OSError], tags: [], forbids: [].}
Convenience helper for read-only memory-mapped file opening. 
proc parseHook(parser: var JsonParser; v: var bool) {.
    ...raises: [OpenParserJsonError, ValueError], tags: [], forbids: [].}
proc parseHook(parser: var JsonParser; v: var JsonNode) {.
    ...raises: [Exception, OpenParserJsonError, ValueError, ValueError],
    tags: [RootEffect], forbids: [].}
A hook to parse a JSON value into a JsonNode 
proc parseHook(parser: var JsonParser; v: var string) {.
    ...raises: [OpenParserJsonError, ValueError], tags: [], forbids: [].}
proc parseHook[K: string; V](parser: var JsonParser; v: var AnyTable[K, V])
proc parseHook[T: distinct](parser: var JsonParser; v: var T)
A hook to parse distinct types by parsing their base type and then converting 
proc parseHook[T: enum](parser: var JsonParser; v: var T)
proc parseHook[T: float | float32 | float64](parser: var JsonParser; v: var T)
proc parseHook[T: Integers](parser: var JsonParser; v: var T)
proc parseHook[T: object](parser: var JsonParser; v: var T)
proc parseHook[T: ref object](parser: var JsonParser; v: var T)
A hook to parse ref object fields 
proc parseHook[T: tuple](parser: var JsonParser; v: var T)
proc parseHook[T](parser: var JsonParser; v: var Option[T])
A hook to parse a value wrapped in an Option type, treating null as None and any other value as Some(value). 
proc parseHook[T](parser: var JsonParser; v: var seq[T])
proc parseHook[T](parser: var JsonParser; v: var set[T])
proc skipValue(parser: var JsonParser) {.
    ...raises: [OpenParserJsonError, ValueError], tags: [], forbids: [].}
proc toJson[T](v: T; opts: JsonOptions = nil): string
Convert a Nim object to its JSON string representation using dump hooks. 
proc toJsonNode[T](v: T): JsonNode
Convert any Nim value (object, table, seq, etc.) to a JsonNode by serializing to a JSON string and parsing it back

Macros

macro toStaticJson(v: typed; opts: static JsonOptions = nil): untyped

Converts a Nim object to its JSON representation.

This macro uses compile-time reflection to inspect the structure of v and generate code that constructs a JSON string representation of it, mostly at compile time.

Templates

template ensureComma() {.inject.}
template skippable() {.pragma.}

Made with Nim. Generated: 2026-06-14 04:29:03 UTC