aowlspt/json

Source: aowl/src/aowlspt/json.nim — 701 lines.

Reading JSON, for mods.

let name = body.field("Info.Nickname").asText let n = body.field("items").count for it in body.field("items").each: echo it.field("_id").asText

A mod on either side spends most of its time reading a document it did not build: a request body, a template out of the database, its own saved state. Without this it would either hand-scan strings or pull in a parser, and the first is what produces the class of bug where a nested "_id" is mistaken for the outer one.

It scans; it does not build a tree. A JsonRef is a pair of offsets into text somebody else owns, so field costs a walk of the document and nothing else — no allocation, no copy, and no lifetime to think about beyond the text it came from. That is the right trade for the access pattern here (a handful of paths out of each body) and the wrong one for walking a 40MB item table field by field, which is what count/each exist to avoid needing.

Paths are dotted, with [n] for array elements:

"Info.Nickname" "items[0]._id" "data[2].Slots[1]"

A key containing a dot is reachable with child, one step at a time. That is deliberate: an escaping rule inside the path syntax would be one more thing to get wrong at a call site that reads fine. Error semantics: field, child, and at return notFound in two cases: (1) a step in the path does not exist, or (2) the path navigation was incorrect (mismatched braces, reached array boundary, etc). The API does not distinguish these two cases. Callers should validate document structure before relying on specific paths; use exists() to check if a reference was found. Reading a notFound ref is safe (returns empty string or default values) and will not crash, but confidently reading a default value as if it were the actual data is a silent failure. This is intentional: distinguishing "absent" from "mis-navigated" would require a three-value result type, making every call site more verbose.

Types

JsonRef

  JsonRef* = object
    text*: string
    first*: int   ## index of the value's first character
    last*: int    ## index of its last character, inclusive
    found*: bool

A view of one JSON value inside text. found distinguishes "the path is not there" from "the path is there and holds null", which is a distinction the game's own bodies rely on.

aowl/src/aowlspt/json.nim:42

Member

  Member* = object
    name*: string
    value*: string   ## the member's value as raw JSON

aowl/src/aowlspt/json.nim:511

Doc

  Doc* = object
    fields*: seq[Member]
    ok*: bool

A JSON object, taken apart for editing. ok is false when the text was not an object -- reported rather than raised, because the text usually came from a request body and a malformed one is an answer to give, not a crash to take.

aowl/src/aowlspt/json.nim:515

List

  List* = object
    items*: seq[string]
    ok*: bool

A JSON array, taken apart for editing. Elements stay as raw text.

aowl/src/aowlspt/json.nim:523

Routines

notFound

func notFound*(): JsonRef

aowl/src/aowlspt/json.nim:51

raw

proc raw*(j: JsonRef): string

The value exactly as it appears, "quotes" and all.

aowl/src/aowlspt/json.nim:164

exists

proc exists*(j: JsonRef): bool

aowl/src/aowlspt/json.nim:170

isNull

proc isNull*(j: JsonRef): bool

aowl/src/aowlspt/json.nim:172

isText

proc isText*(j: JsonRef): bool

aowl/src/aowlspt/json.nim:176

isObject

proc isObject*(j: JsonRef): bool

aowl/src/aowlspt/json.nim:180

isArray

proc isArray*(j: JsonRef): bool

aowl/src/aowlspt/json.nim:184

asText

proc asText*(j: JsonRef; default: string = ""): string

A string value, unescaped. A non-string value comes back as written, so reading a number as text gives "42" rather than the empty string.

aowl/src/aowlspt/json.nim:188

asFloat

proc asFloat*(j: JsonRef; default: float = 0.0): float

aowl/src/aowlspt/json.nim:198

asInt

proc asInt*(j: JsonRef; default: int = 0): int

aowl/src/aowlspt/json.nim:251

asBool

proc asBool*(j: JsonRef; default: bool = false): bool

aowl/src/aowlspt/json.nim:255

child

proc child*(j: JsonRef; key: string): JsonRef

One member of an object, by exact key. The step field is built from, and the way to reach a key that contains a dot.

aowl/src/aowlspt/json.nim:264

count

