Skip to content
FutureBlitz

    Install

    Import std.data.json

    std.data.json

    Reading and writing JSON.

    JSON, as RFC 8259 has it: Json.Read reads a document into a Value, and Json.Write writes a Value as one; JsonReader reads a document's tokens one at a time, in order, and JsonWriter writes a document a token at a time, so neither holds more than the text. Integers stay exact, as Int64s, or UInt64s past them; other numbers are Doubles. The runtime reads the text, over fast_float for its Doubles.

    std/data/json.fb

    Types

    JsonToken enum 

    Public Enum JsonToken

    What a JsonReader read.

    std/data/json.fb, line 34

    • END enum member #

      The document's end, after its value.

    • BEGIN_OBJECT enum member #

      An object's start.

    • END_OBJECT enum member #

      An object's end.

    • BEGIN_ARRAY enum member #

      An array's start.

    • END_ARRAY enum member #

      An array's end.

    • KEY enum member #

      A key of an object's.

    • STRING enum member #

      A string.

    • INT enum member #

      A number that's an integer an Int64 holds.

    • UINT enum member #

      An integer past an Int64's largest that a UInt64 holds.

    • DOUBLE enum member #

      Any other number.

    • BOOL enum member #

      true or false.

    • NULL enum member #

      null.

    JsonReader class 

    Public Class JsonReader

    Reads a JSON document's tokens, one each time Next is called, from text or from UTF-8 bytes, which it copies: an object's as BEGIN_OBJECT, then each KEY and its value, then END_OBJECT, and an array's as BEGIN_ARRAY, its values, and END_ARRAY. A byte order mark before the JSON is left out. It reads arrays and objects nested in each other up to depth deep.

    Examples

    Local reader = JsonReader(r"[1, 2, 3]")
Local sum: Int64 = 0
Local token = Try reader.Next()
While token != JsonToken.END
    If token == JsonToken.INT Then sum += reader.GetInt64()
    token = Try reader.Next()
End While

Expect(sum == 6)

    std/data/json.fb, line 79

    • @PanicsAtCaller Public New(text: String, depth: Int = DEPTH) constructor #

      A JsonReader of text, which nests up to depth deep. Panics unless depth is 1 or more.

    • @PanicsAtCaller Public New(bytes: UInt8[], depth: Int = DEPTH) constructor #

      A JsonReader of bytes, UTF-8 JSON, which nests up to depth deep.

    • Public Method Next(): JsonToken Throws ParseError method #

      The next token, END once the document's value is done, and END again after. Throws a ParseError where the text stops being JSON, with its line and column, each from 1: of SYNTAX for what can't be there, UNEXPECTED_END for text that ends early, and OUT_OF_RANGE for a number past a Double's range, or arrays and objects nested too deep.

    • @PanicsAtCaller Public Property Token: JsonToken property #

      The token Next gave last.

    • Public Property Depth: Int property #

      How many arrays and objects are open after the token: 0 for a document's lone value, 1 after its BEGIN_ARRAY or BEGIN_OBJECT and for each value in it, and 0 again after its END_ARRAY or END_OBJECT.

    • Public Property Line: Int property #

      The line, from 1, where the token starts.

    • Public Property Column: Int property #

      The column, from 1, in code points, where the token starts.

    • @PanicsAtCaller Public Method GetString(): String method #

      A KEY's or a STRING's text. Panics for another token.

    • @PanicsAtCaller Public Method GetInt64(): Int64 method #

      An INT's integer. Panics for another token.

    • @PanicsAtCaller Public Method GetUInt64(): UInt64 method #

      A UINT's integer, or an INT's that isn't negative. Panics for another token.

    • @PanicsAtCaller Public Method GetDouble(): Double method #

      A number as a Double: a DOUBLE's, or the nearest to an INT's or UINT's. Panics for another token.

    • @PanicsAtCaller Public Method GetBool(): Bool method #

      A BOOL token's value. Panics for another token.

    • Public Method Skip() Throws ParseError method #

      Reads past the value whose first token Next gave last, to its END_OBJECT or END_ARRAY when it's an object or an array. Throws as Next does.

    JsonWriter class 

    Public Class JsonWriter Implements Printable

    Writes a JSON document a token at a time: BeginObject, then each Key and its value, then EndObject; BeginArray, its values, then EndArray; or one value alone. With an indent of 0, the text is on one line with no spaces, and otherwise each value of an array or an object is on a line of its own, indented that many spaces more than what holds it, and a key's value is after ": ". Each method panics when its token can't come next, as a Key outside an object, or a second value after the document's, at its caller.

    Examples

    Local writer = JsonWriter()
