v0.4.0
Data formats · Lesson 21.2

Writing JSON

Source
Build a JSON value by hand, write it compact and pretty with WriteValue, parse the output back to the same text, and see a number JSON cannot spell refused.

Writing JSON is the parse lesson run backwards: a tree of JsonValues goes in, text comes out. The tree can come from Parse, or — as here — be built by hand, one value at a time. This lesson builds a small document, writes it two ways, and proves the writing is faithful by reading the output back.

import Json::{ JsonError, JsonStyle, JsonValue, Parse, WriteValue };
import Text::{ FormatError, String, StringBuilder, TextError, TextWriter };

Building a tree by hand

Each kind has a constructor: JsonValue::Text, Number, Boolean, Null, Array and Object. Containers start empty; Push appends to an array and Insert adds a member to an object:

var tags = JsonValue::Array(allocator);
try tags.Push(JsonValue::Text(allocator, "fast"));
try tags.Push(JsonValue::Number(allocator, "2.50"));
var root = JsonValue::Object(allocator);
try root.Insert(String::FromBytes(allocator, "name"), JsonValue::Text(allocator, "Rux"));
try root.Insert(String::FromBytes(allocator, "quote"),
            JsonValue::Text(allocator, "say \"hi\"\n"));
try root.Insert(String::FromBytes(allocator, "tags"), move tags);
try root.Insert(String::FromBytes(allocator, "license"), JsonValue::Null(allocator));

Four things to notice:

  • Text is copied into the tree. Text and String::FromBytes copy their bytes into memory from the allocator, and they throw a TextError when the bytes are not valid UTF-8.
  • A number is given as text. "2.50" stays 2.50, exactly as written, the same way a parsed number keeps its text. Number throws JsonError::MalformedNumber for text that is not a JSON number.
  • The containers check their kind. Push into a value that is not an array, or Insert into one that is not an object, throws JsonError::WrongKind.
  • Values are move-only. A JsonValue owns everything under it, so it cannot be copied. Push and Insert take ownership of what they are given, and handing over the finished tags array is an explicit move: move tags. After that line tags is gone, and the array lives on inside root.

So almost every line can throw, and each one is marked with try. One try covers the whole expression to its right, so try tags.Push(JsonValue::Text(allocator, "fast")) marks both the Text call and the Push. Main is declared throws (TextError | FormatError | JsonError) — an error sum — so plain try passes a failure of any of the three kinds on, and a throwing Main turns it into the program's exit status.

Writing it out

WriteValue writes a tree into any TextWriter:

WriteValue(writer, value, style) throws FormatError

Written points it at a StringBuilder, so the text can be kept, measured and parsed again, and hands the result back as a String the caller owns:

func Written(allocator: Allocator, value: &JsonValue, style: JsonStyle) -> String throws FormatError {
    var builder = StringBuilder(allocator);
    let sink: &var TextWriter = builder;
    try WriteValue(sink, value, style);
    return builder.TakeString();
}

JsonStyle chooses the layout:

StyleLayoutSize of this documentFor
JsonStyle::Compact()no whitespace at all73 bytesa wire, a file
JsonStyle::Pretty()one value per line, two-space indent103 bytesa person

Either way the writer escapes exactly what JSON requires inside strings and nothing more: the quote's " and its newline come out as \" and \n.

The round trip

A writer is only trustworthy if what it writes reads back as the same thing. The program parses the pretty text and writes it compact again. A failed parse here is handled on the spot by the catch arms, which print the reason and leave Main:

let again = try Parse(allocator, pretty.View().Bytes()) catch {
    reason => {
        PrintLine("the written text did not parse: {}", reason);
        return;
    }
};
let rewritten = try Written(allocator, again, JsonStyle::Compact());
PrintLine("round trip gives the same text: {}", rewritten.View().Equals(compact.View()));
flowchart LR
    tree["Tree built<br/>by hand"] -- "`Compact`" --> c1["compact text"]
    tree -- "`Pretty`" --> p["pretty text"]
    p -- "`Parse`" --> tree2["Tree read back"]
    tree2 -- "`Compact`" --> c2["compact text"]
    c2 -. "the same bytes as" .-> c1

The layout was only presentation, so the same 73 bytes come back — including 2.50, which did not become 2.5, because a number keeps the text it was written with.

What JSON cannot say

JSON has no spelling for NaN or infinity. A number with the text "NaN" is refused as soon as it is made, so it never reaches the tree and is never written out as something invented. The try block sees two kinds of error — JsonError from Number, FormatError from Written — so its arms take each type in turn:

try {
    let notANumber = JsonValue::Number(allocator, "NaN");
    let text = Written(allocator, notANumber, JsonStyle::Compact());
    PrintLine("wrote {}", text.View());
} catch {
    _: JsonError => PrintLine("NaN refused: not a JSON number"),
    error: FormatError => PrintLine("NaN not written: {}", error)
}

The first arm runs, and the program prints NaN refused: not a JSON number.

The program