proc count*(j: JsonRef): int

The number of elements in an array, or of members in an object. Zero for anything else, including a value that is not there.

aowl/src/aowlspt/json.nim:304

at

proc at*(j: JsonRef; index: int): JsonRef

One element of an array. Out of range is notFound, not a crash: an index from a request body is not something a mod should have to bounds-check before it can read it.

aowl/src/aowlspt/json.nim:340

keys

proc keys*(j: JsonRef): seq[string]

The member names of an object, in document order.

aowl/src/aowlspt/json.nim:372

each

proc each*(j: JsonRef): seq[JsonRef]

Every element of an array, as views. Built once so a loop over it is a walk of a sequence rather than a rescan of the document per index -- at in a loop is quadratic and this is the reason not to write that.

aowl/src/aowlspt/json.nim:403

whole

proc whole*(text: string): JsonRef

The document itself, as a value.

aowl/src/aowlspt/json.nim:434

field

proc field*(j: JsonRef; path: string): JsonRef

A dotted path from this value. An empty path is the value itself.

aowl/src/aowlspt/json.nim:474

field

proc field*(text, path: string): JsonRef

A dotted path from a document.

aowl/src/aowlspt/json.nim:493

members

proc members*(j: JsonRef): seq[Member]

aowl/src/aowlspt/json.nim:528

parseObject

proc parseObject*(text: string): Doc

aowl/src/aowlspt/json.nim:565

parseObject

proc parseObject*(j: JsonRef): Doc

aowl/src/aowlspt/json.nim:571

newDoc

proc newDoc*(): Doc

aowl/src/aowlspt/json.nim:576

has

proc has*(d: Doc; name: string): bool

aowl/src/aowlspt/json.nim:578

getRaw

proc getRaw*(d: Doc; name: string): string

aowl/src/aowlspt/json.nim:584

get

proc get*(d: Doc; name: string): JsonRef

aowl/src/aowlspt/json.nim:590

escapeText

proc escapeText*(s: string): string

The JSON string escapes. Present here as well as in aowlspt/server because a client-side mod editing a document must not have to import the server API to do it.

aowl/src/aowlspt/json.nim:596

quoted

proc quoted*(s: string): string

aowl/src/aowlspt/json.nim:617

setRaw

proc setRaw*(d: var Doc; name, rawValue: string)

Sets a member, keeping its position if it is already there. Position matters less than it looks: it keeps a diff of two saved profiles readable, which is the difference between finding a bug and re-reading the whole file.

aowl/src/aowlspt/json.nim:619

setText

proc setText*(d: var Doc; name, value: string)

aowl/src/aowlspt/json.nim:629

setNumber

proc setNumber*(d: var Doc; name: string; value: int)

aowl/src/aowlspt/json.nim:630

setNumber

proc setNumber*(d: var Doc; name: string; value: float)

aowl/src/aowlspt/json.nim:631

setBool

proc setBool*(d: var Doc; name: string; value: bool)

aowl/src/aowlspt/json.nim:632

remove

proc remove*(d: var Doc; name: string)

aowl/src/aowlspt/json.nim:635

text

proc text*(d: Doc): string

aowl/src/aowlspt/json.nim:642

parseArray

proc parseArray*(text: string): List

aowl/src/aowlspt/json.nim:651

parseArray

proc parseArray*(j: JsonRef): List

aowl/src/aowlspt/json.nim:661

newList

proc newList*(): List

aowl/src/aowlspt/json.nim:670

len

proc len*(l: List): int

aowl/src/aowlspt/json.nim:672

at

proc at*(l: List; index: int): JsonRef

aowl/src/aowlspt/json.nim:674

add

proc add*(l: var List; rawValue: string)

aowl/src/aowlspt/json.nim:679

add

proc add*(l: var List; d: Doc)

aowl/src/aowlspt/json.nim:680

replaceAt

proc replaceAt*(l: var List; index: int; rawValue: string)

aowl/src/aowlspt/json.nim:682

removeAt

proc removeAt*(l: var List; index: int)

aowl/src/aowlspt/json.nim:686

text

proc text*(l: List): string

aowl/src/aowlspt/json.nim:695