writer.BeginObject()
writer.Key("name")
writer.WriteString("Ada")
writer.Key("scores")
writer.BeginArray()
writer.WriteInt(3)
writer.WriteInt(5)
writer.EndArray()
writer.EndObject()
Expect(writer.IsComplete)
Local written = Try Json.Read(writer.ToString())
Expect(written.Path("scores[1]")?.AsInt() == 5)

    std/data/json.fb, line 237

    • @PanicsAtCaller Public New(indent: Int = 0) constructor #

      A JsonWriter that indents by indent spaces a level, or writes on one line for 0. Panics when indent is below 0.

    • Public Property IsComplete: Bool property #

      Whether the document's value is all written.

    • @PanicsAtCaller Public Method BeginObject() method #

      Starts an object, whose keys and values come next. Panics where a value can't go.

    • @PanicsAtCaller Public Method EndObject() method #

      Ends the object that's open. Panics when the innermost open one is an array, or a key has no value.

    • @PanicsAtCaller Public Method BeginArray() method #

      Starts an array, whose values come next. Panics where a value can't go.

    • @PanicsAtCaller Public Method EndArray() method #

      Ends the array that's open. Panics when the innermost open one is an object.

    • @PanicsAtCaller Public Method Key(name: String) method #

      An object's next key, whose value comes next.

    • @PanicsAtCaller Public Method WriteString(value: String) method #

      Writes value as a string, in quotes, with JSON's escapes. Panics where a value can't go.

    • @PanicsAtCaller Public Method WriteInt(value: Int64) method #

      Writes value as a number. Panics where a value can't go.

    • @PanicsAtCaller Public Method WriteUInt(value: UInt64) method #

      Writes value as a number. Panics where a value can't go.

    • @PanicsAtCaller Public Method WriteDouble(value: Double) method #

      A Double, as the shortest text that reads back as it, with ".0" after one that would read as an integer, so it reads back as a DOUBLE. Panics for NaN or an infinity, which JSON doesn't have.

    • @PanicsAtCaller Public Method WriteBool(value: Bool) method #

      Writes value as true or false. Panics where a value can't go.

    • @PanicsAtCaller Public Method WriteNull() method #

      Writes null. Panics where a value can't go.

    • Public Method ToString(): String method #

      The JSON written so far.

    Json struct 

    Public Struct Json

    A document's Value, and a Value's document.

    Examples

    Local document = Try Json.Read(r"""
    {"name": "Ada", "langs": ["en", "fr"], "age": 36}
    """)
Expect(document.Path("langs[1]")?.AsString() == "fr")
Expect(document.Path("age")?.AsInt() == 36)
Expect((Try Json.Read(Json.Write(document))) == document)

    std/data/json.fb, line 431

    • @PanicsAtCaller Public Static Method Read(text: String, depth: Int = DEPTH): Value Throws ParseError static method #

      The Value of text's JSON: an object as an OBJECT, its keys in order, the last of a key that repeats where its first was, and an integer that fits an Int64 as an INT, one past an Int64's largest that fits a UInt64 as a UINT, and any other number as a DOUBLE. Throws a ParseError as JsonReader's Next does, and for arrays and objects nested past depth. Panics unless depth is 1 or more.

    • @PanicsAtCaller Public Static Method Read(bytes: UInt8[], depth: Int = DEPTH): Value Throws ParseError static method #

      The Value of UTF-8 bytes' JSON, as Read of text gives it.

    • @PanicsAtCaller Public Static Method Write(value: Value, indent: Int = 0): String static method #

      value as JSON, as JsonWriter writes it with indent: a DOUBLE with a point or an exponent, so it reads back as one, and BYTES, which JSON has no kind for, as a string of their base64 (RFC 4648's, with '=' padding). Panics for a DOUBLE that's NaN or an infinity, which JSON doesn't have, or an indent below 0.

    • @PanicsAtCaller Public Static Method Read<T>(text: String, depth: Int = DEPTH): T Throws ParseError static method #

      The T of text's JSON: Read's Value, made a T by Load<T>. Throws Read's ParseErrors, and Load's, whose Path says where in the document a value doesn't fit.

      Examples

      Struct Player
    Field Name: String
    Field Level: Int
End Struct

Local player = Try Json.Read<Player>(r"""
    {"Name": "Ada", "Level": 3}
    """)
Expect(player.Name == "Ada" && player.Level == 3)
Local back = Try Json.Read<Player>(Json.Write(player))
Expect(back.Name == "Ada")
    • @PanicsAtCaller Public Static Method Read<T>(bytes: UInt8[], depth: Int = DEPTH): T Throws ParseError static method #

      The T of UTF-8 bytes' JSON, as Read<T> of text gives it.

    • @PanicsAtCaller Public Static Method Write<T>(x: T, indent: Int = 0): String static method #

      x as JSON: Save's Value of it, written as Write writes a Value.

    Report an issue with this page or with FutureBlitz on GitHub.