The whole lesson is one package in the Examples repository. Its comments explain every step.

Src/Main.rux
// Writing JSON is the parse lesson run backwards: a tree of `JsonValue`s goes in, text comes
// out. The tree can come from `Parse` or be built by hand, and `WriteValue` writes it into any
// `TextWriter` — a StringBuilder here, so the text can be kept and parsed again.
//
//     WriteValue(writer, value, style) throws FormatError
//
// `JsonStyle` chooses the layout. `Compact()` writes no whitespace at all, for a document going
// over a wire; `Pretty()` indents by two spaces, for a person. Either way the writer escapes
// exactly what JSON requires inside strings, and nothing more.
import Allocator::{ Allocator, SystemAllocator };
import Io::PrintLine;
import Json::{ JsonError, JsonStyle, JsonValue, Parse, WriteValue };
import Text::{ FormatError, String, StringBuilder, TextError, TextWriter };

// Writes `value` in `style` and hands the text back as a String the caller owns.
func Written(allocator: Allocator, value: &JsonValue, style: JsonStyle) -> String throws FormatError {
    var builder = StringBuilder(allocator);
    let sink: &var TextWriter = builder;
    try WriteValue(sink, value, style);
    return builder.TakeString();
}

func Main() throws (TextError | FormatError | JsonError) {
    let allocator = SystemAllocator();

    // Building by hand. Values are move-only: `Push` and `Insert` take ownership of what they
    // are given, and a member's name is an owned String. `Push` into a value that is not an
    // array, or `Insert` into one that is not an object, throws `JsonError::WrongKind`.
    var tags = JsonValue::Array(allocator);
    try tags.Push(JsonValue::Text(allocator, "fast"));
    try tags.Push(JsonValue::Number(allocator, "2.50"));
    var root = JsonValue::Object(allocator);
    try root.Insert(String::FromBytes(allocator, "name"), JsonValue::Text(allocator, "Rux"));
    try root.Insert(String::FromBytes(allocator, "quote"),
                JsonValue::Text(allocator, "say \"hi\"\n"));
    try root.Insert(String::FromBytes(allocator, "tags"), move tags);
    try root.Insert(String::FromBytes(allocator, "license"), JsonValue::Null(allocator));

    let compact = try Written(allocator, root, JsonStyle::Compact());
    let pretty = try Written(allocator, root, JsonStyle::Pretty());
    PrintLine("compact, {} bytes:\n{}", compact.Length(), compact.View());
    PrintLine("pretty, {} bytes:\n{}", pretty.Length(), pretty.View());

    // The round trip: parse the pretty text and write it compact again. The layout was only
    // presentation, so the same bytes come back. A number keeps the text it was written with,
    // which is why `2.50` did not become `2.5`.
    let again = try Parse(allocator, pretty.View().Bytes()) catch {
        reason => {
            PrintLine("the written text did not parse: {}", reason);
            return;
        }
    };
    let rewritten = try Written(allocator, again, JsonStyle::Compact());
    PrintLine("round trip gives the same text: {}", rewritten.View().Equals(compact.View()));

    // JSON cannot spell NaN or infinity, so a number with that text is refused as soon as it is
    // made, and never written out as something invented. The `try` block sees both errors, so
    // its arms take each type in turn.
    try {
        let notANumber = JsonValue::Number(allocator, "NaN");
        let text = Written(allocator, notANumber, JsonStyle::Compact());
        PrintLine("wrote {}", text.View());
    } catch {
        _: JsonError => PrintLine("NaN refused: not a JSON number"),
        error: FormatError => PrintLine("NaN not written: {}", error)
    }
}

Besides Io, its Rux.toml lists Allocator, Json and Text under [Dependencies].

Run it

cd Examples/DataFormats/JsonWrite
rux run
compact, 73 bytes:
{"name":"Rux","quote":"say \"hi\"\n","tags":["fast",2.50],"license":null}
pretty, 103 bytes:
{
  "name": "Rux",
  "quote": "say \"hi\"\n",
  "tags": [
    "fast",
    2.50
  ],
  "license": null
}
round trip gives the same text: true
NaN refused: not a JSON number

Common mistakes

Try it yourself

  1. Add a boolean member, "beta": true, with JsonValue::Boolean(allocator, true). How many bytes is the compact text now?
  2. Build a nested object — say "author": {"name": "Ada"} — and look at how Pretty() indents it.
  3. Try "Infinity" and "01" instead of "NaN". Are they refused too?
  4. Insert never replaces: insert "name" a second time and write the tree. What does Parse say when it reads that text back?
  5. Parse the document from the JSON lesson and write it out with Pretty().

Learn more

  • JSON — reading a document into the tree this lesson writes
  • Move — what move does, and why a JsonValue cannot be copied
  • String builder — the TextWriter that collects the text
  • Error sum — one throwing Main for three kinds of error
  • Passing errors on in the Rux Reference
  • Notes — a checkpoint project that saves a to-do list as JSON and loads it back